<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<link rel="stylesheet" href="style.css" type="text/css">
<meta content="text/html; charset=iso-8859-1" http-equiv="Content-Type">
<link rel="Start" href="index.html">
<link rel="previous" href="Shell_sys.html">
<link rel="next" href="Shell_uq.html">
<link rel="Up" href="index.html">
<link title="Index of types" rel=Appendix href="index_types.html">
<link title="Index of exceptions" rel=Appendix href="index_exceptions.html">
<link title="Index of values" rel=Appendix href="index_values.html">
<link title="Index of class attributes" rel=Appendix href="index_attributes.html">
<link title="Index of class methods" rel=Appendix href="index_methods.html">
<link title="Index of classes" rel=Appendix href="index_classes.html">
<link title="Index of class types" rel=Appendix href="index_class_types.html">
<link title="Index of modules" rel=Appendix href="index_modules.html">
<link title="Index of module types" rel=Appendix href="index_module_types.html">
<link title="Uq_gtk" rel="Chapter" href="Uq_gtk.html">
<link title="Equeue" rel="Chapter" href="Equeue.html">
<link title="Unixqueue" rel="Chapter" href="Unixqueue.html">
<link title="Uq_engines" rel="Chapter" href="Uq_engines.html">
<link title="Uq_socks5" rel="Chapter" href="Uq_socks5.html">
<link title="Unixqueue_mt" rel="Chapter" href="Unixqueue_mt.html">
<link title="Equeue_intro" rel="Chapter" href="Equeue_intro.html">
<link title="Uq_ssl" rel="Chapter" href="Uq_ssl.html">
<link title="Uq_tcl" rel="Chapter" href="Uq_tcl.html">
<link title="Netcgi_common" rel="Chapter" href="Netcgi_common.html">
<link title="Netcgi" rel="Chapter" href="Netcgi.html">
<link title="Netcgi_ajp" rel="Chapter" href="Netcgi_ajp.html">
<link title="Netcgi_scgi" rel="Chapter" href="Netcgi_scgi.html">
<link title="Netcgi_cgi" rel="Chapter" href="Netcgi_cgi.html">
<link title="Netcgi_fcgi" rel="Chapter" href="Netcgi_fcgi.html">
<link title="Netcgi_dbi" rel="Chapter" href="Netcgi_dbi.html">
<link title="Netcgi1_compat" rel="Chapter" href="Netcgi1_compat.html">
<link title="Netcgi_test" rel="Chapter" href="Netcgi_test.html">
<link title="Netcgi_porting" rel="Chapter" href="Netcgi_porting.html">
<link title="Netcgi_plex" rel="Chapter" href="Netcgi_plex.html">
<link title="Http_client" rel="Chapter" href="Http_client.html">
<link title="Telnet_client" rel="Chapter" href="Telnet_client.html">
<link title="Ftp_data_endpoint" rel="Chapter" href="Ftp_data_endpoint.html">
<link title="Ftp_client" rel="Chapter" href="Ftp_client.html">
<link title="Nethttpd_types" rel="Chapter" href="Nethttpd_types.html">
<link title="Nethttpd_kernel" rel="Chapter" href="Nethttpd_kernel.html">
<link title="Nethttpd_reactor" rel="Chapter" href="Nethttpd_reactor.html">
<link title="Nethttpd_engine" rel="Chapter" href="Nethttpd_engine.html">
<link title="Nethttpd_services" rel="Chapter" href="Nethttpd_services.html">
<link title="Nethttpd_plex" rel="Chapter" href="Nethttpd_plex.html">
<link title="Nethttpd_intro" rel="Chapter" href="Nethttpd_intro.html">
<link title="Netplex_types" rel="Chapter" href="Netplex_types.html">
<link title="Netplex_mp" rel="Chapter" href="Netplex_mp.html">
<link title="Netplex_mt" rel="Chapter" href="Netplex_mt.html">
<link title="Netplex_log" rel="Chapter" href="Netplex_log.html">
<link title="Netplex_controller" rel="Chapter" href="Netplex_controller.html">
<link title="Netplex_container" rel="Chapter" href="Netplex_container.html">
<link title="Netplex_sockserv" rel="Chapter" href="Netplex_sockserv.html">
<link title="Netplex_workload" rel="Chapter" href="Netplex_workload.html">
<link title="Netplex_main" rel="Chapter" href="Netplex_main.html">
<link title="Netplex_config" rel="Chapter" href="Netplex_config.html">
<link title="Netplex_kit" rel="Chapter" href="Netplex_kit.html">
<link title="Rpc_netplex" rel="Chapter" href="Rpc_netplex.html">
<link title="Netplex_cenv" rel="Chapter" href="Netplex_cenv.html">
<link title="Netplex_intro" rel="Chapter" href="Netplex_intro.html">
<link title="Netshm" rel="Chapter" href="Netshm.html">
<link title="Netshm_data" rel="Chapter" href="Netshm_data.html">
<link title="Netshm_hashtbl" rel="Chapter" href="Netshm_hashtbl.html">
<link title="Netshm_array" rel="Chapter" href="Netshm_array.html">
<link title="Netshm_intro" rel="Chapter" href="Netshm_intro.html">
<link title="Netconversion" rel="Chapter" href="Netconversion.html">
<link title="Netchannels" rel="Chapter" href="Netchannels.html">
<link title="Netstream" rel="Chapter" href="Netstream.html">
<link title="Mimestring" rel="Chapter" href="Mimestring.html">
<link title="Netmime" rel="Chapter" href="Netmime.html">
<link title="Netsendmail" rel="Chapter" href="Netsendmail.html">
<link title="Neturl" rel="Chapter" href="Neturl.html">
<link title="Netaddress" rel="Chapter" href="Netaddress.html">
<link title="Netbuffer" rel="Chapter" href="Netbuffer.html">
<link title="Netdate" rel="Chapter" href="Netdate.html">
<link title="Netencoding" rel="Chapter" href="Netencoding.html">
<link title="Netulex" rel="Chapter" href="Netulex.html">
<link title="Netaccel" rel="Chapter" href="Netaccel.html">
<link title="Netaccel_link" rel="Chapter" href="Netaccel_link.html">
<link title="Nethtml" rel="Chapter" href="Nethtml.html">
<link title="Netstring_str" rel="Chapter" href="Netstring_str.html">
<link title="Netstring_pcre" rel="Chapter" href="Netstring_pcre.html">
<link title="Netstring_mt" rel="Chapter" href="Netstring_mt.html">
<link title="Netmappings" rel="Chapter" href="Netmappings.html">
<link title="Netaux" rel="Chapter" href="Netaux.html">
<link title="Nethttp" rel="Chapter" href="Nethttp.html">
<link title="Netchannels_tut" rel="Chapter" href="Netchannels_tut.html">
<link title="Netmime_tut" rel="Chapter" href="Netmime_tut.html">
<link title="Netsendmail_tut" rel="Chapter" href="Netsendmail_tut.html">
<link title="Netulex_tut" rel="Chapter" href="Netulex_tut.html">
<link title="Neturl_tut" rel="Chapter" href="Neturl_tut.html">
<link title="Netsys" rel="Chapter" href="Netsys.html">
<link title="Netpop" rel="Chapter" href="Netpop.html">
<link title="Rpc_auth_dh" rel="Chapter" href="Rpc_auth_dh.html">
<link title="Rpc_key_service" rel="Chapter" href="Rpc_key_service.html">
<link title="Rpc_time" rel="Chapter" href="Rpc_time.html">
<link title="Rpc_auth_local" rel="Chapter" href="Rpc_auth_local.html">
<link title="Rtypes" rel="Chapter" href="Rtypes.html">
<link title="Xdr" rel="Chapter" href="Xdr.html">
<link title="Rpc" rel="Chapter" href="Rpc.html">
<link title="Rpc_program" rel="Chapter" href="Rpc_program.html">
<link title="Rpc_portmapper_aux" rel="Chapter" href="Rpc_portmapper_aux.html">
<link title="Rpc_packer" rel="Chapter" href="Rpc_packer.html">
<link title="Rpc_transport" rel="Chapter" href="Rpc_transport.html">
<link title="Rpc_client" rel="Chapter" href="Rpc_client.html">
<link title="Rpc_simple_client" rel="Chapter" href="Rpc_simple_client.html">
<link title="Rpc_portmapper_clnt" rel="Chapter" href="Rpc_portmapper_clnt.html">
<link title="Rpc_portmapper" rel="Chapter" href="Rpc_portmapper.html">
<link title="Rpc_server" rel="Chapter" href="Rpc_server.html">
<link title="Rpc_auth_sys" rel="Chapter" href="Rpc_auth_sys.html">
<link title="Rpc_intro" rel="Chapter" href="Rpc_intro.html">
<link title="Rpc_mapping_ref" rel="Chapter" href="Rpc_mapping_ref.html">
<link title="Rpc_ssl" rel="Chapter" href="Rpc_ssl.html">
<link title="Rpc_xti_client" rel="Chapter" href="Rpc_xti_client.html">
<link title="Shell_sys" rel="Chapter" href="Shell_sys.html">
<link title="Shell" rel="Chapter" href="Shell.html">
<link title="Shell_uq" rel="Chapter" href="Shell_uq.html">
<link title="Shell_mt" rel="Chapter" href="Shell_mt.html">
<link title="Shell_intro" rel="Chapter" href="Shell_intro.html">
<link title="Netsmtp" rel="Chapter" href="Netsmtp.html"><link title="Calling commands and pipelines" rel="Section" href="#1_Callingcommandsandpipelines">
<link title="Examples" rel="Section" href="#1_Examples">
<link title="Invoking simple commands" rel="Subsection" href="#2_Invokingsimplecommands">
<link title="Redirecting stdout to a buffer" rel="Subsection" href="#2_Redirectingstdouttoabuffer">
<link title="Subprocess errors are caught and propagated to the caller" rel="Subsection" href="#2_Subprocesserrorsarecaughtandpropagatedtothecaller">
<link title="Redirecting stderr, too" rel="Subsection" href="#2_Redirectingstderrtoo">
<link title="Pipelines" rel="Subsection" href="#2_Pipelines">
<link title="Combining pipelines and redirections" rel="Subsection" href="#2_Combiningpipelinesandredirections">
<link title="Redirection from a string" rel="Subsection" href="#2_Redirectionfromastring">
<link title="Combined redirections" rel="Subsection" href="#2_Combinedredirections">
<link title="Redirections combined with assignments" rel="Subsection" href="#2_Redirectionscombinedwithassignments">
<link title="Final notes" rel="Subsection" href="#2_Finalnotes">
<title>Ocamlnet 2 Reference Manual : Shell</title>
</head>
<body>
<div class="navbar"><a href="Shell_sys.html">Previous</a>
<a href="index.html">Up</a>
<a href="Shell_uq.html">Next</a>
</div>
<center><h1>Module <a href="type_Shell.html">Shell</a></h1></center>
<br>
<pre><span class="keyword">module</span> Shell: <code class="code">sig</code> <a href="Shell.html">..</a> <code class="code">end</code></pre>Calls external programs, creates pipelines, etc. (simplified interface)<br>
<hr width="100%">
<br>
This module is <b>not thread-safe</b>. See the module <code class="code">Shell_sys</code> for
more information.<br>
<br>
<b>Signal handlers:</b> When you call the function <code class="code">call</code>, signal handlers
are automatically installed by <a href="Shell_sys.html#VALinstall_job_handlers"><code class="code">Shell_sys.install_job_handlers</code></a>, unless
this installation has already been performed. You can configure these
handlers by <a href="Shell_sys.html#VALconfigure_job_handlers"><code class="code">Shell_sys.configure_job_handlers</code></a>. The handlers remain
in effect even after <code class="code">call</code> returns.
<p>
Note that this has a global side effect on the whole process, because
there is only one set of signal handlers.<br>
<br>
<a name="1_Callingcommandsandpipelines"></a>
<h1>Calling commands and pipelines</h1><br>
<br>
The following functions are simplified versions of the
<code class="code">Shell_sys.job</code> abstraction.<br>
<pre><span class="keyword">exception</span> <a name="EXCEPTIONSubprocess_error"></a>Subprocess_error <span class="keyword">of</span> <code class="type">(string * Unix.process_status) list</code></pre>
<div class="info">
The string contains the called commands in a readable representation.
The list enumerates the return codes of the processes that have
been started for the commands.<br>
</div>
<pre><span class="keyword">type</span> <a name="TYPEproducer"></a><code class="type"></code>producer </pre>
<div class="info">
A producer generates data sent to a called process<br>
</div>
<pre><span class="keyword">type</span> <a name="TYPEconsumer"></a><code class="type"></code>consumer </pre>
<div class="info">
A consumer receives data from a called process<br>
</div>
<pre><span class="keyword">type</span> <a name="TYPEassignment"></a><code class="type"></code>assignment </pre>
<div class="info">
An assignment redirects file descriptors while calling a process<br>
</div>
<pre><span class="keyword">val</span> <a name="VALcommand"></a>command : <code class="type">?cmdname:string -><br> ?arguments:string array -><br> ?chdir:string -><br> ?environment:<a href="Shell_sys.html#TYPEenvironment">Shell_sys.environment</a> -><br> ?descriptors:Unix.file_descr list -><br> ?assignments:<a href="Shell.html#TYPEassignment">assignment</a> list -> string -> <a href="Shell_sys.html#TYPEcommand">Shell_sys.command</a></code></pre><div class="info">
Creates a command descriptor, to be used in <code class="code">call</code>. The anonymous
string argument is the name of the executable to invoke. If the name
contains a '/', it is simply interpreted as the filename of the
executable. Otherwise the command is searched in the current PATH.
<p>
<br>
</div>
<div class="param_info"><code class="code">cmdname</code> : The name of the command passed in <code class="code">argv[0]</code>. By
default, this argument is derived from the name of the executable.</div>
<div class="param_info"><code class="code">arguments</code> : The arguments of the command (starting with the
first real argument, skipping <code class="code">cmdname</code>). By default <code class="code"> [] </code>.</div>
<div class="param_info"><code class="code">chdir</code> : Before the command is executed it is changed to
this directory.</div>
<div class="param_info"><code class="code">environment</code> : The environment of the command. By default, the
current environment</div>
<div class="param_info"><code class="code">descriptors</code> : The list of file descriptors to share with the
current process; all other file descriptors will be closed.
By default, <code class="code"> [stdin; stdout; stderr] </code>.</div>
<div class="param_info"><code class="code">assignments</code> : The list of descriptor assignments. The assignments
are applied one after the other. By default empty.</div>
<pre><span class="keyword">val</span> <a name="VALcmd"></a>cmd : <code class="type">?cmdname:string -><br> ?chdir:string -><br> ?environment:<a href="Shell_sys.html#TYPEenvironment">Shell_sys.environment</a> -><br> ?descriptors:Unix.file_descr list -><br> ?assignments:<a href="Shell.html#TYPEassignment">assignment</a> list -><br> string -> string list -> <a href="Shell_sys.html#TYPEcommand">Shell_sys.command</a></code></pre><div class="info">
The same as <code class="code">command</code> but with a slightly different interface: Use
<pre><code class="code"> cmd "ls" [ "/dir/file" ] </code></pre>
instead of
<pre><code class="code"> command ~arguments:[|"/dir/file"|] "ls" </code></pre>
<p>
The named arguments have the same meanings as in <code class="code">command</code>.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALcall"></a>call : <code class="type">?ignore_error_code:bool -><br> ?mode:<a href="Shell_sys.html#TYPEgroup_mode">Shell_sys.group_mode</a> -><br> ?stdin:<a href="Shell.html#TYPEproducer">producer</a> -><br> ?stdout:<a href="Shell.html#TYPEconsumer">consumer</a> -><br> ?stderr:<a href="Shell.html#TYPEconsumer">consumer</a> -> <a href="Shell_sys.html#TYPEcommand">Shell_sys.command</a> list -> unit</code></pre><div class="info">
Starts the pipeline represented by the list of commands; i.e.
if <code class="code"> [c1;c2;...;cN] </code> is passed, this corresponds to the pipeline
<code class="code"> c1 | c2 | ... | cN </code> (in shell notation).
<p>
The function returns normally if all processes can be started and
terminate regularly with exit code 0. If a process terminates with
some other exit code, and <code class="code">ignore_error_code</code> is set, the function
returns normally, too. The latter does not apply if a process terminates
because of a signal (which triggers always the exception
<code class="code">Subprocess_error</code>).
<p>
If a process terminates with an exit code other than 0 and
<code class="code">ignore_error_code</code> is not set (the default), or if a process is
terminated because of a signal, the exception <code class="code">Subprocess_error</code>
will be raised. For every command the process result is included
in the exception argument.
<p>
If a process cannot be started (e.g. because of insufficient
resources), the function will try to shut down the already running
part of the pipeline by sending SIGTERM to these processes.
It is not checked whether the processes actually terminate (no
"wait" for them); an appropriate exception will be raised.
In the case that it is not even possible to perform these cleanup
actions, the exception <code class="code">Shell_sys.Fatal_error</code> will be raised.
<p>
When the function raises an exception other than <code class="code">Subprocess_error</code>,
a serious error condition has happened, and it is recommended
to exit the program as soon as possible.
<p>
<br>
</div>
<div class="param_info"><code class="code">ignore_error_code</code> : If <code class="code">true</code>, exit codes other than 0 of the
subprocesses are ignored. This does not apply to signals, however.
By default <code class="code">false</code>.</div>
<div class="param_info"><code class="code">mode</code> : See <a href="Shell_sys.html#VALrun_job"><code class="code">Shell_sys.run_job</code></a> for a detailed description
of this parameter. By default <code class="code">Same_as_caller</code>.</div>
<div class="param_info"><code class="code">stdin</code> : If present, the first process of the pipeline reads
input data from this procucer. By default, there is no such
producer.</div>
<div class="param_info"><code class="code">stdout</code> : If present, the last process of the pipeline writes
output data to this consumer. By default, there is no such
consumer.</div>
<div class="param_info"><code class="code">stderr</code> : If present, all processes of the pipeline write
their error messages to this consumer. By default, there is no
such consumer.</div>
<pre><span class="keyword">val</span> <a name="VALsetup_job"></a>setup_job : <code class="type">?stdin:<a href="Shell.html#TYPEproducer">producer</a> -><br> ?stdout:<a href="Shell.html#TYPEconsumer">consumer</a> -><br> ?stderr:<a href="Shell.html#TYPEconsumer">consumer</a> -><br> <a href="Shell_sys.html#TYPEcommand">Shell_sys.command</a> list -> <a href="Shell_sys.html#TYPEjob">Shell_sys.job</a> * Unix.file_descr list</code></pre><div class="info">
Creates a job like <code class="code">call</code>, but does not execute it. In addition to
the job, the file descriptors are returned that must be closed
when the job is done.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALpostprocess_job"></a>postprocess_job : <code class="type">?ignore_error_code:bool -> <a href="Shell_sys.html#TYPEjob_instance">Shell_sys.job_instance</a> -> unit</code></pre><div class="info">
Looks at the error codes of the job, and raises
<code class="code">Subprocess_error</code> when there is an error that cannot be ignored.
As error conditions are considered non-zero exit codes of any
called processes, or signals terminating any of the called processes.
<p>
<br>
</div>
<div class="param_info"><code class="code">ignore_error_code</code> : If <code class="code">true</code>, exit codes other than 0 of the
subprocesses are ignored. This does not apply to signals, however.
By default <code class="code">false</code>.</div>
<pre><span class="keyword">val</span> <a name="VALassign"></a>assign : <code class="type">src:Unix.file_descr -> target:Unix.file_descr -> <a href="Shell.html#TYPEassignment">assignment</a></code></pre><div class="info">
Arranges a redirection such that writing to <code class="code">src</code> or reading from <code class="code">src</code>
will actually write to <code class="code">target</code> or read from <code class="code">target</code>
(i.e., the <code class="code">target</code> descriptor is duplicated and replaces
the <code class="code">src</code> descriptor just before the process is launched.)
<p>
Note that assignments work only if the descriptors are shared
with the called process, so they must also be contained in the
<code class="code">descriptors</code> list of <code class="code">command</code> or <code class="code">cmd</code>. Furthermore, the
close-on-exec flag must not be set.<br>
</div>
<pre><span class="keyword">val</span> <a name="VAL(>&)"></a>(>&) : <code class="type">Unix.file_descr -> Unix.file_descr -> <a href="Shell.html#TYPEassignment">assignment</a></code></pre><div class="info">
Same as <code class="code">assign</code>, but infix notation. For example,
<code class="code">stdout >& stderr</code> creates an assignment such that all output
to stdout is redirected to stderr.
<p>
<code class="code">f >& g</code> is the same as <code class="code">assign ~src:f target:g</code>. It should
be used for output assignments (as in the Bourne shell).<br>
</div>
<pre><span class="keyword">val</span> <a name="VAL(<&)"></a>(<&) : <code class="type">Unix.file_descr -> Unix.file_descr -> <a href="Shell.html#TYPEassignment">assignment</a></code></pre><div class="info">
Same as <code class="code">assign</code>, but infix notation. For example,
<code class="code">stdin <& f</code> creates an assignment such that the called process
reads from the open file descriptor <code class="code">f</code>.
<p>
<code class="code">f <& g</code> is the same as <code class="code">assign ~src:f target:g</code>. It should
be used for input assignments (as in the Bourne shell).<br>
</div>
<pre><span class="keyword">val</span> <a name="VALassigned_pair"></a>assigned_pair : <code class="type"><a href="Shell.html#TYPEassignment">assignment</a> -> Unix.file_descr * Unix.file_descr</code></pre><div class="info">
Returns the target and the source of the assignment as
pair of descriptors <code class="code">(target,src)</code>.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALstdin"></a>stdin : <code class="type">Unix.file_descr</code></pre><pre><span class="keyword">val</span> <a name="VALstdout"></a>stdout : <code class="type">Unix.file_descr</code></pre><pre><span class="keyword">val</span> <a name="VALstderr"></a>stderr : <code class="type">Unix.file_descr</code></pre><div class="info">
The standard descriptors; defined here for convenience.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALfrom_string"></a>from_string : <code class="type">?pos:int -> ?len:int -> ?epipe:(unit -> unit) -> string -> <a href="Shell.html#TYPEproducer">producer</a></code></pre><div class="info">
Creates a producer taking the data from a string <code class="code">s</code>. After these data
are sent, the pipeline is closed.
<p>
<br>
</div>
<div class="param_info"><code class="code">pos</code> : The position in <code class="code">s</code> where the data slice to transfer begins.
By default <code class="code">0</code>.</div>
<div class="param_info"><code class="code">len</code> : The length of the data slice to transfer. By default,
all bytes from the start position <code class="code">pos</code> to the end of the
string are taken.</div>
<div class="param_info"><code class="code">epipe</code> : This function is called when the pipeline breaks
(EPIPE). Default: the empty function. EPIPE exceptions are
always caught, and implicitly handled by closing the pipeline.</div>
<pre><span class="keyword">val</span> <a name="VALfrom_stream"></a>from_stream : <code class="type">?epipe:(unit -> unit) -> string Stream.t -> <a href="Shell.html#TYPEproducer">producer</a></code></pre><div class="info">
Creates a producer taking the data from a stream of strings.
After the data are sent, the pipeline is closed.
<p>
<br>
</div>
<div class="param_info"><code class="code">epipe</code> : This function is called when the pipeline breaks
(EPIPE). Default: the empty function. EPIPE exceptions are
always caught, and implicitly handled by closing the pipeline.</div>
<pre><span class="keyword">val</span> <a name="VALfrom_function"></a>from_function : <code class="type">producer:(Unix.file_descr -> bool) -> unit -> <a href="Shell.html#TYPEproducer">producer</a></code></pre><div class="info">
Creates a producer taking the data from a function. See
<a href="Shell_sys.html#VALadd_producer"><code class="code">Shell_sys.add_producer</code></a> for the meaning of the <code class="code">producer</code>
function.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALfrom_file"></a>from_file : <code class="type">string -> <a href="Shell.html#TYPEproducer">producer</a></code></pre><div class="info">
Creates a producer taking the data from the file whose name is
passed to this function.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALfrom_fd"></a>from_fd : <code class="type">Unix.file_descr -> <a href="Shell.html#TYPEproducer">producer</a></code></pre><div class="info">
Creates a producer taking the data from the file descriptor passed
to this function.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALfrom_dev_null"></a>from_dev_null : <code class="type"><a href="Shell.html#TYPEproducer">producer</a></code></pre><div class="info">
A producer taking the data from <code class="code">/dev/null</code>.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALto_buffer"></a>to_buffer : <code class="type">Buffer.t -> <a href="Shell.html#TYPEconsumer">consumer</a></code></pre><div class="info">
Creates a consumer writing the data into the passed buffer.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALto_function"></a>to_function : <code class="type">consumer:(Unix.file_descr -> bool) -> unit -> <a href="Shell.html#TYPEconsumer">consumer</a></code></pre><div class="info">
Creates a consumer writing the data by calling a function. See
<a href="Shell_sys.html#VALadd_consumer"><code class="code">Shell_sys.add_consumer</code></a> for the meaning of the <code class="code">consumer</code>
function.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALto_file"></a>to_file : <code class="type">?append:bool -> string -> <a href="Shell.html#TYPEconsumer">consumer</a></code></pre><div class="info">
Creates a consumer writing the data into the file whose name is
passed to this function. Unless <code class="code">append</code> is given, the file is
truncated and overwritten. If <code class="code">append</code> is <code class="code">true</code>, the data are
appended to the file. By default, <code class="code">append</code> is <code class="code">false</code>.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALto_fd"></a>to_fd : <code class="type">Unix.file_descr -> <a href="Shell.html#TYPEconsumer">consumer</a></code></pre><div class="info">
Creates a consumer redirecting the data to the file descriptor<br>
</div>
<pre><span class="keyword">val</span> <a name="VALto_dev_null"></a>to_dev_null : <code class="type"><a href="Shell.html#TYPEconsumer">consumer</a></code></pre><div class="info">
A consumer redirecting the data to <code class="code">/dev/null</code>.<br>
</div>
<br>
<a name="1_Examples"></a>
<h1>Examples</h1>
<p>
The following examples show toploop sessions using <code class="code">Shell</code>.<br>
<br>
<a name="2_Invokingsimplecommands"></a>
<h2>Invoking simple commands</h2>
<p>
Call the command "ls" without redirection:
<pre><code class="code"> # call [ command "ls" ];;
IDEAS s1.ml~ shell.mli~ shell_sys.ml~ unix_exts.ml
META shell.a shell.ml~ shell_sys.o unix_exts.mli
Makefile shell.cma shell_sys.cmi t unix_exts.mli~
Makefile~ shell.cmi shell_sys.cmo testjob unix_exts.ml~
depend shell.cmo shell_sys.cmx testjob~ unix_exts.o
libshell.a shell.cmxa shell_sys.ml unix_exts.cmi unix_exts_c.c
log shell.ml shell_sys.mli unix_exts.cmo unix_exts_c.c~
s1.ml shell.mli shell_sys.mli~ unix_exts.cmx unix_exts_c.o
\- : unit = ()
</code></pre>
<p>
<a name="2_Redirectingstdouttoabuffer"></a>
<h2>Redirecting stdout to a buffer</h2>
<p>
The output of "ls" is collected in the buffer <code class="code">b</code>:
<pre><code class="code"> # let b = Buffer.create 10;;
val b : Buffer.t = <abstr>
# call ~stdout:(to_buffer b) [ command "ls" ];;
\- : unit = ()
# Buffer.contents b;;
\- : string =
"IDEAS\nMETA\nMakefile\nMakefile~\ndepend\n..."
</code></pre>
<p>
<a name="2_Subprocesserrorsarecaughtandpropagatedtothecaller"></a>
<h2>Subprocess errors are caught and propagated to the caller</h2>
<p>
Because "/a" does not exist, "ls" will fail. The command writes the
message to stderr (not redirected here), and returns with an exit
code of 1, triggering an exception:
<pre><code class="code"> # call [ command ~arguments:[| "/a" |] "ls" ];;
/bin/ls: /a: No such file or directory
Uncaught exception: Shell.Subprocess_error ["/bin/ls", Unix.WEXITED 1].
</code></pre>
<p>
<a name="2_Redirectingstderrtoo"></a>
<h2>Redirecting stderr, too</h2>
<p>
Here, the message written to stderr is collected in <code class="code">b</code>:
<pre><code class="code"> # Buffer.clear b;;
\- : unit = ()
# call ~stderr:(to_buffer b) [ command ~arguments:[| "/a" |] "ls" ];;
Uncaught exception: Shell.Subprocess_error ["/bin/ls", Unix.WEXITED 1].
# Buffer.contents b;;
\- : string = "/bin/ls: /a: No such file or directory\n"
</code></pre>
<p>
<a name="2_Pipelines"></a>
<h2>Pipelines</h2>
<p>
Here, the output of "cat" becomes the input of "sort":
<pre><code class="code"> # call [ command ~arguments:[|"META"|] "cat"; command "sort" ];;
archive(byte) = "shell.cma"
archive(native) = "shell.cmxa"
description = "Unix shell functions"
linkopts = "-cclib -lshell"
requires = "unix str"
version = "0.0"
\- : unit = ()
</code></pre>
<p>
<a name="2_Combiningpipelinesandredirections"></a>
<h2>Combining pipelines and redirections</h2>
<p>
The same, but the output of "sort" is collected in the buffer <code class="code">b</code>:
<pre><code class="code"> # Buffer.clear b;;
\- : unit = ()
# call ~stdout:(to_buffer b) [ command ~arguments:[|"META"|] "cat"; command "sort" ];;
\- : unit = ()
# Buffer.contents b;;
\- : string =
"archive(byte) = \"shell.cma\"\narchive(native) = \"shell.cmxa\"\ndescription = \"Unix shell functions\"\nlinkopts = \"-cclib -lshell\"\nrequires = \"unix str\"\nversion = \"0.0\"\n"
</code></pre>
<p>
<a name="2_Redirectionfromastring"></a>
<h2>Redirection from a string</h2>
<p>
The contents of the string <code class="code">s</code> are written to the input of "sort":
<pre><code class="code"> # let s = "f\na\nd\nc\n";;
val s : string = "f\na\nd\nc\n"
# call ~stdin:(from_string s) [ command "sort" ];;
a
c
d
f
\- : unit = ()
</code></pre>
<p>
<a name="2_Combinedredirections"></a>
<h2>Combined redirections</h2>
<p>
It is possible to have several redirections. Here, the string <code class="code">s</code> is
sorted by "sort", and the output is collected in the buffer <code class="code">b</code>:
<pre><code class="code"> # Buffer.clear b;;
\- : unit = ()
# call ~stdout:(to_buffer b) ~stdin:(from_string s) [ command "sort" ];;
\- : unit = ()
# Buffer.contents b;;
\- : string = "a\nc\nd\nf\n"
</code></pre>
<p>
<a name="2_Redirectionscombinedwithassignments"></a>
<h2>Redirections combined with assignments</h2>
<p>
Here, the output and errors of "ls" are both collected in the buffer
<code class="code">b</code>:
<pre><code class="code"> # Buffer.clear b;;
\- : unit = ()
# call ~stdout:(to_buffer b)
[ command
~assignments:[ stderr >& stdout ]
~arguments:[| "/a" |]
"ls" ];;
Uncaught exception: Shell.Subprocess_error ["/bin/ls", Unix.WEXITED 1].
# Buffer.contents b;;
\- : string = "/bin/ls: /a: No such file or directory\n"
</code></pre>
<p>
<a name="2_Finalnotes"></a>
<h2>Final notes</h2>
<p>
Of course, all features can be combined arbitrarily.
<p>
Note that error reporting is better than in a traditional shell, because
the exit codes of all started commands are returned. (Shells usually only
return the exit code of the last command of a pipeline.)
<p>
For non-standard pipelines, you can also use the functions in
Shell_sys. "call" is a simple concatenation of Shell_sys invocations.<br>
</body></html>
