%**<title>The Haskell 98 Library Report: System functions</title>
%**~header

\section{System Functions}

\outline{
\inputHS{headers/System}
}
\indextt{ExitCode}\indextt{ExitSuccess}\indextt{ExitFailure}
\indextt{getArgs}\indextt{getProgName}\indextt{getEnv}
\indextt{system}\indextt{exitWith}\indextt{exitFailure}

%% It would be less draconian to return [] for operations
%% other than system, exitWith. KH
This library describes the interaction of the program with the
operating system.  

Any @System@ operation could raise an @isIllegalOperation@, as
described in Section~\ref{IOError}; all other permissible errors are
described below.  Note that, in particular, if an implementation does
not support an operation it must raise an @isIllegalOperation@.

The @ExitCode@ type defines the exit codes that a program can return.
@ExitSuccess@ indicates successful termination; and @ExitFailure@
"code" indicates program failure with value "code".  The exact
interpretation of "code" is operating-system dependent.  In
particular, some values of "code" may be prohibited (for instance, 0 on a
POSIX-compliant system).

Computation @getArgs@ returns a list of the program's command
line arguments (not including the program name)\index{program arguments}.
Computation @getProgName@ returns the name of the program
as it was invoked\index{program name}.
Computation @getEnv@~"var" returns the value
of the environment variable "var"\index{environment variables}.
If variable "var" is undefined, the
@isDoesNotExistError@ exception is raised.
 
Computation @system@~"cmd" returns the exit code produced when the
operating system processes the command "cmd"\index{operating system
commands}.

Computation @exitWith@~"code" terminates the program, returning "code"
to the program's caller\index{terminating a program}.  Before the
program terminates, any open or semi-closed handles are first closed.
The caller may interpret the return code as it wishes, but the program
should return @ExitSuccess@ to mean normal completion, and
@ExitFailure @"n" to mean that the program encountered a problem from
which it could not recover.  The value @exitFailure@ is equal to
@exitWith (ExitFailure @"exitfail"@)@, where "exitfail" is
implementation-dependent.  @exitWith@ bypasses the error handling in
the I/O monad and cannot be intercepted by @catch@.

If a program terminates as a result of calling @error@\indextt{error} or
because its value is otherwise determined to be "\bot"\index{"\bot"}, then it
is treated identically to the computation @exitFailure@.  Otherwise, if any
program "p" terminates without calling @exitWith@ explicitly, it is treated
identically to the computation
\bprog
@(@"p"@ >> exitWith ExitSuccess) `catch` \ _ -> exitFailure@
\eprog
\indextt{catch}

%**~footer
