Event ‣ stat - chung-leong/zigar GitHub Wiki

Occurs when a system call is made to obtain a file's size and other information.

Usage

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-stat-example-1.zig';
const { on } = __zigar;

on('stat', (evt) => {
  console.log(evt);
  return { size: 1234, ctime: 12340000000, mtime: 45670000000 };
});

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

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

Using a file descriptor:

const std = @import("std");
pub const utimes = std.c.futimes;

pub fn getStat(path: [:0]const u8) !std.c.Stat {
    const fd = try std.posix.open(path, .{}, 0);
    defer std.posix.close(fd);
    var info: std.c.Stat = undefined;
    if (std.c.fstat64(fd, &info) != 0) return error.UnableToSetTimes;
    return info;
}

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

on('open', (evt) => {
  return new Uint8Array(16);
});
on('stat', (evt) => {
  console.log(evt);
  return { size: 1234, ctime: 12340000000, mtime: 45670000000 };
});

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

{
  parent: null,
  path: 'var/mushroom/kingdom/mario.txt',
  target: Uint8Array(16) [
    0, 0, 0, 0, 0, 0,
    0, 0, 0, 0, 0, 0,
    0, 0, 0, 0
  ],
  flags: {}
}
{
  dev: 0n,
  ino: 1n,
  nlink: 1,
  mode: 6,
  uid: 0,
  gid: 0,
  __pad0: 0,
  rdev: 0n,
  size: 1234n,
  blksize: 0,
  blocks: 0n,
  atim: { sec: 0, nsec: 0 },
  mtim: { sec: 45, nsec: 670000000 },
  ctim: { sec: 12, nsec: 340000000 },
  __unused: [ 0, 0, 0 ]
}

Event fields:

• parent: object
  The parent directory, if the event is triggered by a call to fstatat() or if the file descriptor was obtained using openat(). It's null when an absolute path is used to reference the file.
• target: object The object previously returned by the open listener. Present only when event is triggered by a call to fstat().
• path: string
• flags: { symlinkFollow: boolean }

Return value:

object | false | undefined
The object could have the following fields:

• ino
  The file's inode number (default = 1)
• type
  'unknown', 'blockDevice', 'characterDevice', 'directory', 'file', 'socketDgram', 'socketStream', or 'symbolicLink' (default = 'unknown')
• size
  File size (default = 0)
• atime
  Last-accessed time in nanoseconds (default = 0)
• mtime
  Last-modified time in nanoseconds (default = 0)
• ctime
  Creation time in nanoseconds (default = 0)

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:

You usually don't need to handle this event. The listener for open can handle common use cases where only the file size is relevant.

The callback function can be async, provided that it's never invoked in the main thread.

For numeric values, both number and bigint are acceptable.

---

Events