<!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_mt.html"> <link rel="next" href="Netsmtp.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="The shell library: Pipelines and redirections" rel="Section" href="#2_TheshelllibraryPipelinesandredirections"> <link title="Module Shell: The comfortable layer" rel="Subsection" href="#3_ModuleShellThecomfortablelayer"> <link title="Module Shell_sys: The fundamental layer" rel="Subsection" href="#3_ModuleShellsysThefundamentallayer"> <link title="Module Unix_exts: The missing system calls" rel="Subsection" href="#3_ModuleUnixextsThemissingsystemcalls"> <title>Ocamlnet 2 Reference Manual : Shell_intro</title> </head> <body> <div class="navbar"><a href="Shell_mt.html">Previous</a> <a href="index.html">Up</a> <a href="Netsmtp.html">Next</a> </div> <center><h1>Shell_intro</h1></center> <br> <br> <a name="2_TheshelllibraryPipelinesandredirections"></a> <h2>The <code class="code">shell</code> library: Pipelines and redirections</h2> <p> The <code class="code">shell</code> library provides some of the functionality of a Unix shell; in particular the library supports starting simple commands, executing pipelined commands, and arranging redirections. <p> <a name="3_ModuleShellThecomfortablelayer"></a> <h3>Module <code class="code">Shell</code>: The comfortable layer</h3> <p> 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 <p> <pre><code class="code"> call [ cmd "ls" [ "/dir1"; "/dir2" ]] </code></pre> <p> 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). <p> A pipeline can be constructed by <code class="code">call</code> as well. For example: <p> <pre><code class="code"> call [ cmd "find" [ "/dir" ]; cmd "grep" [ "something" ] ] </code></pre> <p> The output of "find" is redirected to the input of "grep". <p> 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: <p> <pre><code class="code">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" ] </code></pre> <p> Here, "sort" reads the contents of s and writes the result to b. <p> Unlike the Unix shell, this module reports errors from all components of a pipeline. For example: <p> <pre><code class="code">call [ cmd "cat" [ "/notfound" ]; cmd "ls" [ "/notfound.too" ] ] </code></pre> <p> This will raise an exception <p> <pre><code class="code">Subprocess_error [ "/bin/cat", Unix.WEXITED 1; "/bin/ls", Unix.WEXITED 1 ] </code></pre> <p> There is another subtle difference to many Unix shells (and normally also the <code class="code">system</code> function in libc). This module reports errors occuring between <code class="code">fork</code> and <code class="code">exec</code>; for instance if the file "fail" refers to a non-existing interpreter <p> <pre><code class="code">#! /not/found </code></pre> <p> 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): <p> <pre><code class="code">Sys.command "fail";; sh: ./fail: No such file or directory ~ : int = 127 </code></pre> <p> 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: <p> <pre><code class="code">call [ command "fail" ];; Uncaught exception: Unix.Unix_error(20, "execve", "./fail"). </code></pre> <p> <a name="3_ModuleShellsysThefundamentallayer"></a> <h3>Module <code class="code">Shell_sys</code>: The fundamental layer</h3> <p> The module <code class="code">Shell</code> is a simple application of the functions defined in <code class="code">Shell_sys</code>, the more fundamental module. <code class="code">Shell_sys</code> allows a more fine-grained control of the execution of external commands; however, it is more difficult to use. <p> <code class="code">Shell_sys</code> 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. <p> <a name="3_ModuleUnixextsThemissingsystemcalls"></a> <h3>Module <code class="code">Unix_exts</code>: The missing system calls</h3> <p> This module contains some system calls missing in the Unix library distributed with O'Caml. <br> </body></html>
