package luv

  1. Overview
  2. Docs
package luv
Legend:
Page
Library
Module
Module type
Parameter
Class
Class type
Source

Module Luv.FileSource

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:

  • Directly using the libuv thread pool.
  • By creating a thread manually with Luv.Thread.create.
  • By creating a thread manually with OCaml's standard Thread module.

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

Sourcetype t

Files.

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

Sourcemodule Request : sig ... end

Request objects that can be optionally used with this module.

Standard I/O streams

Sourceval stdin : t
Sourceval stdout : t
Sourceval stderr : t

Basics

Sourcemodule Open_flag : sig ... end

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

Sourcemodule Mode : sig ... end

Permissions bits.

Sourceval open_ : ?loop:Loop.t -> ?request:Request.t -> ?mode:Mode.t list -> string -> Open_flag.t list -> ((t, Error.t) Result.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].

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

Closes the given file.

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

Sourceval read : ?loop:Loop.t -> ?request:Request.t -> ?file_offset:int64 -> t -> Buffer.t list -> ((Unsigned.Size_t.t, Error.t) Result.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.

Sourceval write : ?loop:Loop.t -> ?request:Request.t -> ?file_offset:int64 -> t -> Buffer.t list -> ((Unsigned.Size_t.t, Error.t) Result.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.

Sourceval rename : ?loop:Loop.t -> ?request:Request.t -> string -> to_:string -> ((unit, Error.t) Result.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

Sourceval mkstemp : ?loop:Loop.t -> ?request:Request.t -> string -> ((string * t, Error.t) Result.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)

Sourceval mkdtemp : ?loop:Loop.t -> ?request:Request.t -> string -> ((string, Error.t) Result.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

Sourceval mkdir : ?loop:Loop.t -> ?request:Request.t -> ?mode:Mode.t list -> string -> ((unit, Error.t) Result.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].

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

Deletes a directory.

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

Sourcemodule Dirent : sig ... end

Directory entries. Binds uv_dirent_t.

Sourcemodule Dir : sig ... end

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

Sourceval opendir : ?loop:Loop.t -> ?request:Request.t -> string -> ((Dir.t, Error.t) Result.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)

Sourceval closedir : ?loop:Loop.t -> ?request:Request.t -> Dir.t -> ((unit, Error.t) Result.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)

Sourceval readdir : ?loop:Loop.t -> ?request:Request.t -> ?number_of_entries:int -> Dir.t -> ((Dirent.t array, Error.t) Result.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)

Sourcemodule Directory_scan : sig ... end

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

Sourceval scandir : ?loop:Loop.t -> ?request:Request.t -> string -> ((Directory_scan.t, Error.t) Result.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.

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

Retrieves the next directory entry.

Binds uv_fs_scandir_next.

Sourceval scandir_end : Directory_scan.t -> unit

Cleans up after a directory scan.

Status

Sourcemodule Stat : sig ... end

Binds uv_stat_t.

Sourceval stat : ?loop:Loop.t -> ?request:Request.t -> string -> ((Stat.t, Error.t) Result.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.

Sourceval lstat : ?loop:Loop.t -> ?request:Request.t -> string -> ((Stat.t, Error.t) Result.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.

Sourceval fstat : ?loop:Loop.t -> ?request:Request.t -> t -> ((Stat.t, Error.t) Result.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.

Sourcemodule Statfs : sig ... end

Binds uv_statfs_t.

Sourceval statfs : ?loop:Loop.t -> ?request:Request.t -> string -> ((Statfs.t, Error.t) Result.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

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

Flushes file changes to storage.

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

Sourceval fdatasync : ?loop:Loop.t -> ?request:Request.t -> t -> ((unit, Error.t) Result.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

Sourceval ftruncate : ?loop:Loop.t -> ?request:Request.t -> t -> int64 -> ((unit, Error.t) Result.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.

Sourceval copyfile : ?loop:Loop.t -> ?request:Request.t -> ?excl:bool -> ?ficlone:bool -> ?ficlone_force:bool -> string -> to_:string -> ((unit, Error.t) Result.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)
Sourceval sendfile : ?loop:Loop.t -> ?request:Request.t -> t -> to_:t -> offset:int64 -> Unsigned.Size_t.t -> ((Unsigned.Size_t.t, Error.t) Result.result -> unit) -> unit

Transfers data between file descriptors.

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

Permissions

Sourcemodule Access_flag : sig ... end

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

Sourceval access : ?loop:Loop.t -> ?request:Request.t -> string -> Access_flag.t list -> ((unit, Error.t) Result.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.

Sourceval chmod : ?loop:Loop.t -> ?request:Request.t -> string -> Mode.t list -> ((unit, Error.t) Result.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.

Sourceval fchmod : ?loop:Loop.t -> ?request:Request.t -> t -> Mode.t list -> ((unit, Error.t) Result.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

Sourceval utime : ?loop:Loop.t -> ?request:Request.t -> string -> atime:float -> mtime:float -> ((unit, Error.t) Result.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.

Sourceval futime : ?loop:Loop.t -> ?request:Request.t -> t -> atime:float -> mtime:float -> ((unit, Error.t) Result.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.

Sourceval lutime : ?loop:Loop.t -> ?request:Request.t -> string -> atime:float -> mtime:float -> ((unit, Error.t) Result.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.

Sourceval realpath : ?loop:Loop.t -> ?request:Request.t -> string -> ((string, Error.t) Result.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

Sourceval chown : ?loop:Loop.t -> ?request:Request.t -> string -> uid:int -> gid:int -> ((unit, Error.t) Result.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.

Sourceval lchown : ?loop:Loop.t -> ?request:Request.t -> string -> uid:int -> gid:int -> ((unit, Error.t) Result.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)

Sourceval fchown : ?loop:Loop.t -> ?request:Request.t -> t -> uid:int -> gid:int -> ((unit, Error.t) Result.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

Sourcemodule Sync : sig ... end

Conversions

Sourceval get_osfhandle : t -> (Os_fd.Fd.t, Error.t) Result.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)

Sourceval open_osfhandle : Os_fd.Fd.t -> (t, Error.t) Result.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)

Sourceval 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.

OCaml

Innovation. Community. Security.

GitHub Discord Twitter Peertube RSS
About
Changelog Releases Industrial Users Academic Users Why OCaml
Ecosystem
Packages Community Events OCaml Planet Jobs
Resources
Install OCaml Get Started Platform Tools Language Manual Standard Library API Books Exercises Papers OCaml Playground Logo
Policies
Carbon Footprint Governance Privacy Code of Conduct