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:
- 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
type t
Files.
Roughly, on Unix, these correspond to OS file descriptors, and on Windows, these are
HANDLE
s wrapped in C runtime file descriptors.
module Request : sig ... end
Request objects that can be optionally used with this module.
Standard I/O streams
Basics
module Open_flag : sig ... end
Flags for use with
Luv.File.open_
. See the flags inopen(3p)
.
module Mode : sig ... end
val 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
. Seeopen(3p)
. The synchronous version isLuv.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) Result.result -> unit) -> unit
Closes the given file.
Binds
uv_fs_close
. Seeclose(3p)
. The synchronous version isLuv.File.Sync.close
.
val 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
. Seereadv(3p)
. The synchronous version isLuv.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
orLuv.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. Seepread(3p)
.End of file is indicated by
Ok Unsigned.Size_t.zero
. Note that this is different fromLuv.Stream.read_start
.
val 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
. Seewritev(3p)
. The synchronous version isLuv.File.Sync.write
.See
Luv.File.read
for notes on the lengths of the buffers and the meaning of?file_offset
.
Moving and removing
val unlink : ?loop:Loop.t -> ?request:Request.t -> string -> ((unit, Error.t) Result.result -> unit) -> unit
Deletes the file at the given path.
Binds
uv_fs_unlink
. Seeunlink(3p)
. The synchronous version isLuv.File.Sync.unlink
.
val 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
. Seerename(3p)
. The synchronous version isLuv.File.Sync.rename
.
Temporary files
val 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
. Seemkstemp(3p)
. The synchronous version isLuv.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) Result.result -> unit) -> unit
Creates a temporary directory with name based on the given pattern.
Binds
uv_fs_mkdtemp
. Seemkdtemp(3p)
. The synchronous version isLuv.File.Sync.mkdtemp
.
Directories
val 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
. Seemkdir(3p)
. The synchronous version isLuv.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) Result.result -> unit) -> unit
Deletes a directory.
Binds
uv_fs_rmdir
. Seermdir(3p)
. The synchronous version isLuv.File.Sync.rmdir
.
module Dirent : sig ... end
Directory entries. Binds
uv_dirent_t
.
module Dir : sig ... end
Declares only
Luv.File.Dir.t
, which bindsuv_dir_t
.
val 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
. Seeopendir(3p)
. The synchronous version isLuv.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) Result.result -> unit) -> unit
Closes the given directory.
Binds
uv_fs_closedir
. Seeclosedir(3p)
. The synchronous version isLuv.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) Result.result -> unit) -> unit
Retrieves a directory entry.
Binds
uv_fs_readdir
. Seereaddir(3p)
. The synchronous version isLuv.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) Result.result -> unit) -> unit
Begins directory listing.
Binds
uv_fs_scandir
. Seescandir(3p)
. The synchronous version isLuv.File.Sync.scandir
.The resulting value of type
Directory_scan.t
must be cleaned up by callingLuv.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
val 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
. Seestat(3p)
. The synchronous version isLuv.File.Sync.stat
.
val 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
. Seelstat(3p)
. The synchronous version isLuv.File.Sync.lstat
.
val 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
. Seefstat(3p)
. The synchronous version isLuv.File.Sync.fstat
.
module Statfs : sig ... end
Binds
uv_statfs_t
.
val 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
. Seestatfs(2)
. The synchronous version isLuv.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) Result.result -> unit) -> unit
Flushes file changes to storage.
Binds
uv_fs_fsync
. Seefsync(3p)
. The synchronous version isLuv.File.Sync.fsync
.
val 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
. Seefdatasync(2)
. The synchronous version isLuv.File.Sync.fdatasync
.
Transfers
val 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
. Seeftruncate(3p)
. The synchronous version isLuv.File.Sync.ftruncate
.
val 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 isLuv.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.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) Result.result -> unit) -> unit
Transfers data between file descriptors.
Binds
uv_fs_sendfile
. Seesendfile(2)
. The synchronous version isLuv.File.Sync.sendfile
.
Permissions
module Access_flag : sig ... end
Declares
`F_OK
,`R_OK
,`W_OK
,`X_OK
for use withLuv.File.access
.
val 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
. Seeaccess(3p)
. The synchronous version isLuv.File.Sync.access
.
val 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
. Seechmod(3p)
. The synchronous version isLuv.File.Sync.chmod
.
val 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
. Seefchmod(3p)
. The synchronous version isLuv.File.Sync.fchmod
.
Timestamps
val 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
. Seeutime(3p)
. The synchronous version isLuv.File.Sync.utime
.
val 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
. Seefutimes(3)
. The synchronous version isLuv.File.Sync.futime
.
val 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
. Seelutimes(3)
. The synchronous version isLuv.File.Sync.lutime
.Requires Luv 0.5.2 and libuv 1.36.0.
Feature check:
Luv.Require.(has fs_lutime)
Links
val link : ?loop:Loop.t -> ?request:Request.t -> string -> link:string -> ((unit, Error.t) Result.result -> unit) -> unit
Hardlinks a file at the location given by
~link
.Binds
uv_fs_link
. Seelink(3p)
. The synchronous version isLuv.File.Sync.link
.
val symlink : ?loop:Loop.t -> ?request:Request.t -> ?dir:bool -> ?junction:bool -> string -> link:string -> ((unit, Error.t) Result.result -> unit) -> unit
Symlinks a file at the location given by
~link
.Binds
uv_fs_symlink
. Seesymlink(3p)
. The synchronous version isLuv.File.Sync.symlink
.See
uv_fs_symlink
for the meaning of the optional arguments.
val readlink : ?loop:Loop.t -> ?request:Request.t -> string -> ((string, Error.t) Result.result -> unit) -> unit
Reads the target path of a symlink.
Binds
uv_fs_readlink
. Seereadlink(3p)
. The synchronous version isLuv.File.Sync.readlink
.
val 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
. Seerealpath(3p)
. The synchronous version isLuv.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) Result.result -> unit) -> unit
Changes owneship of the file at the given path.
Binds
uv_fs_chown
. Seechown(3p)
. The synchronous version isLuv.File.Sync.chown
.
val 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
. Seelchown(3p)
. The synchronous version isLuv.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) Result.result -> unit) -> unit
Like
Luv.File.chown
, but takes a file instead of a path.Binds
uv_fs_fchown
. Seefchown(3p)
. The synchronous version isLuv.File.Sync.fchown
.
Synchronous API
module Sync : sig ... end
Conversions
val 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 aHANDLE
.Requires libuv 1.12.0.
Feature check:
Luv.Require.(has get_osfhandle)
val 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)
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 withLuv.Process
, the API of which assumes that files are represented by integers.