Module Luv.File

File operations.

See Filesystem in the user guide and File system operations in libuv.

This module exposes all the filesystem operations of libuv with an asynchronous (callback) interface. There is an additional submodule, Luv.File.Sync, which exposes all the same operations with a synchronous (direct) interface. So, for example, there are:

Luv.File.chmod :
  string -> Mode.t list -> ((unit, Error.t) result -> unit) -> unit

Luv.File.Sync.chmod :
  string -> Mode.t list -> (unit, Error.t) result

For filesystem operations, synchronous operations are generally faster, because most asynchronous operations have to be run in a worker thread. However, synchronous operations can block.

A general guideline is that if performance is not critical, or your code may be used to access a network filesystem, use asynchronous operations. The latter condition may be especially important if you are writing a library, and cannot readily predict whether it will be used to access a network file system or not.

Synchronous operations are typically best for internal applications and short scripts.

It is possible to run a sequence of synchronous operations without blocking the main thread by manually running them in a worker. This can be done in several ways:

This is only worthwhile if multiple synchronous operations will be done inside the worker thread. If the worker thread does only one operation, the performance is identical to the asynchronous API.

Note that this performance difference does not apply to other kinds of libuv operations. For example, unlike reading from a file, reading from the network asynchronously is very fast.

Types

type t

Files.

Roughly, on Unix, these correspond to OS file descriptors, and on Windows, these are HANDLEs wrapped in C runtime file descriptors.

module Request : sig ... end

Request objects that can be optionally used with this module.

Standard I/O streams

val stdin : t
val stdout : t
val stderr : t

Basics

module Open_flag : sig ... end

Flags for use with Luv.File.open_. See the flags in open(3p).

module Mode : sig ... end

Permissions bits.

val open_ : ?loop:Loop.t -> ?request:Request.t -> ?mode:Mode.t list -> string -> Open_flag.t list -> ((t, Error.t) Stdlib.result -> unit) -> unit

Opens the file at the given path.

Binds uv_fs_open. See open(3p). The synchronous version is Luv.File.Sync.open_.

The default value of the ?mode argument is [`NUMERIC 0o644].

val close : ?loop:Loop.t -> ?request:Request.t -> t -> ((unit, Error.t) Stdlib.result -> unit) -> unit

Closes the given file.

Binds uv_fs_close. See close(3p). The synchronous version is Luv.File.Sync.close.

val read : ?loop:Loop.t -> ?request:Request.t -> ?file_offset:int64 -> t -> Buffer.t list -> ((Unsigned.Size_t.t, Error.t) Stdlib.result -> unit) -> unit

Reads from the given file.

Binds uv_fs_read. See readv(3p). The synchronous version is Luv.File.Sync.read.

The incoming data is written consecutively to into the given buffers. The number of bytes that the operation tries to read is the total length of the buffers.

If you have a buffer a ready, but would like to read less bytes than the length of the buffer, use Bigarray.Array1.sub or Luv.Buffer.sub to create a shorter view of the buffer.

If the ?file_offset argument is not specified, the read is done at the current offset into the file, and the file offset is updated. Otherwise, a positioned read is done at the given offset, and the file offset is not updated. See pread(3p).

End of file is indicated by Ok Unsigned.Size_t.zero. Note that this is different from Luv.Stream.read_start.

val write : ?loop:Loop.t -> ?request:Request.t -> ?file_offset:int64 -> t -> Buffer.t list -> ((Unsigned.Size_t.t, Error.t) Stdlib.result -> unit) -> unit

Writes to the given file.

Binds uv_fs_write. See writev(3p). The synchronous version is Luv.File.Sync.write.

See Luv.File.read for notes on the lengths of the buffers and the meaning of ?file_offset.

Moving and removing

Deletes the file at the given path.

Binds uv_fs_unlink. See unlink(3p). The synchronous version is Luv.File.Sync.unlink.

val rename : ?loop:Loop.t -> ?request:Request.t -> string -> to_:string -> ((unit, Error.t) Stdlib.result -> unit) -> unit

Moves the file at the given path to the path given by ~to_.

Binds uv_fs_rename. See rename(3p). The synchronous version is Luv.File.Sync.rename.

Temporary files

val mkstemp : ?loop:Loop.t -> ?request:Request.t -> string -> ((string * t, Error.t) Stdlib.result -> unit) -> unit

Creates a temporary file with name based on the given pattern.

Binds uv_fs_mkstemp. See mkstemp(3p). The synchronous version is Luv.File.Sync.mkstemp.

Requires libuv 1.34.0.

Feature check: Luv.Require.(has fs_mkstemp)

val mkdtemp : ?loop:Loop.t -> ?request:Request.t -> string -> ((string, Error.t) Stdlib.result -> unit) -> unit

Creates a temporary directory with name based on the given pattern.

Binds uv_fs_mkdtemp. See mkdtemp(3p). The synchronous version is Luv.File.Sync.mkdtemp.

Directories

val mkdir : ?loop:Loop.t -> ?request:Request.t -> ?mode:Mode.t list -> string -> ((unit, Error.t) Stdlib.result -> unit) -> unit

Creates a directory.

Binds uv_fs_mkdir. See mkdir(3p). The synchronous version is Luv.File.Sync.mkdir.

The default value of the ?mode argument is [`NUMERIC 0o755].

