File: Shell.html

package info (click to toggle)
ocamlnet 2.2.9-8
links: PTS, VCS
area: main
in suites: squeeze
size: 17,724 kB
ctags: 10,053
sloc: ml: 63,928; ansic: 1,973; makefile: 800; sh: 651
file content (545 lines) | stat: -rw-r--r-- 31,906 bytes
parent folder | download | duplicates (2)
<!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>
&nbsp;<a href="index.html">Up</a>
&nbsp;<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>(&gt;&amp;) : <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 &gt;&amp; stderr</code> creates an assignment such that all output
 to stdout is redirected to stderr.
<p>

 <code class="code">f &gt;&amp; 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>(&lt;&amp;) : <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 &lt;&amp; 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 &lt;&amp; 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 = &lt;abstr&gt;
 # 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 &gt;&amp; 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>