mirror of
https://github.com/c-cube/ocaml-containers.git
synced 2025-12-06 11:15:31 -05:00
57 lines
24 KiB
HTML
57 lines
24 KiB
HTML
<!DOCTYPE html>
|
||
<html xmlns="http://www.w3.org/1999/xhtml"><head><title>CCUnix (containers.CCUnix)</title><meta charset="utf-8"/><link rel="stylesheet" href="../../odoc.support/odoc.css"/><meta name="generator" content="odoc 2.4.3"/><meta name="viewport" content="width=device-width,initial-scale=1.0"/><script src="../../odoc.support/highlight.pack.js"></script><script>hljs.initHighlightingOnLoad();</script></head><body class="odoc"><nav class="odoc-nav"><a href="../index.html">Up</a> – <a href="../index.html">containers</a> » CCUnix</nav><header class="odoc-preamble"><h1>Module <code><span>CCUnix</span></code></h1></header><nav class="odoc-toc"><ul><li><a href="#high-level-functions-on-top-of-unix">High-level Functions on top of Unix</a><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></li></ul></nav><div class="odoc-content"><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><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 0.10</li></ul><div class="odoc-spec"><div class="spec type anchored" id="type-or_error"><a href="#type-or_error" class="anchor"></a><code><span><span class="keyword">type</span> <span>'a or_error</span></span><span> = <span><span>(<span class="type-var">'a</span>, string)</span> <span class="xref-unresolved">Stdlib</span>.result</span></span></code></div></div><div class="odoc-spec"><div class="spec type anchored" id="type-gen"><a href="#type-gen" class="anchor"></a><code><span><span class="keyword">type</span> <span>'a gen</span></span><span> = <span>unit <span class="arrow">-></span></span> <span><span class="type-var">'a</span> option</span></span></code></div></div><h3 id="calling-commands"><a href="#calling-commands" class="anchor"></a>Calling Commands</h3><div class="odoc-spec"><div class="spec value anchored" id="val-escape_str"><a href="#val-escape_str" class="anchor"></a><code><span><span class="keyword">val</span> escape_str : <span>string <span class="arrow">-></span></span> string</span></code></div><div class="spec-doc"><p>Escape a string so it can be a shell argument.</p></div></div><div class="odoc-spec"><div class="spec type anchored" id="type-call_result"><a href="#type-call_result" class="anchor"></a><code><span><span class="keyword">type</span> call_result</span><span> =
|
||
<span>< stdout : string
|
||
; stderr : string
|
||
; status : <span class="xref-unresolved">Unix</span>.process_status
|
||
; errcode : int ></span></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-call_full"><a href="#val-call_full" class="anchor"></a><code><span><span class="keyword">val</span> call_full :
|
||
<span><span class="optlabel">?bufsize</span>:int <span class="arrow">-></span></span>
|
||
<span><span class="optlabel">?stdin</span>:<span>[ <span>`Gen of <span>string <a href="#type-gen">gen</a></span></span> <span><span>| `Str</span> of string</span> ]</span> <span class="arrow">-></span></span>
|
||
<span><span class="optlabel">?env</span>:<span>string array</span> <span class="arrow">-></span></span>
|
||
<span><span><span>(<span class="type-var">'a</span>, <span class="xref-unresolved">Stdlib</span>.Buffer.t, unit, <a href="#type-call_result">call_result</a>)</span> <span class="xref-unresolved">Stdlib</span>.format4</span> <span class="arrow">-></span></span>
|
||
<span class="type-var">'a</span></span></code></div><div class="spec-doc"><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. <code>cmd</code> can be a format string as in <code>Printf</code>.</p><ul class="at-tags"><li class="parameter"><span class="at-tag">parameter</span> <span class="value">stdin</span> <p>if provided, the generator or string is consumed and fed to the subprocess input channel, which is then closed.</p></li></ul><ul class="at-tags"><li class="parameter"><span class="at-tag">parameter</span> <span class="value">bufsize</span> <p>buffer size used to read stdout and stderr.</p></li></ul><ul class="at-tags"><li class="parameter"><span class="at-tag">parameter</span> <span class="value">env</span> <p>environment to run the command in.</p><p>Example:</p><pre class="language-ocaml"><code># CCUnix.call_full "ls %s" (CCUnix.escape_str "/");;</code></pre></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-call"><a href="#val-call" class="anchor"></a><code><span><span class="keyword">val</span> call :
|
||
<span><span class="optlabel">?bufsize</span>:int <span class="arrow">-></span></span>
|
||
<span><span class="optlabel">?stdin</span>:<span>[ <span>`Gen of <span>string <a href="#type-gen">gen</a></span></span> <span><span>| `Str</span> of string</span> ]</span> <span class="arrow">-></span></span>
|
||
<span><span class="optlabel">?env</span>:<span>string array</span> <span class="arrow">-></span></span>
|
||
<span><span><span>(<span class="type-var">'a</span>, <span class="xref-unresolved">Stdlib</span>.Buffer.t, unit, string * string * int)</span> <span class="xref-unresolved">Stdlib</span>.format4</span> <span class="arrow">-></span></span>
|
||
<span class="type-var">'a</span></span></code></div><div class="spec-doc"><p><code>call cmd</code> is similar to <a href="#val-call_full"><code>call_full</code></a> but returns a tuple <code>stdout, stderr, errcode</code> instead of an object.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-call_stdout"><a href="#val-call_stdout" class="anchor"></a><code><span><span class="keyword">val</span> call_stdout :
|
||
<span><span class="optlabel">?bufsize</span>:int <span class="arrow">-></span></span>
|
||
<span><span class="optlabel">?stdin</span>:<span>[ <span>`Gen of <span>string <a href="#type-gen">gen</a></span></span> <span><span>| `Str</span> of string</span> ]</span> <span class="arrow">-></span></span>
|
||
<span><span class="optlabel">?env</span>:<span>string array</span> <span class="arrow">-></span></span>
|
||
<span><span><span>(<span class="type-var">'a</span>, <span class="xref-unresolved">Stdlib</span>.Buffer.t, unit, string)</span> <span class="xref-unresolved">Stdlib</span>.format4</span> <span class="arrow">-></span></span>
|
||
<span class="type-var">'a</span></span></code></div></div><div class="odoc-spec"><div class="spec type anchored" id="type-line"><a href="#type-line" class="anchor"></a><code><span><span class="keyword">type</span> line</span><span> = string</span></code></div></div><div class="odoc-spec"><div class="spec type anchored" id="type-async_call_result"><a href="#type-async_call_result" class="anchor"></a><code><span><span class="keyword">type</span> async_call_result</span><span> =
|
||
<span>< stdout : <span><a href="#type-line">line</a> <a href="#type-gen">gen</a></span>
|
||
; stderr : <span><a href="#type-line">line</a> <a href="#type-gen">gen</a></span>
|
||
; stdin : <span><a href="#type-line">line</a> <span class="arrow">-></span></span> unit
|
||
; close_in : unit
|
||
; close_err : unit
|
||
; close_out : unit
|
||
; close_all : unit
|
||
; wait : <span class="xref-unresolved">Unix</span>.process_status
|
||
; wait_errcode : int ></span></span></code></div><div class="spec-doc"><p>A subprocess for interactive usage (read/write channels line by line)</p><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 0.11</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-async_call"><a href="#val-async_call" class="anchor"></a><code><span><span class="keyword">val</span> async_call :
|
||
<span><span class="optlabel">?env</span>:<span>string array</span> <span class="arrow">-></span></span>
|
||
<span><span><span>(<span class="type-var">'a</span>, <span class="xref-unresolved">Stdlib</span>.Buffer.t, unit, <a href="#type-async_call_result">async_call_result</a>)</span> <span class="xref-unresolved">Stdlib</span>.format4</span> <span class="arrow">-></span></span>
|
||
<span class="type-var">'a</span></span></code></div><div class="spec-doc"><p>Spawns a subprocess, like <a href="#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><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 0.11</li></ul></div></div><h3 id="accessors"><a href="#accessors" class="anchor"></a>Accessors</h3><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 0.11</li></ul><div class="odoc-spec"><div class="spec value anchored" id="val-stdout"><a href="#val-stdout" class="anchor"></a><code><span><span class="keyword">val</span> stdout : <span><span>< stdout : <span class="type-var">'a</span>.. ></span> <span class="arrow">-></span></span> <span class="type-var">'a</span></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-stderr"><a href="#val-stderr" class="anchor"></a><code><span><span class="keyword">val</span> stderr : <span><span>< stderr : <span class="type-var">'a</span>.. ></span> <span class="arrow">-></span></span> <span class="type-var">'a</span></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-status"><a href="#val-status" class="anchor"></a><code><span><span class="keyword">val</span> status : <span><span>< status : <span class="type-var">'a</span>.. ></span> <span class="arrow">-></span></span> <span class="type-var">'a</span></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-errcode"><a href="#val-errcode" class="anchor"></a><code><span><span class="keyword">val</span> errcode : <span><span>< errcode : <span class="type-var">'a</span>.. ></span> <span class="arrow">-></span></span> <span class="type-var">'a</span></span></code></div></div><h3 id="simple-io"><a href="#simple-io" class="anchor"></a>Simple IO</h3><div class="odoc-spec"><div class="spec value anchored" id="val-with_in"><a href="#val-with_in" class="anchor"></a><code><span><span class="keyword">val</span> with_in :
|
||
<span><span class="optlabel">?mode</span>:int <span class="arrow">-></span></span>
|
||
<span><span class="optlabel">?flags</span>:<span><span class="xref-unresolved">Unix</span>.open_flag list</span> <span class="arrow">-></span></span>
|
||
<span>string <span class="arrow">-></span></span>
|
||
<span><span class="label">f</span>:<span>(<span><span class="xref-unresolved">Stdlib</span>.in_channel <span class="arrow">-></span></span> <span class="type-var">'a</span>)</span> <span class="arrow">-></span></span>
|
||
<span class="type-var">'a</span></span></code></div><div class="spec-doc"><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><ul class="at-tags"><li class="parameter"><span class="at-tag">parameter</span> <span class="value">flags</span> <p>opening flags. <code>Unix.O_RDONLY</code> is used in any cases.</p></li></ul><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 0.16</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-with_out"><a href="#val-with_out" class="anchor"></a><code><span><span class="keyword">val</span> with_out :
|
||
<span><span class="optlabel">?mode</span>:int <span class="arrow">-></span></span>
|
||
<span><span class="optlabel">?flags</span>:<span><span class="xref-unresolved">Unix</span>.open_flag list</span> <span class="arrow">-></span></span>
|
||
<span>string <span class="arrow">-></span></span>
|
||
<span><span class="label">f</span>:<span>(<span><span class="xref-unresolved">Stdlib</span>.out_channel <span class="arrow">-></span></span> <span class="type-var">'a</span>)</span> <span class="arrow">-></span></span>
|
||
<span class="type-var">'a</span></span></code></div><div class="spec-doc"><p>Same as <a href="#val-with_in"><code>with_in</code></a> but for an output channel.</p><ul class="at-tags"><li class="parameter"><span class="at-tag">parameter</span> <span class="value">flags</span> <p>opening flags (default <code>[Unix.O_CREAT; Unix.O_TRUNC]</code>) <code>Unix.O_WRONLY</code> is used in any cases.</p></li></ul><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 0.16</li></ul></div></div><h3 id="subprocesses"><a href="#subprocesses" class="anchor"></a>Subprocesses</h3><div class="odoc-spec"><div class="spec value anchored" id="val-with_process_in"><a href="#val-with_process_in" class="anchor"></a><code><span><span class="keyword">val</span> with_process_in : <span>string <span class="arrow">-></span></span> <span><span class="label">f</span>:<span>(<span><span class="xref-unresolved">Stdlib</span>.in_channel <span class="arrow">-></span></span> <span class="type-var">'a</span>)</span> <span class="arrow">-></span></span> <span class="type-var">'a</span></span></code></div><div class="spec-doc"><p>Open a shell command in a subprocess and obtain a handle to its stdout.</p><pre class="language-ocaml"><code>CCUnix.with_process_in "ls /tmp" ~f:CCIO.read_lines_l;;</code></pre><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 0.16</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-with_process_out"><a href="#val-with_process_out" class="anchor"></a><code><span><span class="keyword">val</span> with_process_out : <span>string <span class="arrow">-></span></span> <span><span class="label">f</span>:<span>(<span><span class="xref-unresolved">Stdlib</span>.out_channel <span class="arrow">-></span></span> <span class="type-var">'a</span>)</span> <span class="arrow">-></span></span> <span class="type-var">'a</span></span></code></div><div class="spec-doc"><p>Open a shell command in a subprocess and obtain a handle to its stdin.</p><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 0.16</li></ul></div></div><div class="odoc-spec"><div class="spec type anchored" id="type-process_full"><a href="#type-process_full" class="anchor"></a><code><span><span class="keyword">type</span> process_full</span><span> =
|
||
<span>< stdin : <span class="xref-unresolved">Stdlib</span>.out_channel
|
||
; stdout : <span class="xref-unresolved">Stdlib</span>.in_channel
|
||
; stderr : <span class="xref-unresolved">Stdlib</span>.in_channel
|
||
; close : <span class="xref-unresolved">Unix</span>.process_status ></span></span></code></div><div class="spec-doc"><p>Handle to a subprocess.</p><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 0.16</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-with_process_full"><a href="#val-with_process_full" class="anchor"></a><code><span><span class="keyword">val</span> with_process_full :
|
||
<span><span class="optlabel">?env</span>:<span>string array</span> <span class="arrow">-></span></span>
|
||
<span>string <span class="arrow">-></span></span>
|
||
<span><span class="label">f</span>:<span>(<span><a href="#type-process_full">process_full</a> <span class="arrow">-></span></span> <span class="type-var">'a</span>)</span> <span class="arrow">-></span></span>
|
||
<span class="type-var">'a</span></span></code></div><div class="spec-doc"><p>Open a subprocess and obtain a handle to its channels.</p><ul class="at-tags"><li class="parameter"><span class="at-tag">parameter</span> <span class="value">env</span> <p>environment to pass to the subprocess.</p></li></ul><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 0.16</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-ensure_session_leader"><a href="#val-ensure_session_leader" class="anchor"></a><code><span><span class="keyword">val</span> ensure_session_leader : <span>unit <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><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><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 2.8</li></ul></div></div><h3 id="networking"><a href="#networking" class="anchor"></a>Networking</h3><div class="odoc-spec"><div class="spec value anchored" id="val-with_connection"><a href="#val-with_connection" class="anchor"></a><code><span><span class="keyword">val</span> with_connection :
|
||
<span><span class="xref-unresolved">Unix</span>.sockaddr <span class="arrow">-></span></span>
|
||
<span><span class="label">f</span>:<span>(<span><span class="xref-unresolved">Stdlib</span>.in_channel <span class="arrow">-></span></span> <span><span class="xref-unresolved">Stdlib</span>.out_channel <span class="arrow">-></span></span> <span class="type-var">'a</span>)</span> <span class="arrow">-></span></span>
|
||
<span class="type-var">'a</span></span></code></div><div class="spec-doc"><p>Wrap <code>Unix.open_connection</code> with a handler.</p><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 0.16</li></ul></div></div><div class="odoc-spec"><div class="spec exception anchored" id="exception-ExitServer"><a href="#exception-ExitServer" class="anchor"></a><code><span><span class="keyword">exception</span> </span><span><span class="exception">ExitServer</span></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-establish_server"><a href="#val-establish_server" class="anchor"></a><code><span><span class="keyword">val</span> establish_server :
|
||
<span><span class="xref-unresolved">Unix</span>.sockaddr <span class="arrow">-></span></span>
|
||
<span><span class="label">f</span>:<span>(<span><span class="xref-unresolved">Stdlib</span>.in_channel <span class="arrow">-></span></span> <span><span class="xref-unresolved">Stdlib</span>.out_channel <span class="arrow">-></span></span> <span class="type-var">_</span>)</span> <span class="arrow">-></span></span>
|
||
unit</span></code></div><div class="spec-doc"><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="#exception-ExitServer"><code>ExitServer</code></a> to stop the loop.</p><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 0.16</li></ul></div></div><h3 id="file-lock"><a href="#file-lock" class="anchor"></a>File lock</h3><div class="odoc-spec"><div class="spec value anchored" id="val-with_file_lock"><a href="#val-with_file_lock" class="anchor"></a><code><span><span class="keyword">val</span> with_file_lock : <span><span class="label">kind</span>:<span>[ `Read <span>| `Write</span> ]</span> <span class="arrow">-></span></span> <span>string <span class="arrow">-></span></span> <span><span>(<span>unit <span class="arrow">-></span></span> <span class="type-var">'a</span>)</span> <span class="arrow">-></span></span> <span class="type-var">'a</span></span></code></div><div class="spec-doc"><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><ul class="at-tags"><li class="parameter"><span class="at-tag">parameter</span> <span class="value">kind</span> <p>specifies whether the lock is read-only or read-write.</p></li></ul><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 1.2</li></ul></div></div><h3 id="infix-functions"><a href="#infix-functions" class="anchor"></a>Infix Functions</h3><div class="odoc-spec"><div class="spec module anchored" id="module-Infix"><a href="#module-Infix" class="anchor"></a><code><span><span class="keyword">module</span> <a href="Infix/index.html">Infix</a></span><span> : <span class="keyword">sig</span> ... <span class="keyword">end</span></span></code></div></div><div class="odoc-include"><details open="open"><summary class="spec include"><code><span><span class="keyword">include</span> <span class="keyword">module</span> <span class="keyword">type</span> <span class="keyword">of</span> <a href="Infix/index.html">Infix</a></span></code></summary><div class="odoc-spec"><div class="spec value anchored" id="val-(?|)"><a href="#val-(?|)" class="anchor"></a><code><span><span class="keyword">val</span> (?|) : <span><span><span>(<span class="type-var">'a</span>, <span class="xref-unresolved">Stdlib</span>.Buffer.t, unit, <a href="#type-call_result">call_result</a>)</span> <span class="xref-unresolved">Stdlib</span>.format4</span> <span class="arrow">-></span></span> <span class="type-var">'a</span></span></code></div><div class="spec-doc"><p>Infix version of <a href="#val-call"><code>call</code></a>.</p><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 0.11</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-(?|&)"><a href="#val-(?|&)" class="anchor"></a><code><span><span class="keyword">val</span> (?|&) : <span><span><span>(<span class="type-var">'a</span>, <span class="xref-unresolved">Stdlib</span>.Buffer.t, unit, <a href="#type-async_call_result">async_call_result</a>)</span> <span class="xref-unresolved">Stdlib</span>.format4</span> <span class="arrow">-></span></span> <span class="type-var">'a</span></span></code></div><div class="spec-doc"><p>Infix version of <a href="#val-async_call"><code>async_call</code></a>.</p><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 0.11</li></ul></div></div></details></div><h3 id="temporary-directory"><a href="#temporary-directory" class="anchor"></a>Temporary directory</h3><div class="odoc-spec"><div class="spec value anchored" id="val-with_temp_dir"><a href="#val-with_temp_dir" class="anchor"></a><code><span><span class="keyword">val</span> with_temp_dir : <span><span class="optlabel">?mode</span>:int <span class="arrow">-></span></span> <span><span class="optlabel">?dir</span>:string <span class="arrow">-></span></span> <span>string <span class="arrow">-></span></span> <span><span>(<span>string <span class="arrow">-></span></span> <span class="type-var">'a</span>)</span> <span class="arrow">-></span></span> <span class="type-var">'a</span></span></code></div><div class="spec-doc"><p>Create a temporary directory, call the function, and then destroy the directory afterwards. Usage <code>with_temp_dir pattern f</code>.</p><ul class="at-tags"><li class="parameter"><span class="at-tag">parameter</span> <span class="value">pattern</span> <p>the naming pattern for the temporary directory. Helps avoiding collisions.</p></li></ul><ul class="at-tags"><li class="parameter"><span class="at-tag">parameter</span> <span class="value">mode</span> <p>mode for the directory</p></li></ul><ul class="at-tags"><li class="parameter"><span class="at-tag">parameter</span> <span class="value">dir</span> <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></li></ul><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 2.8</li></ul></div></div></div></body></html>
|