val rmdir : ?loop:Loop.t -> ?request:Request.t -> string -> ((unit, Error.t) Stdlib.result -> unit) -> unit

Deletes a directory.

Binds uv_fs_rmdir. See rmdir(3p). The synchronous version is Luv.File.Sync.rmdir.

module Dirent : sig ... end

Directory entries. Binds uv_dirent_t.

module Dir : sig ... end

Declares only Luv.File.Dir.t, which binds uv_dir_t.

val opendir : ?loop:Loop.t -> ?request:Request.t -> string -> ((Dir.t, Error.t) Stdlib.result -> unit) -> unit

Opens the directory at the given path for listing.

Binds uv_fs_opendir. See opendir(3p). The synchronous version is Luv.File.Sync.opendir.

The directory must later be closed with Luv.File.closedir.

Requires libuv 1.28.0.

Feature check: Luv.Require.(has fs_readdir)

val closedir : ?loop:Loop.t -> ?request:Request.t -> Dir.t -> ((unit, Error.t) Stdlib.result -> unit) -> unit

Closes the given directory.

Binds uv_fs_closedir. See closedir(3p). The synchronous version is Luv.File.Sync.closedir.

Requires libuv 1.28.0.

Feature check: Luv.Require.(has fs_readdir)

val readdir : ?loop:Loop.t -> ?request:Request.t -> ?number_of_entries:int -> Dir.t -> ((Dirent.t array, Error.t) Stdlib.result -> unit) -> unit

Retrieves a directory entry.

Binds uv_fs_readdir. See readdir(3p). The synchronous version is Luv.File.Sync.readdir.

Requires libuv 1.28.0.

Feature check: Luv.Require.(has fs_readdir)

module Directory_scan : sig ... end

Abstract type of of directory scans. See Luv.File.scandir.

val scandir : ?loop:Loop.t -> ?request:Request.t -> string -> ((Directory_scan.t, Error.t) Stdlib.result -> unit) -> unit

Begins directory listing.

Binds uv_fs_scandir. See scandir(3p). The synchronous version is Luv.File.Sync.scandir.

The resulting value of type Directory_scan.t must be cleaned up by calling Luv.File.scandir_end.

val scandir_next : Directory_scan.t -> Dirent.t option

Retrieves the next directory entry.

Binds uv_fs_scandir_next.

val scandir_end : Directory_scan.t -> unit

Cleans up after a directory scan.

Status

module Stat : sig ... end

Binds uv_stat_t.

val stat : ?loop:Loop.t -> ?request:Request.t -> string -> ((Stat.t, Error.t) Stdlib.result -> unit) -> unit

Retrieves status information for the file at the given path.

Binds uv_fs_stat. See stat(3p). The synchronous version is Luv.File.Sync.stat.

val lstat : ?loop:Loop.t -> ?request:Request.t -> string -> ((Stat.t, Error.t) Stdlib.result -> unit) -> unit

