uwt

libuv bindings
Library uwt
Module type Uwt . Fs_functions
include sig ... end
type uv_open_flag = Fs_types.uv_open_flag =
| O_RDONLY(*

Open for reading

*)
| O_WRONLY(*

Open for writing

*)
| O_RDWR(*

Open for reading and writing

*)
| O_NONBLOCK(*

Open in non-blocking mode, ignored on Windows

*)
| O_CREAT(*

Create if nonexistent

*)
| O_EXCL(*

Fail if existing

*)
| O_TRUNC(*

Truncate to 0 length if existing

*)
| O_APPEND(*

Open for append

*)
| O_NOCTTY(*

Don't make this dev a controlling tty, ignored on Windows

*)
| O_DSYNC(*

Writes complete as `Synchronised I/O data integrity completion', ignored by some platforms

*)
| O_SYNC(*

Writes complete as `Synchronised I/O file integrity completion', ignored by some platforms

*)
| O_RSYNC(*

Reads complete as writes (depending on O_SYNC/O_DSYNC), only supported on some Unix platforms, ignored otherwise

*)
| O_TEMPORARY(*

windows only, ignored on Unix

*)
| O_SHORT_LIVED(*

windows only, ignored on Unix

*)
| O_SEQUENTIAL(*

windows only, ignored on Unix

*)
| O_RANDOM(*

windows only, ignored on Unix

*)
| O_DIRECT(*

On Windows supported since libuv 1.16

*)
| O_EXLOCK(*

OS X (and Windows, but with different semantic)

*)
| O_NOATIME(*

no windows, some Unix systems, ignored otherwise

*)
| O_NOFOLLOW(*

no windows, some Unix systems, ignored otherwise

*)
| O_DIRECTORY(*

no windows, some Unix systems, ignored otherwise

*)

Flags for Fs_functions.openfile

O_CLOEXEC doesn't exist, because this flag is unconditionally added by libuv. O_SHARE_DELETE, O_SHARE_WRITE, O_SHARE_READ are always added on Windows, unless O_EXLOCK is specified.

type file_kind = Fs_types.file_kind =
| S_REG(*

Regular file

*)
| S_DIR(*

Directory

*)
| S_CHR(*

Character device

*)
| S_BLK(*

Block device

*)
| S_LNK(*

Symbolic link

*)
| S_FIFO(*

Named pipe

*)
| S_SOCK(*

Socket

*)
| S_UNKNOWN(*

Everything else - possible on some platforms.

*)

On Windows it can be specified how to create symlinks.

type access_permission = Fs_types.access_permission =
| Read(*

Read permission

*)
| Write(*

Write permission

*)
| Exec(*

Execution permission

*)
| Exists(*

File exists

*)
type stats = Fs_types.stats = {
st_dev : int;(*

Device number

*)
st_kind : file_kind;(*

Kind of the file

*)
st_perm : int;(*

Access rights

*)
st_uid : int;(*

User id of the owner

*)
st_gid : int;(*

Group ID of the file's group

*)
st_rdev : int;(*

Device minor number

*)
st_ino : int;(*

Inode number

*)
st_size : int64;(*

Size in bytes

*)
st_blksize : int;(*

"Preferred" block size for efficient filesystem I/O

*)
st_blocks : int;(*

Number of blocks allocated to the file, in 512-byte units

*)
st_flags : int;(*

User defined flags for file

*)
st_gen : int;(*

File generation number

*)
st_atime : int64;(*

Last access time

*)
st_atime_nsec : int;(*

Nanosecond components of last access time

*)
st_mtime : int64;(*

Last modification time

*)
st_mtime_nsec : int;(*

Nanosecond components of last modification time

*)
st_ctime : int64;(*

Last status change time

*)
st_ctime_nsec : int;(*

Nanosecond components of lastt status change time

*)
st_birthtime : int64;(*

File creation time

*)
st_birthtime_nsec : int;(*

Nanosecond components of File creation time

*)
}

File status information. Support for the various fields differs depending on the OS and filesystem.

type clone_mode =
| No_clone(*

Create a normal copy

*)
| Try_clone(*

Try to clone the file, but create a normal copy, if it fails

*)
| Force_clone(*

Try tlone the file, don't create a normal copy, if it fails

*)

Clone mode for Fs_functions.copyfile

type 'a t
val openfile : ?perm:int -> mode:uv_open_flag list -> string -> file t

Equivalent to open(2).

  • parameter perm

    defaults are 0o644

val read : ?pos:int -> ?len:int -> file -> buf:bytes -> int t

read ~pos ~len fd ~buf reads ~len bytes from descriptor fd, storing them in byte sequence buf, starting at position ~pos in ~buf. Return the number of bytes actually read.

  • parameter pos

    default is always zero

  • parameter len

    default is always the still available length of the string / bigarray / Bytes.t

val read_ba : ?pos:int -> ?len:int -> file -> buf:buf -> int t

like read, buf for bigarrays. Bigarrays are passed directly to libuv (no copy to c heap or stack). It's faster, but you must manually ensure, that the bigarray is not accessed from another thread.

val pread : ?pos:int -> ?len:int -> file -> fd_offset:int64 -> buf:bytes -> int t

pread is equivalent to read, except that it reads from a given position ~fd_offset in the file without changing the file offset.

val pread_ba : ?pos:int -> ?len:int -> file -> fd_offset:int64 -> buf:buf -> int t
val write : ?pos:int -> ?len:int -> file -> buf:bytes -> int t

