Return the file descriptor as integer. See also Netsys.int64_of_file_descr which works for all OS.

Make a file descriptor from an integer

Same as getpgid 0, i.e. returns the process group ID of the current process.

Same as setpgid 0 0: A new process group ID is created, and the current process becomes its sole member.

with_tty f: Runs f fd where fd is the terminal of the process. If the process does not have a terminal (because it is a daemon) with_tty will fail.

tty_read_password prompt: If tty is a terminal, the prompt is printed, and a password is read from the terminal (echo off). If tty is not a terminal, no prompt is printed, and just a line is read from the tty descriptor (non-interactive case).

tty defaults to Unix.stdin. If this function is used in a program where stdin is not redirected, and the program is started in a terminal, it will read the password with prompt and echo disabled. If stdin is redirected, it is assumed that the program is used in a script, and the password is piped into it.

Use in conjunction with with_tty to ensure that tty is the terminal even if a redirection is in effect, e.g.

with_tty (fun tty -> tty_read_password ~tty prompt)

Raises Sys.Break if the user triggers SIGINT (i.e. presses CTRL-C) to abort the input of a password.

Whether the *at functions are available (they were only recently standardized and cannot be expected on all OS yet)

Pseudo descriptor value to be used as first argument of *at functions

Same as Unix.openfile but open relative to the directory given by first argument

Same as Unix.access but the file is taken relative to the directory given by first argument

Same as Unix.mkdir but the file is taken relative to the directory given by first argument

renameat olddirfd oldpath newdirfd newpath

linkat olddirfd oldpath newdirfd newpath flags

Same as Unix.unlink but unlink the file relative to the directory given by first argument

symlinkat oldpath newdirfd newpath flags

mkfifoat dirfd path mode

NB. MacOS 10.10 doesn't support mkfifoat although the other "at" functions are implemented. Be prepared to get Invalid_argument.

readlinkat dirfd path

Whether there is a native poll implementation on this OS

poll_req_events rd wr pri: Create a set of in events consisting of the bits rd, wr, and pri. rd means to poll for input data, wr to poll for output data, and pri to poll for urgent input data.

Looks into a poll_req_events value, and returns the triple (rd,wr,pri).

Create an empty set of poll_act_events, for initilization of poll cells.

Look whether there is any event in poll_out_events

Look for the bit in poll_act_events and return the status

Create a poll array with the given size. The poll_fd member is initialized with Unix.stdin, and the two event members are empty.

set_poll_cell a k c: Sets the poll cell k to c. The index k must be in the range from 0 to N-1 when N is the length of the poll array.

get_poll_cell a k: Returns the poll cell k. The index k must be in the range from 0 to N-1 when N is the length of the poll array.

blit_poll_array a1 p1 a2 p2 len: Copies the len cells at index p1 from a1 to a2 at index p2.

Return the number of cells in the poll array

poll a n tmo: Poll for the events of the cells 0 to n-1 of poll array a, and set the poll_act_events member of all cells. Wait for at most tmo seconds (a negative value means there is no timeout). Returns the number of ready file descriptors.

On platforms without native support for poll the function is emulated using Unix.select. Note, however, that there is a performance penalty for the emulation, and that the output flags poll_error_result, poll_hangup_result, and poll_invalid_result are not emulated.

A wrapper around poll that handles the EINTR condition

poll_single fd rd wr pri tmo: Polls a single descriptor for the events given by rd, wr, and pri. In tmo the timeout can be passed. Returns true if one of the requested events is indicated for the descriptor. The EINTR case is not handled.

Whether there is an implementation for this OS

create_event_aggregator is_interruptible: Creates a new aggregator, and allocates the required OS resources.

If is_interruptible, the aggregator can be interrupted from a different thread. See interrupt_event_aggregator below.

Frees all OS resources

Wraps a file descriptor as event_source, and monitors the events in poll_req_events.

The event_source contains state about the relation to the aggregator, and because of this, the event_source should only be used together with one aggregator (at a time).

Modifies the set of events monitored at this event source

Get the file descriptor wrapped by this event source

Return the actual events of the source. This is updated when poll_event_sources returns the source.

Adds the event source to the aggregator

Removes the source from the aggregator

If create_event_aggregator was called with true as argument, the aggregator is interruptible, and this function interrupts it. The effect is that a currently running poll_event_sources, or, if it is not running, the next invocation of poll_event_sources returns immediately.

If the aggregator is not interruptible, this function is a NOP.

