--------------------------------
[haskell-report.git] / report / system.verb
1 %**<title>The Haskell 98 Library Report: System functions</title>
2 %**~header
3
4 \section{System Functions}
5
6 \outline{
7 \inputHS{lib-hdrs/System}
8 }
9 \indextt{ExitCode}\indextt{ExitSuccess}\indextt{ExitFailure}
10 \indextt{getArgs}\indextt{getProgName}\indextt{getEnv}
11 \indextt{system}\indextt{exitWith}\indextt{exitFailure}
12
13 %% It would be less draconian to return [] for operations
14 %% other than system, exitWith. KH
15 This library describes the interaction of the program with the
16 operating system.  
17
18 Any @System@ operation could raise an @isIllegalOperation@, as
19 described in Section~\ref{IOError}; all other permissible errors are
20 described below.  Note that, in particular, if an implementation does
21 not support an operation it must raise an @isIllegalOperation@.
22
23 The @ExitCode@ type defines the exit codes that a program can return.
24 @ExitSuccess@ indicates successful termination; and @ExitFailure@
25 "code" indicates program failure with value "code".  The exact
26 interpretation of "code" is operating-system dependent.  In
27 particular, some values of "code" may be prohibited (for instance, 0 on a
28 POSIX-compliant system).
29
30 Computation @getArgs@ returns a list of the program's command
31 line arguments (not including the program name)\index{program arguments}.
32 Computation @getProgName@ returns the name of the program
33 as it was invoked\index{program name}.
34 Computation @getEnv@~"var" returns the value
35 of the environment variable "var"\index{environment variables}.
36 If variable "var" is undefined, the
37 @isDoesNotExistError@ exception is raised.
38  
39 Computation @system@~"cmd" returns the exit code produced when the
40 operating system processes the command "cmd"\index{operating system
41 commands}.
42
43 Computation @exitWith@~"code" terminates the program, returning "code"
44 to the program's caller\index{terminating a program}.  Before the
45 program terminates, any open or semi-closed handles are first closed.
46 The caller may interpret the return code as it wishes, but the program
47 should return @ExitSuccess@ to mean normal completion, and
48 @ExitFailure @"n" to mean that the program encountered a problem from
49 which it could not recover.  The value @exitFailure@ is equal to
50 @exitWith (ExitFailure @"exitfail"@)@, where "exitfail" is
51 implementation-dependent.  @exitWith@ bypasses the error handling in
52 the I/O monad and cannot be intercepted by @catch@.
53
54 If a program terminates as a result of calling @error@\indextt{error} or
55 because its value is otherwise determined to be "\bot"\index{"\bot"}, then it
56 is treated identically to the computation @exitFailure@.  Otherwise, if any
57 program "p" terminates without calling @exitWith@ explicitly, it is treated
58 identically to the computation
59 \bprog
60 @(@"p"@ >> exitWith ExitSuccess) `catch` \ _ -> exitFailure@
61 \eprog
62 \indextt{catch}
63
64 %**~footer