package uwt

You can search for identifiers within the package.

in-package search v0.2.0

Package contains no libraries

Synchronous filesystem operations

This module is independent of lwt. It might be useful, if you target windows:

additional options and functions are available, that are missing inside the standard Unix module.

filenames and similar parameters and return values are always utf-8 encoded.

include Uwt_base.Fs_functions with type 'a t := 'a Uwt_base.uv_result

include module type of Uwt_base.Fs_types
  with type uv_open_flag = Uwt_base.Fs_types.uv_open_flag
  with type file_kind = Uwt_base.Fs_types.file_kind
  with type symlink_mode = Uwt_base.Fs_types.symlink_mode
  with type access_permission = Uwt_base.Fs_types.access_permission
  with type stats = Uwt_base.Fs_types.stats

type uv_open_flag = Uwt_base.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_SYMLINK
(*
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 = Uwt_base.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.
*)

type symlink_mode = Uwt_base.Fs_types.symlink_mode =

| S_Default
| S_Dir
(*
indicates that path points to a directory.
*)
| S_Junction
(*
request that the symlink is created using junction points.
*)

On Windows it can be specified how to create symlinks.

type access_permission = Uwt_base.Fs_types.access_permission =

| Read
(*
Read permission
*)
| Write
(*
Write permission
*)
| Exec
(*
Execution permission
*)
| Exists
(*
File exists
*)

type stats = Uwt_base.Fs_types.stats = {

st_dev : int;
(*
Device number
*)
st_kind : file_kind;
(*
Kind of the file
*)
st_perm : int;
(*
Access rights
*)
st_nlink : int;
(*
Number of links
*)
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

val openfile : 
  ?perm:int ->
  mode:uv_open_flag list ->
  string ->
  Uwt_base.file Uwt_base.uv_result

Equivalent to open(2).

parameter perm
defaults are 0o644

val read : 
  ?pos:int ->
  ?len:int ->
  Uwt_base.file ->
  buf:bytes ->
  int Uwt_base.uv_result

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 ->
  Uwt_base.file ->
  buf:Uwt_base.buf ->
  int Uwt_base.uv_result

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 ->
  Uwt_base.file ->
  fd_offset:int64 ->
  buf:bytes ->
  int Uwt_base.uv_result

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 ->
  Uwt_base.file ->
  fd_offset:int64 ->
  buf:Uwt_base.buf ->
  int Uwt_base.uv_result

val write : 
  ?pos:int ->
  ?len:int ->
  Uwt_base.file ->
  buf:bytes ->
  int Uwt_base.uv_result

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 ->
  Uwt_base.file ->
  buf:string ->
  int Uwt_base.uv_result

val write_ba : 
  ?pos:int ->
  ?len:int ->
  Uwt_base.file ->
  buf:Uwt_base.buf ->
  int Uwt_base.uv_result

val pwrite : 
  ?pos:int ->
  ?len:int ->
  Uwt_base.file ->
  fd_offset:int64 ->
  buf:bytes ->
  int Uwt_base.uv_result

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 ->
  Uwt_base.file ->
  fd_offset:int64 ->
  buf:string ->
  int Uwt_base.uv_result

val pwrite_ba : 
  ?pos:int ->
  ?len:int ->
  Uwt_base.file ->
  fd_offset:int64 ->
  buf:Uwt_base.buf ->
  int Uwt_base.uv_result

val writev : 
  Uwt_base.file ->
  Uwt_base.Iovec_write.t list ->
  int Uwt_base.uv_result

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 : 
  Uwt_base.file ->
  Uwt_base.Iovec_write.t list ->
  int64 ->
  int Uwt_base.uv_result

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

val close : Uwt_base.file -> unit Uwt_base.uv_result

Close a file descriptor.

val unlink : string -> unit Uwt_base.uv_result

delete a name and possibly the file it refers to

val mkdir : ?perm:int -> string -> unit Uwt_base.uv_result

Create a directory.

parameter perm
defaults are 0o777

val rmdir : string -> unit Uwt_base.uv_result

Delete an empty directory

val fsync : Uwt_base.file -> unit Uwt_base.uv_result

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

val fdatasync : Uwt_base.file -> unit Uwt_base.uv_result

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 : Uwt_base.file -> len:int64 -> unit Uwt_base.uv_result

truncate a file to a specified length

val stat : string -> stats Uwt_base.uv_result

Return the information for the named file.

val lstat : string -> stats Uwt_base.uv_result

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 : Uwt_base.file -> stats Uwt_base.uv_result

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 Uwt_base.uv_result

change the name or location of a file

val link : target:string -> link_name:string -> unit Uwt_base.uv_result

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

val symlink : 
  ?mode:symlink_mode ->
  src:string ->
  dst:string ->
  unit ->
  unit Uwt_base.uv_result

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

parameter mode
default S_Default

val mkdtemp : string -> string Uwt_base.uv_result

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:Uwt_base.file ->
  src:Uwt_base.file ->
  unit ->
  nativeint Uwt_base.uv_result

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 Uwt_base.uv_result

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 : 
  Uwt_base.file ->
  access:float ->
  modif:float ->
  unit Uwt_base.uv_result

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

val readlink : string -> string Uwt_base.uv_result

readlink reads the value of a symbolic link

val access : string -> access_permission list -> unit Uwt_base.uv_result

Check user's permissions for a file

val chmod : string -> perm:int -> unit Uwt_base.uv_result

Change the permissions of the named file.

val fchmod : Uwt_base.file -> perm:int -> unit Uwt_base.uv_result

Change the permissions of an opened file.

val chown : string -> uid:int -> gid:int -> unit Uwt_base.uv_result

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

val fchown : Uwt_base.file -> uid:int -> gid:int -> unit Uwt_base.uv_result

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

val lchown : string -> uid:int -> gid:int -> unit Uwt_base.uv_result

like chown, but do not dereference symbolic links

val scandir : string -> (file_kind * string) array Uwt_base.uv_result

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 Uwt_base.uv_result

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 Uwt_base.uv_result

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.