Pushes all modifications of the sources to the kernel

poll_event_sources ea tmo: First, all modifications are pushed to the kernel, and polling is set up to get events. If no events can currently be delivered, the function waits up to tmo seconds (or endlessly if negative) for events. The function returns only a limited number of events at a time. It is allowed that the function returns fewer events than are currently in signalled state, even none.

Call the function with tmo=0.0 for non-blocking behavior.

Note that this is the "level-triggered" behavior: If a source remains active it will be reported again by the next poll_event_sources, just as poll would do.

Returns the underlying file descriptor. It is implementation-defined whether this descriptor can also be polled for events. Generally, you should run push_event_updates before polling from the descriptor.

Registers a new post fork handler (MT-Safe)

Removes a post fork handler from the registry (MT-Safe)

Runs all post fork handlers. Exceptions are caught and printed to stderr.

spawn cmd args: Fork the process and exec cmd which gets the arguments args. On success, the PID of the new process is returned. This function does not wait for the completion of the process; use Unix.waitpid for this purpose.

• chdir: If set, the new process starts with this working directory (this is done before anything else)
• pg: If set, the new process will be a member of this process group
• fd_actions: If set, these descriptor actions are executed sequentially
• sig_actions: If set, these signal actions are executed sequentially
• env: If set, the process gets this environment instead of the current one
• no_posix_spawn: If set, the posix_spawn family of library functions is not used to spawn even if possible, and always a fork/exec approach is taken. This may be slower, but there is normally better error reporting.

Any exceptions in the subprocess are detected, and reported. However, if Fda_close_ignore leads to EBADF for a descriptor, this error is ignored.

If pg=Pg_new_fg_group, one should include Sig_ignore Sys.sigttou in sig_actions.

There are two implementations for spawn: One calls fork and exec directly, and one uses the posix_spawn family of library functions. The latter is faster on certain conditions, but this is very OS-specific. A number of features are not supported by posix_spawn and will force that fork/exec is used: Wd_chdir, Wd_fchdir, Pg_new_fg_group, and Sig_ignore. However, note some implementations of posix_spawn also fall back to fork/exec internally for some combinations of flags, and it is hard to predict which spawn calls can actually be accelerated. The tendency, though, is that recent OS have sped up posix_spawn so far possible (e.g. by using vfork internally, or even by making posix_spawn a system call).

Creates a new event file descriptor.

Releases the OS resources. Note that there can be a hidden second file descriptor, so closing the descriptor returned by get_event_fd is not sufficient.

report_signal_as_event ev sig Installs a new signal handler for signal sig so that ev is signalled when a signal arrives.

let fd, ws = watch_subprocess pid pgid kill_flag: Enters the subprocess pid into the watch list. If pgid > 0, the process group ID is pgid (for killpg_subprocess and killpg_all_subprocesses). The kill_flag controls the process selection of kill_all_subprocesses and killpg_all_subprocesses.

The returned descriptor fd is open for reading and will indicate EOF when the subprocess is terminated. Via ws it is possible to query information about the subprocess. The installed signal handler will wait for the subprocess and put the process status into ws.

The caller has to close fd after the termination is signaled.

Changes the arrangement so that the termination of the subprocess is no longer reported by the file descriptor. The file descriptor indicates EOF immediately (and can be closed by the caller). Nevertheless, the signal handler still waits for the subprocess to avoid zombies.

Any further access to ws will fail.

Frees OS resources. Any further access to the ws will fail.

If the subprocess is terminated, this function returns the status. Otherwise None is returned

Sends this signal to the subprocess if this process still exists. Never throws an exception.

Sends this signal to the process group of the subprocess if there is still a watched subprocess belonging to this group. Never throws an exception.

kill_all_subprocess signal override nogroup: Sends a signal to potentially all subprocesses. The signal is sent to a watched process if the process still exists, and these two conditions hold both:

• not nogroup || pgid = 0: Processes with pgid > 0 are excluded if nogroup is set
• kill_flag || override: A process needs to have kill_flag set, or override is specified

Never throws an exception if the signal handler is installed.

killpg_all_subprocess signal override: Sends a signal to potentially all subprocesses belonging to a process group (i.e. pgid>0). . The signal is sent to a process group if there are still watched subprocesses belonging to the group, and if either the kill_flag of any of the subprocesses process was set to true, or override is true.

Never throws an exception if the signal handler is installed.

