module Netsys_posix:POSIX-specific system calls missing in thesig
..end
Unix
moduletype
poll_array
poll_cell
entriestype
poll_req_events
type
poll_act_events
poll_req_events
is used to request that certain
event types are observed. poll_act_event
shows which
event types are actually possibletype
poll_cell = {
|
mutable poll_fd : |
|
mutable poll_req_events : |
|
mutable poll_act_events : |
poll_fd
. The poll_req_events
are the events the descriptor is polled for. The poll_act_events
are the actually reported events.val have_poll : unit -> bool
poll
implementation on this OSval poll_req_events : bool -> bool -> bool -> poll_req_events
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.val poll_req_triple : poll_req_events -> bool * bool * bool
poll_req_events
value, and returns the triple
(rd,wr,pri)
.val poll_null_events : unit -> poll_act_events
poll_act_events
, for initilization
of poll cells.val poll_result : poll_act_events -> bool
poll_out_events
val poll_rd_result : poll_act_events -> bool
val poll_wr_result : poll_act_events -> bool
val poll_pri_result : poll_act_events -> bool
val poll_err_result : poll_act_events -> bool
val poll_hup_result : poll_act_events -> bool
val poll_nval_result : poll_act_events -> bool
poll_act_events
and return the statusval create_poll_array : int -> poll_array
poll_fd
member is
initialized with Unix.stdin
, and the two event members are empty.val set_poll_cell : poll_array -> int -> poll_cell -> unit
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.val get_poll_cell : poll_array -> int -> poll_cell
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.val blit_poll_array : poll_array ->
int -> poll_array -> int -> int -> unit
blit_poll_array a1 p1 a2 p2 len
: Copies the len
cells at index p1
from a1
to a2
at index p2
.val poll_array_length : poll_array -> int
val poll : poll_array -> int -> float -> int
poll a n tmo
: Poll for the events of the cells 0 to n-1
of
poll array a
, and set the poll_revents
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.
val restarting_poll : poll_array -> int -> float -> int
poll
that handles the EINTR
conditionval poll_single : Unix.file_descr -> bool -> bool -> bool -> float -> bool
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.poll_req_events
and poll_act_events
are integers that
are bitmasks of some constants. The following functions allow access to
this detail.val int_of_req_events : poll_req_events -> int
val int_of_act_events : poll_act_events -> int
val req_events_of_int : int -> poll_req_events
val act_events_of_int : int -> poll_act_events
val const_rd_event : int
val const_wr_event : int
val const_pri_event : int
val const_err_event : int
val const_hup_event : int
val const_nval_event : int
Unix.fork
at some places to create child processes
for doing real work. The following functions
allow it to register a handler that is run in the forked child
process. Note that this is done by the O'caml code calling fork
,
and not via the POSIX atfork()
facility.
The handler should release OS resources like file descriptors that are by default shared with the parent process.
The handler are not invoked when the only purpose of the fork
is
to exec
a different process.
class type post_fork_handler =object
..end
post_fork_handler
is a named function unit -> unit
val register_post_fork_handler : post_fork_handler -> unit
val remove_post_fork_handler : post_fork_handler -> unit
val run_post_fork_handlers : unit -> unit
val int_of_file_descr : Unix.file_descr -> int
Netsys.int64_of_file_descr
which works for all OS.val file_descr_of_int : int -> Unix.file_descr
val sysconf_open_max : unit -> int
fd
:
fd < sysconf_open_max()
val getpgid : int -> int
val getpgrp : unit -> int
getpgid 0
, i.e. returns the process group ID of the
current process.val setpgid : int -> int -> unit
setpgid pid pgid
: Set the process group ID of the process pid
to pgid
. If pid = 0
, the process group ID of the current process
is changed. If pgid = 0
, as process group ID the process ID of the
process referenced by pid
is used.
It is only possible for a process to join a process group if both
belong to the same session.
val setpgrp : unit -> unit
setpgid 0 0
: A new process group ID is created, and the
current process becomes its sole member.val tcgetpgrp : Unix.file_descr -> int
val tcsetpgrp : Unix.file_descr -> int -> unit
val ctermid : unit -> string
val ttyname : Unix.file_descr -> string
val getsid : int -> int
val setreuid : int -> int -> unit
val setregid : int -> int -> unit
type
wd_spec =
| |
Wd_keep |
| |
Wd_chdir of |
| |
Wd_fchdir of |
type
pg_spec =
| |
Pg_keep |
| |
Pg_new_bg_group |
| |
Pg_new_fg_group |
| |
Pg_join_group of |
type
fd_action =
| |
Fda_close of |
(* | Close the descriptor | *) |
| |
Fda_close_ignore of |
(* | Close the descriptor but ignore EBADF errors | *) |
| |
Fda_close_except of |
(* | Closes all descriptors except those for which
except.(k) is true where k = int_of_file_descr fd .
Descriptors outside the array index range are closed. | *) |
| |
Fda_dup2 of |
(* | Duplicate the first descriptor to the second as dup2 does | *) |
type
sig_action =
| |
Sig_default of |
| |
Sig_ignore of |
val spawn : ?chdir:wd_spec ->
?pg:pg_spec ->
?fd_actions:fd_action list ->
?sig_actions:sig_action list ->
?env:string array -> string -> string array -> int
spawn cmd args
: Fork the process and exec cmd
which gets the
arguments args
. On success, the PID of the new process is returned.
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 groupfd_actions
: If set, these descriptor actions are executed
sequentiallysig_actions
: If set, these signal actions are executed sequentiallyenv
: If set, the process gets this environment instead of the
current oneFda_close
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
.
install_subprocess_handler
type
watched_subprocess
val watch_subprocess : int -> int -> bool -> Unix.file_descr * watched_subprocess
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.
val ignore_subprocess : watched_subprocess -> unit
wait
s for the subprocess
to avoid zombies.
Any further access to ws
will fail.
val forget_subprocess : watched_subprocess -> unit
ws
will fail.val get_subprocess_status : watched_subprocess -> Unix.process_status option
None
is returnedval kill_subprocess : int -> watched_subprocess -> unit
val killpg_subprocess : int -> watched_subprocess -> unit
val kill_all_subprocesses : int -> bool -> bool -> unit
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 setkill_flag || override
: A process needs to have
kill_flag
set, or override
is specifiedval killpg_all_subprocesses : int -> bool -> unit
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.
val install_subprocess_handler : unit -> unit
wait
ed 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.
val register_subprocess_handler : unit -> unit
Netsys_signal
framework to manage the installation of
the SIGCHLD handler.
This is the preferred method of installing the SIGCHLD handler.
fork()
: The subprocess handler uses
pipes for notification, and because of this it is sensitive to
unpredicted duplicates of the pipe descriptors. fork()
duplicates
these pipe descriptors. If nothing is done about this issue, it
can happen that the notification does not work anymore as it relies
on detecting closed pipes.
If fork()
is immediately followed by exec()
(as it is done
to run subcommands), the problem does not occur, because the relevant
descriptors are closed at exec()
time.
If fork()
is used to start worker processes, however, we have
to be careful. The descriptors need to be closed, so that the
parent can continue to monitor subprocesses, and to allow the worker
processes to use this mechanism. This module defines post fork
handlers (see above), and a handler is automatically added that
cleans the descriptors up. All user code has to do is to call
run_post_fork_handlers
immediately after fork()
has spawned
the new child, from the new child. This completely resets
everything.
The subprocess handler and multi-threading: The handler has been
carefully designed, and works even in multi-threaded programs.
However, one should know that multi-threading and fork()
do not
interact well with each other. Again, the problems do not occur
if fork()
is followed by exec()
. There is no solution for the
case that worker processes are started with fork()
, though.
The (very generic) problem is that the state of mutexes and other
multi-threading primitives is not well-defined after a fork()
.
typelevel =
Netlog.level
typesyslog_facility =
[ `Authpriv
| `Cron
| `Daemon
| `Default
| `Ftp
| `Kern
| `Local0
| `Local1
| `Local2
| `Local3
| `Local4
| `Local5
| `Local6
| `Local7
| `Lpr
| `News
| `Syslog
| `User
| `Uucp ]
`User
and `Local0
to `Local7
are
standard POSIX. If a facility is unavailable it is silently
substituted by `Local0
. The value `Default
leaves this unspecified.typesyslog_option =
[ `Cons | `Ndelay | `Nowait | `Odelay | `Pid ]
`Cons
: Fall back to console logging if syslog is unavailable`Ndelay
: Open the connection immediately`Odelay
: Open the connection at the first call syslog
(default)`Nowait
: Do not wait until it is ensured that the message is
sent`Pid
: Log the PID with every messageval openlog : string option ->
syslog_option list -> syslog_facility -> unit
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.val syslog : syslog_facility -> level -> string -> unit
syslog facility level message
: Logs message
at level
for
facility
val closelog : unit -> unit
Netlog.current_logger
to syslog facility
, e.g.
Netlog.current_logger := Netsys_posix.syslog `User
val fsync : Unix.file_descr -> unit
val fdatasync : Unix.file_descr -> unit
fsync
val have_fadvise : unit -> bool
type
advice =
| |
FADV_NORMAL |
| |
FADV_SEQUENTIAL |
| |
FADV_RANDOM |
| |
FADV_NOREUSE |
| |
FADV_WILLNEED |
| |
FADV_DONTNEED |
val fadvise : Unix.file_descr -> int64 -> int64 -> advice -> unit
val have_fallocate : unit -> bool
val fallocate : Unix.file_descr -> int64 -> int64 -> unit
val have_posix_shm : unit -> bool
type
shm_open_flag =
| |
SHM_O_RDONLY |
| |
SHM_O_RDWR |
| |
SHM_O_CREAT |
| |
SHM_O_EXCL |
| |
SHM_O_TRUNC |
val shm_open : string -> shm_open_flag list -> int -> Unix.file_descr
The open flags are interpreted as follows:
SHM_O_RDONLY
: Open the object for read accessSHM_O_RDWR
: Open the object for read-write accessSHM_O_CREAT
: Create the object if it does not existSHM_O_EXCL
: If SHM_O_CREAT
was also specified, and a an object
with the given name already exists, return an error
(Unix.EEXIST
).SHM_O_TRUNC
: If the object already exists, truncate it to
zero bytesSHM_O_RDONLY
or SHM_O_RDWR
must be given.
On success, the function returns a file descriptor representing the
object. To access the object, one has to memory-map this file
use one of the map_file
functions in the Bigarray
module, or in Netsys_mem
). Use Unix.ftruncate
to resize the object.
Note that it is unspecified whether this file pops up somewhere in the file system, and if so, where.
If a system error occurs, the function raises a Unix.Unix_error
exception.
val shm_unlink : string -> unit
val have_posix_semaphores : unit -> bool
true
if POSIX semaphores are supported on this systemval sem_value_max : int
max_int
val sem_size : int
sizeof(sem_t)
)typesem_kind =
[ `Anonymous | `Named ]
type 'a
semaphore
typenamed_semaphore =
[ `Named ] semaphore
typeanon_sempahore =
[ `Anonymous ] semaphore
type
sem_open_flag =
| |
SEM_O_CREAT |
| |
SEM_O_EXCL |
val sem_open : string ->
sem_open_flag list -> int -> int -> named_semaphore
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 returnedval sem_close : named_semaphore -> unit
val sem_unlink : string -> unit
val sem_init : Netsys_types.memory -> int -> bool -> int -> anon_sempahore
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
.val sem_destroy : anon_sempahore -> unit
val as_sem : Netsys_types.memory -> int -> anon_sempahore
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.val sem_getvalue : 'a semaphore -> int
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.
val sem_post : 'a semaphore -> unit
type
sem_wait_behavior =
| |
SEM_WAIT_BLOCK |
| |
SEM_WAIT_NONBLOCK |
val sem_wait : 'a semaphore -> sem_wait_behavior -> unit
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.
Per-process I/O priorities are currently only supported by the
CFQ I/O scheduler.
val have_ioprio : unit -> bool
true
if the system call ioprio_get
is supportedtype
ioprio_target =
| |
Ioprio_process of |
(* | A single process | *) |
| |
Ioprio_pgrp of |
(* | A process group | *) |
| |
Ioprio_user of |
(* | All processes owned by this user | *) |
type
ioprio =
| |
Noprio |
(* | I/O prioritization is unsupported by block layer | *) |
| |
Real_time of |
(* | 0..7 (higest..lowest prio) | *) |
| |
Best_effort of |
(* | 0..7 (higest..lowest prio) | *) |
| |
Idle |
val ioprio_get : ioprio_target -> ioprio
ESRCH
will be raised.val ioprio_set : ioprio_target -> ioprio -> unit
module Debug:sig
..end