Like Luv.File.stat, but does not dereference symlinks.

Binds uv_fs_lstat. See lstat(3p). The synchronous version is Luv.File.Sync.lstat.

val fstat : ?loop:Loop.t -> ?request:Request.t -> t -> ((Stat.t, Error.t) Stdlib.result -> unit) -> unit

Like Luv.File.stat, but takes a file instead of a path.

Binds uv_fs_fstat. See fstat(3p). The synchronous version is Luv.File.Sync.fstat.

module Statfs : sig ... end

Binds uv_statfs_t.

val statfs : ?loop:Loop.t -> ?request:Request.t -> string -> ((Statfs.t, Error.t) Stdlib.result -> unit) -> unit

Retrieves status information for the filesystem containing the given path.

Binds uv_fs_statfs. See statfs(2). The synchronous version is Luv.File.Sync.statfs.

Requires libuv 1.31.0.

Feature check: Luv.Require.(has fs_statfs)

Flushing

val fsync : ?loop:Loop.t -> ?request:Request.t -> t -> ((unit, Error.t) Stdlib.result -> unit) -> unit

Flushes file changes to storage.

Binds uv_fs_fsync. See fsync(3p). The synchronous version is Luv.File.Sync.fsync.

val fdatasync : ?loop:Loop.t -> ?request:Request.t -> t -> ((unit, Error.t) Stdlib.result -> unit) -> unit

Like Luv.File.fsync, but may omit some metadata.

Binds uv_fs_fdatasync. See fdatasync(2). The synchronous version is Luv.File.Sync.fdatasync.

Transfers

val ftruncate : ?loop:Loop.t -> ?request:Request.t -> t -> int64 -> ((unit, Error.t) Stdlib.result -> unit) -> unit

Truncates the given file to the given length.

Binds uv_fs_ftruncate. See ftruncate(3p). The synchronous version is Luv.File.Sync.ftruncate.

val copyfile : ?loop:Loop.t -> ?request:Request.t -> ?excl:bool -> ?ficlone:bool -> ?ficlone_force:bool -> string -> to_:string -> ((unit, Error.t) Stdlib.result -> unit) -> unit

Copies the file at the given path to the path given by ~to_.

Binds uv_fs_copyfile. The synchronous version is Luv.File.Sync.copyfile.

Requires libuv 1.14.0.

?ficlone and ?ficlone_force have no effect if the libuv version is less than 1.20.0.

Feature checks:

  • Luv.Require.(has fs_copyfile)
  • Luv.Require.(has fs_copyfile_ficlone)
val sendfile : ?loop:Loop.t -> ?request:Request.t -> t -> to_:t -> offset:int64 -> Unsigned.Size_t.t -> ((Unsigned.Size_t.t, Error.t) Stdlib.result -> unit) -> unit

Transfers data between file descriptors.

Binds uv_fs_sendfile. See sendfile(2). The synchronous version is Luv.File.Sync.sendfile.

Permissions

module Access_flag : sig ... end

Declares `F_OK, `R_OK, `W_OK, `X_OK for use with Luv.File.access.

val access : ?loop:Loop.t -> ?request:Request.t -> string -> Access_flag.t list -> ((unit, Error.t) Stdlib.result -> unit) -> unit

Checks whether the calling process can access the file at the given path.

Binds uv_fs_access. See access(3p). The synchronous version is Luv.File.Sync.access.

val chmod : ?loop:Loop.t -> ?request:Request.t -> string -> Mode.t list -> ((unit, Error.t) Stdlib.result -> unit) -> unit

Changes permissions of the file at the given path.

Binds uv_fs_chmod. See chmod(3p). The synchronous version is Luv.File.Sync.chmod.

val fchmod : ?loop:Loop.t -> ?request:Request.t -> t -> Mode.t list -> ((unit, Error.t) Stdlib.result -> unit) -> unit

Like Luv.File.chmod, but takes a file instead of a path.

Binds uv_fs_fchmod. See fchmod(3p). The synchronous version is Luv.File.Sync.fchmod.

Timestamps