Installs a SIGCHLD handler for watching subprocesses. Note that only processes are waited for that are registered with watch_subprocess.

The handler works both in the single-threaded and the multi-threaded case. install_subprocess_handler can safely called several times. The handler is installed every time the function is called, but the required data structures are only initialized at the first call.

Uses the [root:Netsys_signal] framework to manage the installation of the SIGCHLD handler.

This is the preferred method of installing the SIGCHLD handler.

openlog ident options facility: Opens a log stream. ident is prepended to every message if given (usually the program name). The facility is the default facility for syslog calls.

syslog facility level message: Logs message at level for facility

Closes the log stream

let (fd,name) = shm_create prefix size: Creates an shm object with a unique name. The name has the passed prefix. The prefix must start with "/" but must not contain any further "/". The object has a length of size bytes. The object has a permissions 0o600 (independent of umask).

Returns true if named POSIX semaphores are supported on this system

Returns true if anonymous POSIX semaphores are supported on this system

Returns true if both kinds of semaphores are supported on this system

The maximum value of a semaphore, but at most max_int

The size of an anonymous semaphore in bytes (sizeof(sem_t))

sem_open name flags mode init_value: Opens a named semaphore which is optionally created. Sempahore names usually begin with a slash followed by a single name component (not containing a further slash).

Interpretation of flags:

• SEM_O_CREAT: The semaphore is created if not yet existing. The mode and init_value are interpreted if the creation actually occurs. mode is the permission of the semaphore. init_value is the (non-negative) initial value, up to sem_value_max.
• SEM_O_EXCL: The semaphore is only opened if the semaphore does not exist yet. Othwerwise an EEXIST error is returned

Closes a named semaphore. Semaphores are also automatically closed when the GC finds that the semaphore is unreachable.

Unlinks the semaphore name

let (sem,name) = sem_create prefix init_value: Creates a new semaphore with a unique name. The name has the passed prefix. The prefix must start with "/" but must not contain any further "/". The semaphore is initialized with init_value. The object has permissions 0o600 (modulo umask).

sem_init mem pos pshared init_value: Initializes the memory at position pos to pos + sem_size() - 1 as anonymous semaphore. If pshared the semaphore is shared between processes. init_value is the initial non-negative value (max is sem_value_max.

Destroys the anonymous semaphore

as_sem mem pos: Interprets the memory at position pos to pos + sem_size() - 1 as anonymous semaphore. The memory region must already have been initialized.

Returns the value of the semaphore. If the value is bigger than what can be represented as int, an EINVAL error is returned.

The returned value is non-negative - if the underlying POSIX function reports a negative value zero is returned instead.

Unavailable on MacOS.

Unlocks the semaphore (increases the value by 1)

Locks the semaphore (decreases the value by 1). If the semaphore value is already zero, and SEM_WAIT_BLOCK is given, the function waits until another process or thread posts. If SEM_WAIT_NONBLOCK the error EAGAIN is returned.

sem_wait may be interrupted by signals.

query_langinfo locale: Temporarily sets the passed locale and determines the language attributes. After that the orignal locale is restored. Pass "" as locale to get the locale requested in the environment.

The value for "" is cached.

Create a new timer that will report expiration as given by the arg:

• TEXP_NONE: no notification
• TEXP_EVENT e: the not_event e is signalled
• TEXP_EVENT_CREATE: a special not_event is created for the timer. (Get the event via timer_event, see below.)
• TEXP_SIGNAL n: the signal n is sent to the process

Note that TEXP_EVENT_CREATE is much faster on Linux than TEXP_EVENT, because it can be avoided to start a new thread whenever the timer expires. Instead, the timerfd machinery is used.

TEXP_EVENT and TEXP_EVENT_CREATE are only supported on systems with pthreads.

timer_settime tm abstime interval value:

If value=(0.0,0), the timer is stopped.

If value is a positive time, the timer is started (or the timeout is changed if it is already started). If abstime, value is interpreted as the absolute point in time of the expiration. Otherwise value sets the number of seconds until the expiration.

If interval is positive, the started timer will repeat to expire after this many seconds once it has expired for the first time. If interval=(0.0,0), the timer is a one-shot timer.

Returns the number of seconds until the expiration, or (0.0,0) if the timer is off

Deletes the timer

Returns the notification event for the timer styles TEXP_EVENT and TEXP_EVENT_CREATE.

Note that the latter type of event does not allow to call set_event.

Returns true if the system call ioprio_get is supported