The Standard ML Basis Library


The Posix.Process structure


Synopsis

signature POSIX_PROCESS
structure Process : POSIX_PROCESS

The structure Posix.Process describes the primitive POSIX operations dealing with processes, as described in Section 3 of the POSIX standard 1003.1,1996[CITE].


Interface

eqtype signal
eqtype pid
val wordToPid : SysWord.word -> pid
val pidToWord : pid -> SysWord.word
val fork : unit -> pid option
val exec  : string * string list -> 'a
val exece : string * string list * string list -> 'a
val execp : string * string list -> 'a
datatype waitpid_arg
  = W_ANY_CHILD
  | W_CHILD of pid
  | W_SAME_GROUP
  | W_GROUP of pid
datatype exit_status
  = W_EXITED
  | W_EXITSTATUS of Word8.word
  | W_SIGNALED of signal
  | W_STOPPED of signal
val fromStatus : OS.Process.status -> exit_status
structure W : sig
    include BIT_FLAGS
    val untraced : flags
  end
val wait : unit -> pid * exit_status
val waitpid : waitpid_arg * W.flags list
                -> pid * exit_status
val waitpid_nh : waitpid_arg * W.flags list
                   -> (pid * exit_status) option
val exit : Word8.word -> 'a
datatype killpid_arg
  = K_PROC of pid
  | K_SAME_GROUP
  | K_GROUP of pid
val kill : killpid_arg * signal -> unit
val alarm : Time.time -> Time.time
val pause : unit -> unit
val sleep : Time.time -> Time.time

Description

eqtype signal
A POSIX signal, an asynchronous notification of an event.

eqtype pid
A process ID, used as an identifier for an operating system process.

val wordToPid : SysWord.word -> pid
val pidToWord : pid -> SysWord.word
These functions convert between a process ID and the integer representation used by the operating system. Note that there is no validation that a pid value generated using wordToPid is legal on the given system or that it corresponds to a currently running process.

val fork : unit -> pid option
This creates a new process. The new child process is a copy of the calling parent process. After execution of fork, both the parent and child process execute independently, but share various system resources. Upon successful completion, fork returns NONE in the child process, and the pid of the child in the parent process. It raises OS.SysErr on failure.

exec (path, args)
exece (path, args, env)
execp (file, args)
These functions replace the current process image with a new process image. There is no return from a successful call, as the calling process image is overlaid by the new process image. In the first two forms, the path argument specifies the pathname of the executable file. In the last form, if file contains a slash character, it is treated as the pathname for the executable file; otherwise, an executable file with name file is searched for in the directories specified by the environment variable PATH.

Normally, the new image is given the same environment as the calling program. The env argument in exece allows the program to specify a new environment.

The args argument is a list of string arguments to be passed to the new program. By convention, the first item in args is some form of the filename of the new program, usually the last arc in the path or filename.

datatype waitpid_arg
= W_ANY_CHILD
Any child process

| W_CHILD of pid
The child process with the given pid

| W_SAME_GROUP
Any child process in the same process group as the calling process

| W_GROUP of pid
Any child process whose process group ID is given by pid.

datatype exit_status
  = W_EXITED
  | W_EXITSTATUS of Word8.word
  | W_SIGNALED of signal
  | W_STOPPED of signal
These values represent the ways in which a process might stop. They correspond to, respectively, terminate successfully, terminate with the given value, terminate upon receipt of the given signal, and stop upon receipt of the given signal. The value carried by W_EXITSTATUS must never be zero.

If an implementation provides both the Posix and Unix structures, then the datatypes Posix.Process.exit_status and Unix.exit_status must be the same.

fromStatus sts
returns a concrete view of the given status.

structure W

val untraced : flags
In systems supporting job control, this flag requests the status of child processes that are stopped.

val wait : unit -> pid * exit_status
This function allows a calling process to obtain status information on any of its child processes. Execution of wait suspends execution until status information on one of its child processes is available. If status information is available prior to the execution of wait, return is immediate. wait returns the process ID of the child and its exit status.

waitpid (procs, l)
is identical to wait except that the status is reported only for child processes specified by procs. A set of flags l may be used to modify the behavior of waitpid.

waitpid_nh (procs, l)
is identical to waitpid, except that the call does not suspend if status information for one of the children specified by procs is not immediately available.
Rationale:

In C, waitpid_nh is handled by waitpid, using an additional flag to indicate no hanging. In SML, the semantics of waitpid_nh indicated a different return type from that of waitpid, hence the split into two functions.



exit i
terminates the calling process. If the parent process is executing a wait related call, the exit status i is made available to it. exit does not return to the caller.

Calling exit does not flush or close any open IO streams, nor does it call OS.Process.atExit. It does close any open POSIX files, and performs the actions associated with the C version of exit.

datatype killpid_arg
= K_PROC of pid
The process with ID pid.

| K_SAME_GROUP
All processes in the same process group as the calling process.

| K_GROUP of pid
All processes in the process group specified by pid.

kill (procs, sig)
sends the signal sig to the process or group of processes specified by procs.

alarm t
causes the system to send an alarm signal (alrm) to the calling process after t seconds have elapsed. If there is a previous alarm request with time remaining, the alarm function returns a nonzero value corresponding to the number of seconds remaining on the previous request. Zero time is returned if there are no outstanding calls.

val pause : unit -> unit
This suspends the calling process until the delivery of a signal that is either caught or that terminates the process.

sleep t
causes the current process to be suspended from execution until either t seconds have elapsed, or until the receipt of a signal that is either caught or that terminates the process.

See Also

BIT_FLAGS, OS.Process, Posix, Posix.Signal

[ Top | Parent | Contents | Index | Root ]

Generated October 02, 2003
Last Modified July 1, 2002
Comments to John Reppy.


This document may be distributed freely over the internet as long as the copyright notice and license terms below are prominently displayed within every machine-readable copy.

Copyright © 2003 AT&T and Lucent Technologies. All rights reserved.

Permission is granted for internet users to make one paper copy for their own personal use. Further hardcopy reproduction is strictly prohibited. Permission to distribute the HTML document electronically on any medium other than the internet must be requested from the copyright holders by contacting the editors. Printed versions of the SML Basis Manual are available from Cambridge University Press. To order, please visit www.cup.org (North America) or www.cup.cam.ac.uk (outside North America).