val utime : ?loop:Loop.t -> ?request:Request.t -> string -> atime:float -> mtime:float -> ((unit, Error.t) Stdlib.result -> unit) -> unit

Sets timestamps of the file at the given path.

Binds uv_fs_utime. See utime(3p). The synchronous version is Luv.File.Sync.utime.

val futime : ?loop:Loop.t -> ?request:Request.t -> t -> atime:float -> mtime:float -> ((unit, Error.t) Stdlib.result -> unit) -> unit

Like Luv.File.utime, but takes a file instead of a path.

Binds uv_fs_futime. See futimes(3). The synchronous version is Luv.File.Sync.futime.

val lutime : ?loop:Loop.t -> ?request:Request.t -> string -> atime:float -> mtime:float -> ((unit, Error.t) Stdlib.result -> unit) -> unit

Like Luv.File.utime, but does not dereference symlinks.

Binds uv_fs_lutime. See lutimes(3). The synchronous version is Luv.File.Sync.lutime.

Requires Luv 0.5.2 and libuv 1.36.0.

Feature check: Luv.Require.(has fs_lutime)

Hardlinks a file at the location given by ~link.

Binds uv_fs_link. See link(3p). The synchronous version is Luv.File.Sync.link.

Symlinks a file at the location given by ~link.

Binds uv_fs_symlink. See symlink(3p). The synchronous version is Luv.File.Sync.symlink.

See uv_fs_symlink for the meaning of the optional arguments.

Reads the target path of a symlink.

Binds uv_fs_readlink. See readlink(3p). The synchronous version is Luv.File.Sync.readlink.

val realpath : ?loop:Loop.t -> ?request:Request.t -> string -> ((string, Error.t) Stdlib.result -> unit) -> unit

Resolves a real absolute path to the given file.

Binds uv_fs_readpath. See realpath(3p). The synchronous version is Luv.File.Sync.realpath.

Requires libuv 1.8.0.

Feature check: Luv.Require.(has fs_realpath)

Ownership

val chown : ?loop:Loop.t -> ?request:Request.t -> string -> uid:int -> gid:int -> ((unit, Error.t) Stdlib.result -> unit) -> unit

Changes owneship of the file at the given path.

Binds uv_fs_chown. See chown(3p). The synchronous version is Luv.File.Sync.chown.

val lchown : ?loop:Loop.t -> ?request:Request.t -> string -> uid:int -> gid:int -> ((unit, Error.t) Stdlib.result -> unit) -> unit

Like Luv.File.chown, but does not dereference symlinks.

Binds uv_fs_lchown. See lchown(3p). The synchronous version is Luv.File.Sync.lchown.

Requires libuv 1.21.0.

Feature check: Luv.Require.(has fs_lchown)

val fchown : ?loop:Loop.t -> ?request:Request.t -> t -> uid:int -> gid:int -> ((unit, Error.t) Stdlib.result -> unit) -> unit

Like Luv.File.chown, but takes a file instead of a path.

Binds uv_fs_fchown. See fchown(3p). The synchronous version is Luv.File.Sync.fchown.

Synchronous API

module Sync : sig ... end

Conversions

val get_osfhandle : t -> (Os_fd.Fd.t, Error.t) Stdlib.result

Converts a Luv.File.t to an OS file handle.

Binds uv_get_osfhandle. See _get_osfhandle.

On Unix-like systems, this passes the file descriptor through unchanged. On Windows, a Luv.File.t is an C runtime library file descritpor. This function converts it to a HANDLE.

Requires libuv 1.12.0.

Feature check: Luv.Require.(has get_osfhandle)

val open_osfhandle : Os_fd.Fd.t -> (t, Error.t) Stdlib.result

Inverse of Luv.File.get_osfhandle.

Binds uv_open_osfhandle. See _open_osfhandle.

Requires libuv 1.23.0.

Feature check: Luv.Require.(has open_osfhandle)

val to_int : t -> int

Returns the integer representation of a Luv.File.t.

Luv.File.t is defined as an integer file descriptor by libuv on all platforms at the moment. This is a convenience function for interoperability with Luv.Process, the API of which assumes that files are represented by integers.