Previous  Up  Next

Module Unix_syscalls

module Unix_syscalls: sig .. end
Unix_syscalls provides an interface to many of the functions in OCaml's standard Unix module. It uses a deferred in the return type of functions that would block. The idea is that in an async program one does not use the standard Unix module, since in doing so one could accidentally block the whole program.

There are also a number of cosmetic changes (e.g. polymorphic variants) and other improvements (e.g. phantom types on sockets) over the standard Unix module.

module Exit: module type of Unix.Exit
module Exit_or_signal: module type of Unix.Exit_or_signal
module Exit_or_signal_or_stop: module type of Unix.Exit_or_signal_or_stop
val system : string -> Exit_or_signal.t Import.Deferred.t
val system_exn : string -> unit Import.Deferred.t
val getpid : unit -> Core.Std.Pid.t
val getppid : unit -> Core.Std.Pid.t option
val getppid_exn : unit -> Core.Std.Pid.t
val this_process_became_child_of_init : ?poll_delay:Core.Std.Time.Span.t -> unit -> unit Import.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 to determine if one's parent has died, because in that case init will becomes one's parent.

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

val nice : int -> int
val cores : (unit -> int Import.Deferred.t) Core.Std.Or_error.t
cores () Returns the number of cores
type open_flag = [ `Append
       | `Creat
       | `Dsync
       | `Excl
       | `Noctty
       | `Nonblock
       | `Rdonly
       | `Rdwr
       | `Rsync
       | `Sync
       | `Trunc
       | `Wronly ] 
type file_perm = int 
val openfile : ?perm:file_perm ->
       string -> mode:open_flag list -> Fd.t Import.Deferred.t
