1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
|
******************************************************************************
README - Shell: Pipelines and redirections
******************************************************************************
==============================================================================
Abstract
==============================================================================
Shell provides some of the functionality of a Unix shell; in particular the
library supports starting simple commands, executing pipelined commands, and
arranging redirections.
==============================================================================
Download
==============================================================================
You can download Shell as gzip'ed tarball [1].
==============================================================================
Documentation
==============================================================================
Sorry, there is no manual. The mli files describe each function in detail.
Furthermore, the following additional information may be useful.
------------------------------------------------------------------------------
Module "Shell": The comfortable layer
------------------------------------------------------------------------------
This module is designed for the average user who does not know very much about
the Unix process model, and just wants to start external commands. A simple
command can be executed by a statement like
call [ cmd "ls" [ "/dir1"; "/dir2" ]]
This statement searches "ls" in the current search PATH, launches the new
process, and passes the arguments "/dir1" and /dir2" to the process. Nothing
special is done with the file descriptors; the new process shares stdin, stdout
and stderr with the current process (all other descriptors are automatically
closed).
A pipeline can be constructed by "call" as well. For example:
call [ cmd "find" [ "/dir" ]; cmd "grep" [ "something" ] ]
The output of "find" is redirected to the input of "grep".
You can redirect stdin, stdout, stderr (and every other descriptor) by
assigning them to other descriptors, or by opening and reading from or writing
to them. In the latter case, multiple descriptors can be served parallely. For
example:
let s = "d\na\nc\nb\n" in
let b = Buffer.create 20 in
call ~stdin:(from_string s) ~stdout:(to_buffer b) [ cmd "sort" ]
Here, "sort" reads the contents of s and writes the result to b.
Unlike the Unix shell, this module reports errors from all components of a
pipeline. For example:
call [ cmd "cat" [ "/notfound" ]; cmd "ls" [ "/notfound.too" ] ]
This will raise an exception
Subprocess_error [ "/bin/cat", Unix.WEXITED 1; "/bin/ls", Unix.WEXITED 1 ]
There is another subtle difference to many Unix shells (and normally also the
"system" function in libc). This module reports errors occuring between "fork"
and "exec"; for instance if the file "fail" refers to a non-existing
interpreter
#! /not/found
but is executable, this special error can only be detected by the "exec" call.
Unix shells print an error message to stderr, and return an exit code of 127
(which is reserved for this case):
Sys.command "fail";;
sh: ./fail: No such file or directory
- : int = 127
However, the true reason isn't reported. In contrast to this, the Shell module
is able to pass the real error condition back to the calling program:
call [ command "fail" ];;
Uncaught exception: Unix.Unix_error(20, "execve", "./fail").
------------------------------------------------------------------------------
Module "Shell_sys": The fundamental layer
------------------------------------------------------------------------------
The module Shell is a simple application of the functions defined in Shell_sys,
the more fundamental module. Shell_sys allows a more fine-grained control of
the execution of external commands; however, it is more difficult to use.
Shell_sys allows it to run processes both synchronously and asynchronously, to
form pipelines with arbitrary topology, to create user-defined handlers serving
file descriptors, and to control signal handling.
------------------------------------------------------------------------------
Module "Unix_exts": The missing system calls
------------------------------------------------------------------------------
This module contains some system calls missing in the Unix library distributed
with O'Caml.
==============================================================================
Author, Copying
==============================================================================
Shell has been written by Gerd Stolpmann [2]. You may copy it as you like, you
may use it even for commercial purposes as long as the license conditions are
respected, see the file LICENSE coming with the distribution. It allows almost
everything.
==============================================================================
History
==============================================================================
- Changed in 0.2.1: Changes for O'Caml 3.04
- Changed in 0.2: If possible, the C library is created as shared library
(O'Caml 3.03-alpha).
--------------------------
[1] see http://www.ocaml-programming.de/packages/shell-0.2.1.tar.gz
[2] see mailto:gerd@gerd-stolpmann.de
|
