Module Posix_statSource

POSIX file status and permissions.

This module provides OCaml bindings to POSIX file status functions defined in sys/stat.h.

It includes functions for querying file metadata, changing permissions, and creating directories and special files.

Example

  (* Get file information *)
  let info = stat "/etc/passwd" in
  Printf.printf "Size: %Ld bytes\n" (Posix_types.Off.to_int64 info.st_size);

  (* Check if it's a regular file *)
  if s_isreg info.st_mode then print_endline "Regular file"

File Type Constants

Constants for the file type portion of st_mode. Use s_ifmt to mask out the file type bits.

File type mask. Use as Posix_types.Mode.logand mode s_ifmt.

Regular file (S_IFREG).

Directory (S_IFDIR).

Symbolic link (S_IFLNK).

Character device (S_IFCHR).

Block device (S_IFBLK).

FIFO/named pipe (S_IFIFO).

Socket (S_IFSOCK).

Permission Bit Constants

Constants for file permission bits in st_mode.

Special Mode Bits

Set-user-ID on execution (S_ISUID).

Set-group-ID on execution (S_ISGID).

Sticky bit (S_ISVTX). On directories, restricts file deletion.

Owner Permissions

Owner: read, write, execute (S_IRWXU = 0o700).

Owner: read permission (S_IRUSR = 0o400).

Owner: write permission (S_IWUSR = 0o200).

Owner: execute permission (S_IXUSR = 0o100).

Group Permissions

Group: read, write, execute (S_IRWXG = 0o070).

Group: read permission (S_IRGRP = 0o040).

Group: write permission (S_IWGRP = 0o020).

Group: execute permission (S_IXGRP = 0o010).

Others Permissions

Others: read, write, execute (S_IRWXO = 0o007).

Others: read permission (S_IROTH = 0o004).

Others: write permission (S_IWOTH = 0o002).

Others: execute permission (S_IXOTH = 0o001).

File Type Test Functions

These functions test the st_mode field to determine file type. They are equivalent to the POSIX S_IS* macros.

Sourceval s_isreg : Posix_types.mode_t -> bool

s_isreg mode returns true if mode indicates a regular file.

Sourceval s_isdir : Posix_types.mode_t -> bool

s_isdir mode returns true if mode indicates a directory.

Sourceval s_islnk : Posix_types.mode_t -> bool

s_islnk mode returns true if mode indicates a symbolic link.

Sourceval s_ischr : Posix_types.mode_t -> bool

s_ischr mode returns true if mode indicates a character device.

Sourceval s_isblk : Posix_types.mode_t -> bool

s_isblk mode returns true if mode indicates a block device.

Sourceval s_isfifo : Posix_types.mode_t -> bool

s_isfifo mode returns true if mode indicates a FIFO/named pipe.

Sourceval s_issock : Posix_types.mode_t -> bool

s_issock mode returns true if mode indicates a socket.

File Status Structure

File status information returned by stat, fstat, and lstat. Corresponds to POSIX struct stat.

File Status Functions

Sourceval stat : string -> stat

Get file status, following symbolic links.

See stat(2).

  • raises Unix.Unix_error

    on failure.

Sourceval fstat : Unix.file_descr -> stat

Get file status for an open file descriptor.

See fstat(2).

  • raises Unix.Unix_error

    on failure.

Sourceval lstat : string -> stat

Get file status without following symbolic links.

Returns information about the symbolic link itself, not its target.

See lstat(2).

  • raises Unix.Unix_error

    on failure.

Permission Functions

Sourceval chmod : string -> Posix_types.mode_t -> unit

Change file permissions.

See chmod(2).

  • raises Unix.Unix_error

    on failure.

Sourceval fchmod : Unix.file_descr -> Posix_types.mode_t -> unit

Change file permissions using a file descriptor.

See fchmod(2).

  • raises Unix.Unix_error

    on failure.

File Creation

Sourceval mkdir : string -> Posix_types.mode_t -> unit

Create a directory.

See mkdir(2).

  • raises Unix.Unix_error

    on failure.

Sourceval mkfifo : string -> Posix_types.mode_t -> unit

Create a FIFO (named pipe).

See mkfifo(3).

  • raises Unix.Unix_error

    on failure.

File Creation Mask

Set the file mode creation mask.

See umask(2).

The umask is used to turn off permission bits when creating files. For example, umask (Mode.of_int 0o022) prevents group and others write permissions on newly created files.

  • returns

    The previous umask value.

Directory-Relative Operations

These functions operate relative to a directory file descriptor, providing protection against certain race conditions (TOCTOU).

See *at(2) functions.

Sourceval at_fdcwd : int

Use current working directory as the base for relative paths. Pass this as dirfd to use CWD like the non-*at functions.

Flag: do not follow symbolic links.

Sourceval at_removedir : int

Flag: remove directory instead of file (for unlinkat).

Sourceval at_eaccess : int

Flag: use effective IDs for access checks (for faccessat).

Sourceval fstatat : ?dirfd:Unix.file_descr -> ?flags:int list -> string -> stat

Like stat/lstat but relative to a directory file descriptor.

See fstatat(2).

  • parameter dirfd

    Base directory (default: current working directory).

  • raises Unix.Unix_error

    on failure.

Sourceval fchmodat : ?dirfd:Unix.file_descr -> ?flags:int list -> string -> Posix_types.mode_t -> unit

Like chmod but relative to a directory file descriptor.

See fchmodat(2).

  • parameter dirfd

    Base directory (default: current working directory).

  • parameter flags

    Optional flags.

  • raises Unix.Unix_error

    on failure.

Sourceval mkdirat : ?dirfd:Unix.file_descr -> string -> Posix_types.mode_t -> unit

Like mkdir but relative to a directory file descriptor.

See mkdirat(2).

  • parameter dirfd

    Base directory (default: current working directory).

  • raises Unix.Unix_error

    on failure.

Sourceval mkfifoat : ?dirfd:Unix.file_descr -> string -> Posix_types.mode_t -> unit

Like mkfifo but relative to a directory file descriptor.

See mkfifoat(3).

  • parameter dirfd

    Base directory (default: current working directory).

  • raises Unix.Unix_error

    on failure.