Event ‣ open - chung-leong/zigar GitHub Wiki

Occurs when a system call is made to open a file or directory.

Usage

const std = @import("std");
pub const open = std.posix.open;
pub const write = std.posix.write;
pub const close = std.posix.close;

import { __zigar, close, open, write } from './event-open-example-1.zig';
const { on } = __zigar;

const array = [];

on('open', (evt) => {
  console.log(evt);
  return array;
})

const fd = open('/var/mushroom/kingdom/mario.txt', { ACCMODE: 'WRONLY' }, 0o666);
write(fd, 'This is a test');
close(fd);

console.log(array);
console.log(new TextDecoder().decode(array[0]));

{
  parent: null,
  path: 'var/mushroom/kingdom/mario.txt',
  rights: { write: true },
  flags: { symlinkFollow: true }
}
[
  Uint8Array(14) [
     84, 104, 105, 115, 32,
    105, 115,  32,  97, 32,
    116, 101, 115, 116
  ]
]
This is a test

In the absence of a listener for 'stat', an 'open' event will occur when stat() is called:

const std = @import("std");

pub fn stat(path: [*:0]const u8) !std.c.Stat {
    var info: std.c.Stat = undefined;
    if (std.c.stat(path, &info) != 0) return error.UnableToStat;
    return info;
}

import { __zigar, stat } from './event-open-example-2.zig';
const { on } = __zigar;

on('open', (evt) => {
  console.log(evt);
  return new Uint8Array(16);
});

const info = stat('/var/mushroom/kingdom/mario.txt');
console.log(info.valueOf());

{
  parent: null,
  path: 'var/mushroom/kingdom/mario.txt',
  rights: {},
  flags: { symlinkFollow: true, dryrun: true }
}
{
  dev: 0n,
  ino: 1n,
  nlink: 1,
  mode: 32774,
  uid: 0,
  gid: 0,
  __pad0: 0,
  rdev: 0n,
  size: 16n,
  blksize: 0,
  blocks: 0n,
  atim: { sec: 0, nsec: 0 },
  mtim: { sec: 0, nsec: 0 },
  ctim: { sec: 0, nsec: 0 },
  __unused: [ 0, 0, 0 ]
}

Event fields:

• parent: object
  The parent directory, if the event is triggered by a call to openat(), std.fs.Dir.openFile(), or std.fs.Dir.openDir(). It's null when an absolute path is used to reference the file.
• path: string
  Relative path to the file or directory. No leading slash even when an absolute path is used.
• rights: { read: boolean, write: boolean, readdir: boolean }
  Rights requested. Both readdir and read may be set at the same time.
• flags: { symlinkFollow: boolean, create: boolean, directory: boolean, exclusive: boolean, truncate: boolean, append: boolean, dsync: boolean, nonblock: boolean, rsync: boolean, sync: boolean, dryrun: boolean }
  Flags for the operation. directory is not guaranteed to be present when opening a directory. dryrun indicates the event is triggered by a call to stat().

Return value:

object | false | undefined
The object should have either a file or a directory or something that automatically get converted into either one:

• string
• array
• Blob
• Map
• Uint8Array
• ReadableStreamDefaultReader
• WritableStreamDefaultWriter

A return value of false means the operation failed. undefined means the listener declined to handle the event, allowing the operation to be handled by the actual file system.

Note:

The callback function can be async, provided that it's never invoked in the main thread. The same constraint to the returned object. A Uint8Array can be read synchronously, for example, and is therefore usuable in the main thread, whereas a Blob is not.

The mode parameter of open() is absent from the event object.

---

Events | File interface | Directory interface