val with_file : ?exclusive:[ `Read | `Write ] ->
       ?perm:file_perm ->
       string ->
       mode:open_flag list ->
       f:(Fd.t -> 'a Import.Deferred.t) -> 'a Import.Deferred.t
with_file file ~mode ~perm ~f ?exclusive 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 exclusive is supplied, then the file descriptor is locked before calling f and unlocked after calling f.
val close : Fd.t -> unit Import.Deferred.t
close fd closes the file descriptor fd, and raises an exception if fd has already been closed.
val lseek : Fd.t -> int64 -> mode:[ `Cur | `End | `Set ] -> int64 Import.Deferred.t
val truncate : string -> len:int64 -> unit Import.Deferred.t
val ftruncate : Fd.t -> len:int64 -> unit Import.Deferred.t
val fsync : Fd.t -> unit Import.Deferred.t
val fdatasync : Fd.t -> unit Import.Deferred.t
val sync : unit -> unit Import.Deferred.t
val lockf : ?len:Core.Std.Int64.t -> Fd.t -> [ `Read | `Write ] -> unit Import.Deferred.t
lockf fd read_or_write ?len exclusively locks for reading/writing 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.
val try_lockf : ?len:Core.Std.Int64.t -> Fd.t -> [ `Read | `Write ] -> bool
try_lockf fd read_or_write ?len attempts to exclusively lock for reading/writing 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.
val test_lockf : ?len:Core.Std.Int64.t -> Fd.t -> bool
lockf_is_locked fd ?len checks the lock on section of the open file fd specified by the current file position and len (see man lockf). If the section is unlocked or locked by this process, it returns true, else it returns false. It raises if fd is closed.
val unlockf : ?len:Core.Std.Int64.t -> Fd.t -> unit
unlockf fd ?len unlocks the section of the open file fd specified by the current file position and len (see man lockf). It raises if fd is closed.
module File_kind: sig .. end
module Stats: sig .. end
val fstat : Fd.t -> Stats.t Import.Deferred.t
val stat : string -> Stats.t Import.Deferred.t
val lstat : string -> Stats.t Import.Deferred.t
val unlink : string -> unit Import.Deferred.t
val rename : src:string -> dst:string -> unit Import.Deferred.t
val link : ?force:bool ->
       target:string -> link_name:string -> unit -> unit Import.Deferred.t
val chmod : string -> perm:file_perm -> unit Import.Deferred.t
val fchmod : Fd.t -> perm:file_perm -> unit Import.Deferred.t
val chown : string -> uid:int -> gid:int -> unit Import.Deferred.t
val fchown : Fd.t -> uid:int -> gid:int -> unit Import.Deferred.t
val access : string ->
       [ `Exec | `Exists | `Read | `Write ] list ->
       (unit, exn) Core.Std.Result.t Import.Deferred.t
val access_exn : string -> [ `Exec | `Exists | `Read | `Write ] list -> unit Import.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 Import.Deferred.t
val rmdir : string -> unit Import.Deferred.t
val chdir : string -> unit Import.Deferred.t
val getcwd : unit -> string Import.Deferred.t
val chroot : string -> unit Import.Deferred.t
type dir_handle = Core.Std.Unix.dir_handle 
val opendir : string -> dir_handle Import.Deferred.t
val readdir : dir_handle -> string Import.Deferred.t
val rewinddir : dir_handle -> unit Import.Deferred.t
val closedir : dir_handle -> unit Import.Deferred.t
val pipe : Core.Std.Info.t ->
       ([ `Reader of Fd.t ] * [ `Writer of Fd.t ]) Import.Deferred.t
The info supplied to pipe is debugging information that will be included in the returned Fds.
val symlink : src:string -> dst:string -> unit Import.Deferred.t
val readlink : string -> string Import.Deferred.t
val mkstemp : string -> (string * Fd.t) Import.Deferred.t
val mkdtemp : string -> string Import.Deferred.t
type process_times = Core.Std.Unix.process_times = {
   tms_utime :float; (*User time for the process*)
   tms_stime :float; (*System time for the process*)
   tms_cutime :float; (*User time for the children processes*)
   tms_cstime :float; (*System time for the children processes*)
}
Time functions.
val times : unit -> process_times
type tm = Core.Std.Unix.tm = {
   tm_sec :int; (*Seconds 0..59*)
   tm_min :int; (*Minutes 0..59*)
   tm_hour :int; (*Hours 0..23*)
   tm_mday :int; (*Day of month 1..31*)
   tm_mon :int; (*Month of year 0..11*)
   tm_year :int; (*Year - 1900*)
   tm_wday :int; (*Day of week (Sunday is 0)*)
   tm_yday :int; (*Day of year 0..365*)
   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 Import.Deferred.t
val environment : unit -> string array
val getenv : string -> string option
val getenv_exn : string -> string
val putenv : key:string -> data:string -> unit
val fork_exec : prog:string ->
       args:string list ->
       ?use_path:bool ->
       ?env:string list -> unit -> Core.Std.Pid.t Import.Deferred.t
fork_exec ~prog ~args ?path ?env forks and execs prog with args, 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 is used as the environment when prog is executed.
type wait_on = [ `Any | `Group of Core.Std.Pid.t | `My_group | `Pid of Core.Std.Pid.t ] 
val wait : wait_on ->
       (Core.Std.Pid.t * Exit_or_signal.t) Import.Deferred.t
val wait_nohang : wait_on ->
       (Core.Std.Pid.t * Exit_or_signal.t) option
val wait_untraced : wait_on ->
       (Core.Std.Pid.t * Exit_or_signal_or_stop.t) Import.Deferred.t
val wait_nohang_untraced : wait_on ->
       (Core.Std.Pid.t * Exit_or_signal_or_stop.t) option
val waitpid : Core.Std.Pid.t -> Exit_or_signal.t Import.Deferred.t
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 win any other way.
val waitpid_exn : Core.Std.Pid.t -> unit Import.Deferred.t
module Inet_addr: sig .. end
module Protocol_family: sig .. end
val socketpair : unit -> Fd.t * Fd.t
module Socket: sig .. end
module Host: sig .. end
val gethostname : unit -> string
val getuid : unit -> int
val geteuid : unit -> int
val getgid : unit -> int
val getegid : unit -> int
val setuid : int -> unit
type error = Core.Std.Unix.error =
| E2BIG
| EACCES
| EAGAIN
| EBADF
| EBUSY
| ECHILD
| EDEADLK
| EDOM
| EEXIST
| EFAULT
| EFBIG
| EINTR
| EINVAL
| EIO
| EISDIR
| EMFILE
| EMLINK
| ENAMETOOLONG
| ENFILE
| ENODEV
| ENOENT
| ENOEXEC
| ENOLCK
| ENOMEM
| ENOSPC
| ENOSYS
| ENOTDIR
| ENOTEMPTY
| ENOTTY
| ENXIO
| EPERM
| EPIPE
| ERANGE
| EROFS
| ESPIPE
| ESRCH
| EXDEV
| EWOULDBLOCK
| EINPROGRESS
| EALREADY
| ENOTSOCK
| EDESTADDRREQ
| EMSGSIZE
| EPROTOTYPE
| ENOPROTOOPT
| EPROTONOSUPPORT
| ESOCKTNOSUPPORT
| EOPNOTSUPP
| EPFNOSUPPORT
| EAFNOSUPPORT
| EADDRINUSE
| EADDRNOTAVAIL
| ENETDOWN
| ENETUNREACH
| ENETRESET
| ECONNABORTED
| ECONNRESET
| ENOBUFS
| EISCONN
| ENOTCONN
| ESHUTDOWN
| ETOOMANYREFS
| ETIMEDOUT
| ECONNREFUSED
| EHOSTDOWN
| EHOSTUNREACH
| ELOOP
| EOVERFLOW
| EUNKNOWNERR of int 
exception Unix_error of error * 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. 
val getlogin : unit -> string Import.Deferred.t
Return the login 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).

val wordexp : ?flags:[ `No_cmd | `Show_err | `Undef ] list ->
       string -> string array Import.Deferred.t
val wait_on_of_sexp : Sexplib.Sexp.t -> wait_on
val wait_on_of_sexp__ : Sexplib.Sexp.t -> wait_on
val sexp_of_wait_on : wait_on -> Sexplib.Sexp.t

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 win any other way.

of_string_or_getbyname hostname does a DNS lookup of hostname and returns the resulting IP address. The implemenation sequentializes all calls so that only a single call is active at a time. The is because we've observed thread safety issues with certain versions of winbind using "wins" name resolution.

Sockets have a phantom type parameter that tracks the state of the socket in order to eliminate certain errors in which socket functions are called in the wrong order. Initially, a socket is `Unconnected. As various socket functions are called, they return a socket with a new phantom state. Here is a chart of the allowed state transitions.

Unconnected ---connect--> Active | | ---bind--> Bound ---listen--> Passive ---accept---> Active

val error_of_sexp : Sexplib.Sexp.t -> error
val sexp_of_error : error -> Sexplib.Sexp.t
val ounit_tests : unit -> OUnit.test

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 to determine if one's parent has died, because in that case init will becomes one's parent.

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

cores () Returns the number of cores

with_file file ~mode ~perm ~f ?exclusive 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 exclusive is supplied, then the file descriptor is locked before calling f and unlocked after calling f.

close fd closes the file descriptor fd, and raises an exception if fd has already been closed.

lockf fd read_or_write ?len exclusively locks for reading/writing 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.

try_lockf fd read_or_write ?len attempts to exclusively lock for reading/writing 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.

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

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

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

Time functions.

User time for the process

System time for the process

User time for the children processes

System time for the children processes

Seconds 0..59

Minutes 0..59

Hours 0..23

Day of month 1..31

Month of year 0..11

Year - 1900

Day of week (Sunday is 0)

Day of year 0..365

Daylight time savings in effect

fork_exec ~prog ~args ?path ?env forks and execs prog with args, 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 is used as the environment when prog is executed.

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 win any other way.

of_string_or_getbyname hostname does a DNS lookup of hostname and returns the resulting IP address. The implemenation sequentializes all calls so that only a single call is active at a time. The is because we've observed thread safety issues with certain versions of winbind using "wins" name resolution.

Sockets have a phantom type parameter that tracks the state of the socket in order to eliminate certain errors in which socket functions are called in the wrong order. Initially, a socket is `Unconnected. As various socket functions are called, they return a socket with a new phantom state. Here is a chart of the allowed state transitions.

Unconnected ---connect--> Active | | ---bind--> Bound ---listen--> Passive ---accept---> Active

Ignore the break condition.

Signal interrupt on break condition.

Ignore characters with parity errors.

Mark parity errors.

Enable parity check on input.

Strip 8th bit on input characters.

Map NL to CR on input.

Ignore CR on input.

Map CR to NL on input.

Recognize XON/XOFF characters on input.

Emit XON/XOFF chars to control input flow.

Enable output processing.

Output baud rate (0 means close connection).

Input baud rate.

Number of bits per character (5-8).

Number of stop bits (1-2).

Reception is enabled.

Enable parity generation and detection.

Specify odd parity instead of even.

Hang up on last close.

Ignore modem status lines.

Generate signal on INTR, QUIT, SUSP.

Enable canonical processing (line buffering and editing)

Disable flush after INTR, QUIT, SUSP.

Echo input characters.

Echo ERASE (to erase previous character).

Echo KILL (to erase the current line).

Echo NL even if c_echo is not set.

Interrupt character (usually ctrl-C).

Quit character (usually ctrl-\).

Erase character (usually DEL or ctrl-H).

Kill line character (usually ctrl-U).

End-of-file character (usually ctrl-D).

Alternate end-of-line char. (usually none).

Minimum number of characters to read before the read request is satisfied.

Maximum read wait (in 0.1s units).

Start character (usually ctrl-Q).

Stop character (usually ctrl-S).

Structure of entries in the passwd database.

Structure of entries in the groups database.

Return the login 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).