mirror of
https://github.com/c-cube/ocaml-containers.git
synced 2025-12-06 11:15:31 -05:00
2 lines
No EOL
16 KiB
HTML
2 lines
No EOL
16 KiB
HTML
<!DOCTYPE html>
|
||
<html xmlns="http://www.w3.org/1999/xhtml"><head><title>CCUnix (containers.CCUnix)</title><link rel="stylesheet" href="../../odoc.css"/><meta charset="utf-8"/><meta name="viewport" content="width=device-width,initial-scale=1.0"/><script src="../../highlight.pack.js"></script><script>hljs.initHighlightingOnLoad();</script></head><body><div class="content"><header><nav><a href="../index.html">Up</a> – <a href="../index.html">containers</a> » CCUnix</nav><h1>Module <code>CCUnix</code></h1><h2 id="high-level-functions-on-top-of-unix"><a href="#high-level-functions-on-top-of-unix" class="anchor"></a>High-level Functions on top of Unix</h2><p>Some useful functions built on top of Unix.</p><p><b>status: unstable</b></p><dl><dt>since</dt><dd>0.10</dd></dl><nav class="toc"><ul><li><a href="#calling-commands">Calling Commands</a></li><li><a href="#accessors">Accessors</a></li><li><a href="#simple-io">Simple IO</a></li><li><a href="#subprocesses">Subprocesses</a></li><li><a href="#networking">Networking</a></li><li><a href="#file-lock">File lock</a></li><li><a href="#infix-functions">Infix Functions</a></li><li><a href="#temporary-directory">Temporary directory</a></li></ul></nav></header><dl><dt class="spec type" id="type-or_error"><a href="#type-or_error" class="anchor"></a><code><span class="keyword">type</span> 'a or_error</code><code> = (<span class="type-var">'a</span>, string) Stdlib.result</code></dt><dt class="spec type" id="type-gen"><a href="#type-gen" class="anchor"></a><code><span class="keyword">type</span> 'a gen</code><code> = unit <span>-></span> <span class="type-var">'a</span> option</code></dt></dl><section><header><h3 id="calling-commands"><a href="#calling-commands" class="anchor"></a>Calling Commands</h3></header><dl><dt class="spec value" id="val-escape_str"><a href="#val-escape_str" class="anchor"></a><code><span class="keyword">val</span> escape_str : string <span>-></span> string</code></dt><dd><p>Escape a string so it can be a shell argument.</p></dd></dl><dl><dt class="spec type" id="type-call_result"><a href="#type-call_result" class="anchor"></a><code><span class="keyword">type</span> call_result</code><code> = < stdout : string; stderr : string; status : Unix.process_status; errcode : int; ></code></dt></dl><dl><dt class="spec value" id="val-call_full"><a href="#val-call_full" class="anchor"></a><code><span class="keyword">val</span> call_full : ?⁠bufsize:int <span>-></span> ?⁠stdin:[ `Gen of string <a href="index.html#type-gen">gen</a> | `Str of string ] <span>-></span> ?⁠env:string array <span>-></span> (<span class="type-var">'a</span>, Stdlib.Buffer.t, unit, <a href="index.html#type-call_result">call_result</a>) Stdlib.format4 <span>-></span> <span class="type-var">'a</span></code></dt><dd><p><code>call_full cmd</code> wraps the result of <code>Unix.open_process_full cmd</code> into an object. It reads the full stdout and stderr of the subprocess before returning.</p><dl><dt>parameter stdin</dt><dd><p>if provided, the generator or string is consumed and fed to the subprocess input channel, which is then closed.</p></dd></dl><dl><dt>parameter bufsize</dt><dd><p>buffer size used to read stdout and stderr.</p></dd></dl><dl><dt>parameter env</dt><dd><p>environment to run the command in.</p></dd></dl></dd></dl><dl><dt class="spec value" id="val-call"><a href="#val-call" class="anchor"></a><code><span class="keyword">val</span> call : ?⁠bufsize:int <span>-></span> ?⁠stdin:[ `Gen of string <a href="index.html#type-gen">gen</a> | `Str of string ] <span>-></span> ?⁠env:string array <span>-></span> (<span class="type-var">'a</span>, Stdlib.Buffer.t, unit, string * string * int) Stdlib.format4 <span>-></span> <span class="type-var">'a</span></code></dt><dd><p><code>call cmd</code> is similar to <code>call_full cmd</code> but returns a tuple <code>stdout, stderr, errcode</code> instead of an object.</p></dd></dl><dl><dt class="spec value" id="val-call_stdout"><a href="#val-call_stdout" class="anchor"></a><code><span class="keyword">val</span> call_stdout : ?⁠bufsize:int <span>-></span> ?⁠stdin:[ `Gen of string <a href="index.html#type-gen">gen</a> | `Str of string ] <span>-></span> ?⁠env:string array <span>-></span> (<span class="type-var">'a</span>, Stdlib.Buffer.t, unit, string) Stdlib.format4 <span>-></span> <span class="type-var">'a</span></code></dt></dl><dl><dt class="spec type" id="type-line"><a href="#type-line" class="anchor"></a><code><span class="keyword">type</span> line</code><code> = string</code></dt><dt class="spec type" id="type-async_call_result"><a href="#type-async_call_result" class="anchor"></a><code><span class="keyword">type</span> async_call_result</code><code> = < stdout : <a href="index.html#type-line">line</a> <a href="index.html#type-gen">gen</a>; stderr : <a href="index.html#type-line">line</a> <a href="index.html#type-gen">gen</a>; stdin : <a href="index.html#type-line">line</a> <span>-></span> unit; close_in : unit; close_err : unit; close_out : unit; close_all : unit; wait : Unix.process_status; wait_errcode : int; ></code></dt><dd><p>A subprocess for interactive usage (read/write channels line by line)</p><dl><dt>since</dt><dd>0.11</dd></dl></dd></dl><dl><dt class="spec value" id="val-async_call"><a href="#val-async_call" class="anchor"></a><code><span class="keyword">val</span> async_call : ?⁠env:string array <span>-></span> (<span class="type-var">'a</span>, Stdlib.Buffer.t, unit, <a href="index.html#type-async_call_result">async_call_result</a>) Stdlib.format4 <span>-></span> <span class="type-var">'a</span></code></dt><dd><p>Spawns a subprocess, like <a href="index.html#val-call"><code>call</code></a>, but the subprocess's channels are line generators and line sinks (for stdin). If <code>p</code> is <code>async_call "cmd"</code>, then <code>p#wait</code> waits for the subprocess to die. Channels can be closed independently.</p><dl><dt>since</dt><dd>0.11</dd></dl></dd></dl></section><section><header><h3 id="accessors"><a href="#accessors" class="anchor"></a>Accessors</h3><dl><dt>since</dt><dd>0.11</dd></dl></header><dl><dt class="spec value" id="val-stdout"><a href="#val-stdout" class="anchor"></a><code><span class="keyword">val</span> stdout : < stdout : <span class="type-var">'a</span>; .. > <span>-></span> <span class="type-var">'a</span></code></dt><dt class="spec value" id="val-stderr"><a href="#val-stderr" class="anchor"></a><code><span class="keyword">val</span> stderr : < stderr : <span class="type-var">'a</span>; .. > <span>-></span> <span class="type-var">'a</span></code></dt><dt class="spec value" id="val-status"><a href="#val-status" class="anchor"></a><code><span class="keyword">val</span> status : < status : <span class="type-var">'a</span>; .. > <span>-></span> <span class="type-var">'a</span></code></dt><dt class="spec value" id="val-errcode"><a href="#val-errcode" class="anchor"></a><code><span class="keyword">val</span> errcode : < errcode : <span class="type-var">'a</span>; .. > <span>-></span> <span class="type-var">'a</span></code></dt></dl></section><section><header><h3 id="simple-io"><a href="#simple-io" class="anchor"></a>Simple IO</h3></header><dl><dt class="spec value" id="val-with_in"><a href="#val-with_in" class="anchor"></a><code><span class="keyword">val</span> with_in : ?⁠mode:int <span>-></span> ?⁠flags:Unix.open_flag list <span>-></span> string <span>-></span> f:(Stdlib.in_channel <span>-></span> <span class="type-var">'a</span>) <span>-></span> <span class="type-var">'a</span></code></dt><dd><p>Open an input file with the given optional flag list, calls the function on the input channel. When the function raises or returns, the channel is closed.</p><dl><dt>parameter flags</dt><dd><p>opening flags. <code>Unix.O_RDONLY</code> is used in any cases.</p></dd></dl><dl><dt>since</dt><dd>0.16</dd></dl></dd></dl><dl><dt class="spec value" id="val-with_out"><a href="#val-with_out" class="anchor"></a><code><span class="keyword">val</span> with_out : ?⁠mode:int <span>-></span> ?⁠flags:Unix.open_flag list <span>-></span> string <span>-></span> f:(Stdlib.out_channel <span>-></span> <span class="type-var">'a</span>) <span>-></span> <span class="type-var">'a</span></code></dt><dd><p>Same as <a href="index.html#val-with_in"><code>with_in</code></a> but for an output channel.</p><dl><dt>parameter flags</dt><dd><p>opening flags (default <code>[Unix.O_CREAT; Unix.O_TRUNC]</code>) <code>Unix.O_WRONLY</code> is used in any cases.</p></dd></dl><dl><dt>since</dt><dd>0.16</dd></dl></dd></dl></section><section><header><h3 id="subprocesses"><a href="#subprocesses" class="anchor"></a>Subprocesses</h3></header><dl><dt class="spec value" id="val-with_process_in"><a href="#val-with_process_in" class="anchor"></a><code><span class="keyword">val</span> with_process_in : string <span>-></span> f:(Stdlib.in_channel <span>-></span> <span class="type-var">'a</span>) <span>-></span> <span class="type-var">'a</span></code></dt><dd><p>Open a shell command in a subprocess and obtain a handle to its stdout.</p><pre><code class="ml">CCUnix.with_process_in "ls /tmp" ~f:CCIO.read_lines_l;;</code></pre><dl><dt>since</dt><dd>0.16</dd></dl></dd></dl><dl><dt class="spec value" id="val-with_process_out"><a href="#val-with_process_out" class="anchor"></a><code><span class="keyword">val</span> with_process_out : string <span>-></span> f:(Stdlib.out_channel <span>-></span> <span class="type-var">'a</span>) <span>-></span> <span class="type-var">'a</span></code></dt><dd><p>Open a shell command in a subprocess and obtain a handle to its stdin.</p><dl><dt>since</dt><dd>0.16</dd></dl></dd></dl><dl><dt class="spec type" id="type-process_full"><a href="#type-process_full" class="anchor"></a><code><span class="keyword">type</span> process_full</code><code> = < stdin : Stdlib.out_channel; stdout : Stdlib.in_channel; stderr : Stdlib.in_channel; close : Unix.process_status; ></code></dt><dd><p>Handle to a subprocess.</p><dl><dt>since</dt><dd>0.16</dd></dl></dd></dl><dl><dt class="spec value" id="val-with_process_full"><a href="#val-with_process_full" class="anchor"></a><code><span class="keyword">val</span> with_process_full : ?⁠env:string array <span>-></span> string <span>-></span> f:(<a href="index.html#type-process_full">process_full</a> <span>-></span> <span class="type-var">'a</span>) <span>-></span> <span class="type-var">'a</span></code></dt><dd><p>Open a subprocess and obtain a handle to its channels.</p><dl><dt>parameter env</dt><dd><p>environment to pass to the subprocess.</p></dd></dl><dl><dt>since</dt><dd>0.16</dd></dl></dd></dl><dl><dt class="spec value" id="val-ensure_session_leader"><a href="#val-ensure_session_leader" class="anchor"></a><code><span class="keyword">val</span> ensure_session_leader : unit <span>-></span> unit</code></dt><dd><p>On unix, call <code>Unix.setsid()</code> to make sure subprocesses die at the same time as the current process. Does nothing on windows. Idempotent: it can be called several times but will only have effects, if any, the first time.</p><dl><dt>since</dt><dd>2.8</dd></dl></dd></dl></section><section><header><h3 id="networking"><a href="#networking" class="anchor"></a>Networking</h3></header><dl><dt class="spec value" id="val-with_connection"><a href="#val-with_connection" class="anchor"></a><code><span class="keyword">val</span> with_connection : Unix.sockaddr <span>-></span> f:(Stdlib.in_channel <span>-></span> Stdlib.out_channel <span>-></span> <span class="type-var">'a</span>) <span>-></span> <span class="type-var">'a</span></code></dt><dd><p>Wrap <span class="xref-unresolved" title="unresolved reference to "Unix.open_connection""><code>Unix</code>.open_connection</span> with a handler.</p><dl><dt>since</dt><dd>0.16</dd></dl></dd></dl><dl><dt class="spec exception" id="exception-ExitServer"><a href="#exception-ExitServer" class="anchor"></a><code><span class="keyword">exception</span> </code><code><span class="exception">ExitServer</span></code></dt></dl><dl><dt class="spec value" id="val-establish_server"><a href="#val-establish_server" class="anchor"></a><code><span class="keyword">val</span> establish_server : Unix.sockaddr <span>-></span> f:(Stdlib.in_channel <span>-></span> Stdlib.out_channel <span>-></span> <span class="type-var">_</span>) <span>-></span> unit</code></dt><dd><p>Listen on the address and calls the handler in a blocking fashion. Using <code>Thread</code> is recommended if handlers might take time. The callback should raise <a href="index.html#exception-ExitServer"><code>ExitServer</code></a> to stop the loop.</p><dl><dt>since</dt><dd>0.16</dd></dl></dd></dl></section><section><header><h3 id="file-lock"><a href="#file-lock" class="anchor"></a>File lock</h3></header><dl><dt class="spec value" id="val-with_file_lock"><a href="#val-with_file_lock" class="anchor"></a><code><span class="keyword">val</span> with_file_lock : kind:[ `Read | `Write ] <span>-></span> string <span>-></span> (unit <span>-></span> <span class="type-var">'a</span>) <span>-></span> <span class="type-var">'a</span></code></dt><dd><p><code>with_file_lock ~kind filename f</code> puts a lock on the offset 0 of the file named <code>filename</code>, calls <code>f</code> and returns its result after the file is unlocked. If <code>f ()</code> raises an exception the exception is re-raised after the file is unlocked.</p><dl><dt>parameter kind</dt><dd><p>specifies whether the lock is read-only or read-write.</p></dd></dl><dl><dt>since</dt><dd>1.2</dd></dl></dd></dl></section><section><header><h3 id="infix-functions"><a href="#infix-functions" class="anchor"></a>Infix Functions</h3></header><div class="spec module" id="module-Infix"><a href="#module-Infix" class="anchor"></a><code><span class="keyword">module</span> <a href="Infix/index.html">Infix</a> : <span class="keyword">sig</span> ... <span class="keyword">end</span></code></div><div><div class="spec include"><div class="doc"><details open="open"><summary><span class="def"><code><span class="keyword">include</span> <span class="keyword">module</span> <span class="keyword">type</span> <span class="keyword">of</span> <a href="index.html#module-Infix">Infix</a></code></span></summary><dl><dt class="spec value" id="val-(?|)"><a href="#val-(?|)" class="anchor"></a><code><span class="keyword">val</span> (?|) : (<span class="type-var">'a</span>, Stdlib.Buffer.t, unit, <a href="index.html#type-call_result">call_result</a>) Stdlib.format4 <span>-></span> <span class="type-var">'a</span></code></dt><dd><p>Infix version of <a href="index.html#val-call"><code>call</code></a>.</p><dl><dt>since</dt><dd>0.11</dd></dl></dd></dl><dl><dt class="spec value" id="val-(?|&)"><a href="#val-(?|&)" class="anchor"></a><code><span class="keyword">val</span> (?|&) : (<span class="type-var">'a</span>, Stdlib.Buffer.t, unit, <a href="index.html#type-async_call_result">async_call_result</a>) Stdlib.format4 <span>-></span> <span class="type-var">'a</span></code></dt><dd><p>Infix version of <a href="index.html#val-async_call"><code>async_call</code></a>.</p><dl><dt>since</dt><dd>0.11</dd></dl></dd></dl></details></div></div></div></section><section><header><h3 id="temporary-directory"><a href="#temporary-directory" class="anchor"></a>Temporary directory</h3></header><dl><dt class="spec value" id="val-with_temp_dir"><a href="#val-with_temp_dir" class="anchor"></a><code><span class="keyword">val</span> with_temp_dir : ?⁠mode:int <span>-></span> ?⁠dir:string <span>-></span> string <span>-></span> (string <span>-></span> <span class="type-var">'a</span>) <span>-></span> <span class="type-var">'a</span></code></dt><dd><p>Create a temporary directory, call the function, and then destroy the directory afterwards. Usage <code>with_temp_dir pattern f</code>.</p><dl><dt>parameter pattern</dt><dd><p>the naming pattern for the temporary directory. Helps avoiding collisions.</p></dd></dl><dl><dt>parameter mode</dt><dd><p>mode for the directory</p></dd></dl><dl><dt>parameter dir</dt><dd><p>the directory under which to make a temporary directory (default <code>/tmp</code>)</p><p>Note that this is implemented following the discussion at: https://discuss.ocaml.org/t/how-to-create-a-temporary-directory-in-ocaml/1815/</p></dd></dl><dl><dt>since</dt><dd>2.8</dd></dl></dd></dl></section></div></body></html> |