write fd ~pos ~len fd ~buf writes ~len bytes to descriptor fd, taking them from byte sequence buf, starting at position ~pos in ~buf. Return the number of bytes actually written.

val write_string : ?pos:int -> ?len:int -> file -> buf:string -> int t
val write_ba : ?pos:int -> ?len:int -> file -> buf:buf -> int t
val pwrite : ?pos:int -> ?len:int -> file -> fd_offset:int64 -> buf:bytes -> int t

pwrite is equivalent to write, except that it writes into a given position ~fd_offset and does not change the file offset

val pwrite_string : ?pos:int -> ?len:int -> file -> fd_offset:int64 -> buf:string -> int t
val pwrite_ba : ?pos:int -> ?len:int -> file -> fd_offset:int64 -> buf:buf -> int t
val writev : file -> Iovec_write.t list -> int t

write multiple buffers at once. If the number of buffers is greater than IOV_MAX, newer libuv versions already contains code to circumvent this issue

val pwritev : file -> Iovec_write.t list -> int64 -> int t

pwritev is equivalent to pwrite, except that it writes into a given position and does not change the file offset

val close : file -> unit t

Close a file descriptor.

delete a name and possibly the file it refers to

val mkdir : ?perm:int -> string -> unit t

Create a directory.

  • parameter perm

    defaults are 0o777

val rmdir : string -> unit t

Delete an empty directory

val fsync : file -> unit t

synchronize a file's in-core state with storage device.

val fdatasync : file -> unit t

fdatasync is similar to fsync, but does not flush modified metadata unless that metadata is needed in order to allow a subsequent data retrieval to be correctly handled.

val ftruncate : file -> len:int64 -> unit t

truncate a file to a specified length

val stat : string -> stats t

Return the information for the named file.

val lstat : string -> stats t

lstat is identical to stat, except that if pathname is a symbolic link. In this case it returns information about the link itself.

val fstat : file -> stats t

fstat is identical to stat, except that the file about which information is to be retrieved is specified by the file descriptor

val rename : src:string -> dst:string -> unit t

change the name or location of a file

link creates a new link (also known as a hard link) to an existing file

symlink creates a symbolic link named ~dst which contains the string ~src

  • parameter mode

    default S_Default

val mkdtemp : string -> string t

The mkdtemp function generates a uniquely named temporary directory from template. The last six characters of template must be XXXXXX and these are replaced with a string that makes the directory name unique

val sendfile : ?pos:int64 -> ?len:nativeint -> dst:file -> src:file -> unit -> nativeint t

A limited equivalent to sendfile(2). It copies data between one file descriptor and another

  • parameter pos

    default 0

  • parameter len

    default: SIZE_MAX

val utime : string -> access:float -> modif:float -> unit t

utime changes the access and modification times of a file. If both times are 0.0, the access and last modification times are both set to the current time.

val futime : file -> access:float -> modif:float -> unit t

futime is identical to utime, except that the file about which information is to be retrieved is specified by the file descriptor

readlink reads the value of a symbolic link

val access : string -> access_permission list -> unit t

Check user's permissions for a file

val chmod : string -> perm:int -> unit t

Change the permissions of the named file.

val fchmod : file -> perm:int -> unit t

Change the permissions of an opened file.

val chown : string -> uid:int -> gid:int -> unit t

Change the owner ~uid and owner ~gid of the named file.

val fchown : file -> uid:int -> gid:int -> unit t

Change the owner ~uid and owner ~gid of the opened file.

val lchown : string -> uid:int -> gid:int -> unit t

like chown, but do not dereference symbolic links

val scandir : string -> (file_kind * string) array t

On Linux, getting the type of an entry is only supported by some filesystems (btrfs, ext2, ext3 and ext4 at the time of this writing), check the getdents(2) man page.

val realpath : string -> string t

Equivalent to realpath(3) on Unix. Windows uses GetFinalPathNameByHandle.

Warning This function has certain platform specific caveats that were discovered when used in Node.

macOS and other BSDs: this function will fail with UV_ELOOP if more than 32 symlinks are found while resolving the given path. This limit is hardcoded and cannot be sidestepped.

Windows: while this function works in the common case, there are a number of corner cases where it doesn't:

  • Paths in ramdisk
  • volumes created by tools which sidestep the Volume Manager (such as ImDisk) cannot be resolved.
  • Inconsistent casing when using drive letters.
  • Resolved path bypasses subst'd drives.

While this function can still be used, it's not recommended if scenarios such as the above need to be supported.

val copyfile : ?excl:bool -> ?clone:clone_mode -> src:string -> dst:string -> unit -> unit t

Copies a file from ~src to ~dst.

If ?excl is true, copyfile will fail with EEXIST if the destination path already exists. The default behavior is to overwrite the destination if it exists.

If ?clone is Try_clone, copyfile will attempt to create a copy-on-write reflink. If the underlying platform (or your installed libuv version) does not support copy-on-write, then a fallback copy mechanism is used. If ?clone is Force_clone, copyfile will attempt to create a copy-on-write reflink. If the underlying platform does not support copy-on-write, then an error is returned. The default behaviour is a normal copy (No_clone).

Warning: If the destination path is created, but an error occurs while copying the data, then the destination path is removed. There is a brief window of time between closing and removing the file where another process could access the file.