package async_unix

  1. Overview
  2. Docs
package async_unix
Legend:
Library
Module
Module type
Parameter
Class
Class type
module Fd = Fd
module Syscall_result = Core_unix.Syscall_result
module Exit = Core_unix.Exit
module Exit_or_signal = Core_unix.Exit_or_signal
module Exit_or_signal_or_stop = Core_unix.Exit_or_signal_or_stop
val system_exn : string -> unit Async_kernel.Deferred.t
val getpid : unit -> Core.Pid.t
val getppid : unit -> Core.Pid.t option
val getppid_exn : unit -> Core.Pid.t
val this_process_became_child_of_init : ?poll_delay:Time_float_unix.Span.t -> unit -> unit Async_kernel.Deferred.t

this_process_became_child_of_init returns a deferred that becomes determined when the current process becomes a child of init(8). This is useful for determining whether one's parent has died, because in that case init will become one's parent.

See Linux_ext.pr_set_pdeathsig : Signal.t -> unit for a related way to get information about parent death.

?poll_delay controls how often to check.

val nice : int -> int
val cores : (unit -> int Async_kernel.Deferred.t) Core.Or_error.t

cores () Returns the number of cores.

type open_flag = [
  1. | `Rdonly
  2. | `Wronly
  3. | `Rdwr
  4. | `Nonblock
  5. | `Append
  6. | `Creat
  7. | `Trunc
  8. | `Excl
  9. | `Noctty
  10. | `Dsync
  11. | `Sync
  12. | `Rsync
]
type file_perm = int
val openfile : ?info:Core.Info.t -> ?perm:file_perm -> string -> mode:open_flag list -> Fd.t Async_kernel.Deferred.t
module Lock_mode : sig ... end
module Lock_mechanism : sig ... end
module Lock : sig ... end
val with_file : ?lock:Lock.t -> ?perm:file_perm -> string -> mode:open_flag list -> f:(Fd.t -> 'a Async_kernel.Deferred.t) -> 'a Async_kernel.Deferred.t

with_file file ~mode ~perm ~f opens file, and applies f to the resulting file descriptor. When the result of f becomes determined, it closes the descriptor and returns the result of f.

If lock is supplied, then the file descriptor is locked before calling f with the specified lock_mechanism. Note that it is not unlocked before close, which might be significant if this file descriptor is held elsewhere (e.g., by fork() or dup()).

module Open_flags = Core_unix.Open_flags

fcntl_getfl and fcntl_setf are deferred wrappers around the corresponding functions in Core_unix for accessing the open-file-descriptor table.

val fcntl_setfl : Fd.t -> Open_flags.t -> unit Async_kernel.Deferred.t
include module type of Fd.Close

The Close module exists to collect close and its associated types, so they can be easily reused elsewhere, e.g., Unix_syscalls.

type socket_handling =
  1. | Shutdown_socket
  2. | Do_not_shutdown_socket
type file_descriptor_handling =
  1. | Close_file_descriptor of socket_handling
  2. | Do_not_close_file_descriptor
val close : ?file_descriptor_handling:file_descriptor_handling -> Fd.t -> unit Async_kernel.Deferred.t

close t prevents further use of t, and makes shutdown() and close() system calls on t's underlying file descriptor according to the file_descriptor_handling argument and whether or not t is a socket, i.e., kind t = Socket `Active:

        | file_descriptor_handling                     | shutdown() | close() |
        |----------------------------------------------+------------+---------|
        | Do_not_close_file_descriptor                 | no         | no      |
        | Close_file_descriptor Shutdown_socket        | if socket  | yes     |
        | Close_file_descriptor Do_not_shutdown_socket | no         | yes     |

The result of close becomes determined once the system calls complete. It is OK to call close multiple times on the same t; calls subsequent to the initial call will have no effect, but will return the same deferred as the original call.

val deregister : Fd.t -> unit Async_kernel.Deferred.t

deregister t causes Async to stop tracking this file descriptor, and prevents further use of t. The file descriptor remains open; it can be used by other libraries.

You should only call this function if you have a file descriptor created by Async and you need to move ownership of that file descriptor to another IO library which expects to be able to close the file descriptor itself. Otherwise, just use close.

This is like calling close with file_descriptor_handling set to Do_not_close_file_descriptor.

It is OK to call deregister multiple times on the same t, like close.

val lseek : Fd.t -> int64 -> mode:[< `Set | `Cur | `End ] -> int64 Async_kernel.Deferred.t
val truncate : string -> len:int64 -> unit Async_kernel.Deferred.t
val ftruncate : Fd.t -> len:int64 -> unit Async_kernel.Deferred.t
val fsync : Fd.t -> unit Async_kernel.Deferred.t
val fdatasync : Fd.t -> unit Async_kernel.Deferred.t
val sync : unit -> unit Async_kernel.Deferred.t
val lockf : ?len:Core.Int64.t -> Fd.t -> Lock_mode.t -> unit Async_kernel.Deferred.t

lockf fd lock_mode ?len locks the section of the open file fd specified by the current file position and len (see man lockf). It returns when the lock has been acquired. It raises if fd is closed.

Warning: lockf locks are held per-process, so taking the lock on the same file multiple times in the same process is going to break in terrible ways.

Note that, despite the name, this function does not call the UNIX lockf() system call; rather it calls fcntl() with F_SETLKW

val try_lockf : ?len:Core.Int64.t -> Fd.t -> Lock_mode.t -> bool

try_lockf fd lock_mode ?len attempts to lock the section of the open file fd specified by the current file position and len (see man lockf). It returns true if it acquired the lock. It raises if fd is closed.

Note that, despite the name, this function does not call the UNIX lockf() system call; rather it calls fcntl() with F_SETLK

val test_lockf : ?len:Core.Int64.t -> Fd.t -> bool

test_lockf fd ?len checks the lock on section of the open file fd specified by the current file position and len. If the section is unlocked or locked by this process, it returns true, else it returns false. It raises if fd is closed.

Note that, despite the name, this function does not call the UNIX lockf() system call; rather it calls fcntl() with F_GETLK

val unlockf : ?len:Core.Int64.t -> Fd.t -> unit

unlockf fd ?len unlocks the section of the open file fd specified by the current file position and len. It raises if fd is closed.

Note that, despite the name, this function does not call the UNIX lockf() system call; rather it calls fcntl() with F_UNLCK

flock fd lock_mode locks the open file fd (see man 2 flock). It returns when the lock has been acquired. It raises if fd is closed.

val try_flock : Fd.t -> Lock_mode.t -> bool

try_flock fd lock_mode attempts to lock the open file fd (see man 2 flock). It returns true if it acquired the lock or false if a conflicting lock was already present. It raises if fd is closed.

val funlock : Fd.t -> unit

funlock fd unlocks the open file fd (see man 2 flock). It raises if fd is closed.

module File_kind : sig ... end
module Stats : sig ... end
val stat : string -> Stats.t Async_kernel.Deferred.t
val lstat : string -> Stats.t Async_kernel.Deferred.t
val isatty : Fd.t -> bool Async_kernel.Deferred.t
val remove : string -> unit Async_kernel.Deferred.t
val rename : src:string -> dst:string -> unit Async_kernel.Deferred.t
val chmod : string -> perm:file_perm -> unit Async_kernel.Deferred.t
val fchmod : Fd.t -> perm:file_perm -> unit Async_kernel.Deferred.t
val chown : string -> uid:int -> gid:int -> unit Async_kernel.Deferred.t
val fchown : Fd.t -> uid:int -> gid:int -> unit Async_kernel.Deferred.t
val access : string -> [ `Read | `Write | `Exec | `Exists ] list -> (unit, exn) Core.Result.t Async_kernel.Deferred.t
val access_exn : string -> [ `Read | `Write | `Exec | `Exists ] list -> unit Async_kernel.Deferred.t
val set_close_on_exec : Fd.t -> unit
val clear_close_on_exec : Fd.t -> unit
val mkdir : ?p:unit -> ?perm:file_perm -> string -> unit Async_kernel.Deferred.t
val rmdir : string -> unit Async_kernel.Deferred.t
val chdir : string -> unit Async_kernel.Deferred.t
val getcwd : unit -> string Async_kernel.Deferred.t
val chroot : string -> unit Async_kernel.Deferred.t
type dir_handle = Core_unix.dir_handle
val opendir : string -> dir_handle Async_kernel.Deferred.t
val readdir_opt : dir_handle -> string option Async_kernel.Deferred.t

readdir_opt dir_handle returns the next directory member, or None when there are no more directory members to return.

val rewinddir : dir_handle -> unit Async_kernel.Deferred.t
val closedir : dir_handle -> unit Async_kernel.Deferred.t
val pipe : Core.Info.t -> ([ `Reader of Fd.t ] * [ `Writer of Fd.t ]) Async_kernel.Deferred.t

The info supplied to pipe is debugging information that will be included in the returned Fds.

val mkfifo : ?perm:file_perm -> string -> unit Async_kernel.Deferred.t

Create a named pipe with the given permissions.

val mkstemp : string -> (string * Fd.t) Async_kernel.Deferred.t

mkstemp prefix creates and opens a unique temporary file with prefix, automatically appending a suffix of six random characters to make the name unique. Unlike C's mkstemp, prefix should not include six X's at the end.

val mkdtemp : string -> string Async_kernel.Deferred.t
val getgrouplist : string -> int -> int array Async_kernel.Deferred.t
type process_times = Core_unix.process_times = {
  1. tms_utime : float;
    (*

    User time for the process

    *)
  2. tms_stime : float;
    (*

    System time for the process

    *)
  3. tms_cutime : float;
    (*

    User time for the children processes

    *)
  4. tms_cstime : float;
    (*

    System time for the children processes

    *)
}

Time functions.

val times : unit -> process_times
type tm = Core_unix.tm = {
  1. tm_sec : int;
    (*

    Seconds 0..59

    *)
  2. tm_min : int;
    (*

    Minutes 0..59

    *)
  3. tm_hour : int;
    (*

    Hours 0..23

    *)
  4. tm_mday : int;
    (*

    Day of month 1..31

    *)
  5. tm_mon : int;
    (*

    Month of year 0..11

    *)
  6. tm_year : int;
    (*

    Year - 1900

    *)
  7. tm_wday : int;
    (*

    Day of week (Sunday is 0)

    *)
  8. tm_yday : int;
    (*

    Day of year 0..365

    *)
  9. tm_isdst : bool;
    (*

    Daylight time savings in effect

    *)
}
val time : unit -> float
val gettimeofday : unit -> float
val gmtime : float -> tm
val localtime : float -> tm
val mktime : tm -> float * tm
val utimes : string -> access:float -> modif:float -> unit Async_kernel.Deferred.t
type env = Core_unix.env
val sexp_of_env : env -> Sexplib0.Sexp.t
val env_of_sexp : Sexplib0.Sexp.t -> env
val environment : unit -> string array
val getenv : string -> string option
val getenv_exn : string -> string
val unsafe_getenv : string -> string option
val unsafe_getenv_exn : string -> string
val putenv : key:string -> data:string -> unit
val unsetenv : string -> unit
val fork_exec : prog:string -> argv:string list -> ?use_path:bool -> ?env:[ env | `Replace_raw of string list ] -> unit -> Core.Pid.t Async_kernel.Deferred.t

fork_exec ~prog ~argv ?path ?env forks and execs prog with argv, and returns the child pid. If use_path = true (the default) and prog doesn't contain a slash, then fork_exec searches the PATH environment variable for prog. If env is supplied, it specifies the environment when prog is executed.

If env contains multiple bindings for the same variable, the last takes precedence. In the case of `Extend, bindings in env take precedence over the existing environment. See Unix.exec.

type wait_on = [
  1. | `Any
  2. | `Group of Core.Pid.t
  3. | `My_group
  4. | `Pid of Core.Pid.t
]
val sexp_of_wait_on : wait_on -> Sexplib0.Sexp.t
val wait_on_of_sexp : Sexplib0.Sexp.t -> wait_on
val __wait_on_of_sexp__ : Sexplib0.Sexp.t -> wait_on
val wait_nohang : wait_on -> (Core.Pid.t * Exit_or_signal.t) option
val wait_nohang_untraced : wait_on -> (Core.Pid.t * Exit_or_signal_or_stop.t) option

waitpid pid returns a deferred that becomes determined with the child's exit status, when the child process with process id pid exits. waitpid_exn is like waitpid, except the result only becomes determined if the child exits with status zero; it raises if the child terminates in any other way.

Same as waitpid, but guarantees that the resulting Deferred is determined in the same async job as the wait system call, so that it's safe to keep using the pid if the deferred is not determined.

val waitpid_exn : Core.Pid.t -> unit Async_kernel.Deferred.t
module Inet_addr : sig ... end
module Cidr = Core_unix.Cidr
module Protocol_family : sig ... end
val socketpair : unit -> Fd.t * Fd.t
module Socket : sig ... end
val bind_to_interface_exn : (Fd.t -> Linux_ext.Bound_to_interface.t -> unit) Core.Or_error.t
module Host : sig ... end
type socket_domain = Core_unix.socket_domain =
  1. | PF_UNIX
  2. | PF_INET
  3. | PF_INET6
val bin_shape_socket_domain : Core.Bin_prot.Shape.t
val bin_size_socket_domain : socket_domain Core.Bin_prot.Size.sizer
val bin_write_socket_domain : socket_domain Core.Bin_prot.Write.writer
val bin_writer_socket_domain : socket_domain Core.Bin_prot.Type_class.writer
val bin_read_socket_domain : socket_domain Core.Bin_prot.Read.reader
val __bin_read_socket_domain__ : (int -> socket_domain) Core.Bin_prot.Read.reader
val bin_reader_socket_domain : socket_domain Core.Bin_prot.Type_class.reader
val bin_socket_domain : socket_domain Core.Bin_prot.Type_class.t
val compare_socket_domain : socket_domain -> socket_domain -> int
val hash_fold_socket_domain : Ppx_hash_lib.Std.Hash.state -> socket_domain -> Ppx_hash_lib.Std.Hash.state
val hash_socket_domain : socket_domain -> Ppx_hash_lib.Std.Hash.hash_value
val sexp_of_socket_domain : socket_domain -> Sexplib0.Sexp.t
val socket_domain_of_sexp : Sexplib0.Sexp.t -> socket_domain
type socket_type = Core_unix.socket_type =
  1. | SOCK_STREAM
  2. | SOCK_DGRAM
  3. | SOCK_RAW
  4. | SOCK_SEQPACKET
val bin_shape_socket_type : Core.Bin_prot.Shape.t
val bin_size_socket_type : socket_type Core.Bin_prot.Size.sizer
val bin_write_socket_type : socket_type Core.Bin_prot.Write.writer
val bin_writer_socket_type : socket_type Core.Bin_prot.Type_class.writer
val bin_read_socket_type : socket_type Core.Bin_prot.Read.reader
val __bin_read_socket_type__ : (int -> socket_type) Core.Bin_prot.Read.reader
val bin_reader_socket_type : socket_type Core.Bin_prot.Type_class.reader
val bin_socket_type : socket_type Core.Bin_prot.Type_class.t
val compare_socket_type : socket_type -> socket_type -> int
val hash_fold_socket_type : Ppx_hash_lib.Std.Hash.state -> socket_type -> Ppx_hash_lib.Std.Hash.state
val hash_socket_type : socket_type -> Ppx_hash_lib.Std.Hash.hash_value
val sexp_of_socket_type : socket_type -> Sexplib0.Sexp.t
val socket_type_of_sexp : Sexplib0.Sexp.t -> socket_type
type sockaddr = Core_unix.sockaddr =
  1. | ADDR_UNIX of string
  2. | ADDR_INET of Inet_addr.t * int
val bin_shape_sockaddr : Core.Bin_prot.Shape.t
val bin_size_sockaddr : sockaddr Core.Bin_prot.Size.sizer
val bin_write_sockaddr : sockaddr Core.Bin_prot.Write.writer
val bin_writer_sockaddr : sockaddr Core.Bin_prot.Type_class.writer
val bin_read_sockaddr : sockaddr Core.Bin_prot.Read.reader
val __bin_read_sockaddr__ : (int -> sockaddr) Core.Bin_prot.Read.reader
val bin_reader_sockaddr : sockaddr Core.Bin_prot.Type_class.reader
val bin_sockaddr : sockaddr Core.Bin_prot.Type_class.t
val compare_sockaddr : sockaddr -> sockaddr -> int
val sexp_of_sockaddr : sockaddr -> Sexplib0.Sexp.t
type sockaddr_blocking_sexp = sockaddr

sockaddr_blocking_sexp is like sockaddr, with of_sexp that performs DNS lookup to resolve Inet_addr.t.

val bin_shape_sockaddr_blocking_sexp : Core.Bin_prot.Shape.t
val bin_size_sockaddr_blocking_sexp : sockaddr_blocking_sexp Core.Bin_prot.Size.sizer
val bin_write_sockaddr_blocking_sexp : sockaddr_blocking_sexp Core.Bin_prot.Write.writer
val bin_writer_sockaddr_blocking_sexp : sockaddr_blocking_sexp Core.Bin_prot.Type_class.writer
val bin_read_sockaddr_blocking_sexp : sockaddr_blocking_sexp Core.Bin_prot.Read.reader
val __bin_read_sockaddr_blocking_sexp__ : (int -> sockaddr_blocking_sexp) Core.Bin_prot.Read.reader
val bin_reader_sockaddr_blocking_sexp : sockaddr_blocking_sexp Core.Bin_prot.Type_class.reader
val bin_sockaddr_blocking_sexp : sockaddr_blocking_sexp Core.Bin_prot.Type_class.t
val sexp_of_sockaddr_blocking_sexp : sockaddr_blocking_sexp -> Sexplib0.Sexp.t
val sockaddr_blocking_sexp_of_sexp : Sexplib0.Sexp.t -> sockaddr_blocking_sexp
module Addr_info : sig ... end
module Name_info : sig ... end

The following functions correspond to the system calls of the same names. They can't block so they don't need to return a deferred.

val gethostname : unit -> string
val getuid : unit -> int
val geteuid : unit -> int
val getgid : unit -> int
val getegid : unit -> int
val setuid : int -> unit
val setgid : int -> unit
module Error = Core_unix.Error
exception Unix_error of Error.t * string * string
module Terminal_io : sig ... end
module Passwd : sig ... end

Structure of entries in the passwd database.

module Group : sig ... end

Structure of entries in the groups database.

module Ifaddr = Core_unix.Ifaddr
val getifaddrs : unit -> Ifaddr.t list Async_kernel.Deferred.t

Gets the information using the socket-based netlink interface, which can block; see https://www.infradead.org/~tgr/libnl/doc/core.html.

val username : unit -> string Async_kernel.Deferred.t

Returns the name of the user executing the process.

This returns a deferred because the username may need to be looked up in what is essentially a database elsewhere on the network (winbound user, or NIS). This also means that this function isn't guaranteed to succeed: it may raise instead.

val getlogin : unit -> string Async_kernel.Deferred.t

Same as username.

val wordexp : (?flags:[ `No_cmd | `Show_err | `Undef ] list -> string -> string array Async_kernel.Deferred.t) Core.Or_error.t
module Private : sig ... end
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