<!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="Up" href="Std.Unix.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 modules" rel=Appendix href="index_modules.html">
<link title="Index of module types" rel=Appendix href="index_module_types.html">
<link title="Async_print" rel="Chapter" href="Async_print.html">
<link title="Async_sys" rel="Chapter" href="Async_sys.html">
<link title="Epoll_file_descr_watcher" rel="Chapter" href="Epoll_file_descr_watcher.html">
<link title="Fd" rel="Chapter" href="Fd.html">
<link title="Fd_by_descr" rel="Chapter" href="Fd_by_descr.html">
<link title="File_descr_watcher_intf" rel="Chapter" href="File_descr_watcher_intf.html">
<link title="Import" rel="Chapter" href="Import.html">
<link title="Interruptor" rel="Chapter" href="Interruptor.html">
<link title="In_thread" rel="Chapter" href="In_thread.html">
<link title="Io_stats" rel="Chapter" href="Io_stats.html">
<link title="Process" rel="Chapter" href="Process.html">
<link title="Raw_fd" rel="Chapter" href="Raw_fd.html">
<link title="Raw_scheduler" rel="Chapter" href="Raw_scheduler.html">
<link title="Raw_signal_manager" rel="Chapter" href="Raw_signal_manager.html">
<link title="Reader" rel="Chapter" href="Reader.html">
<link title="Read_write" rel="Chapter" href="Read_write.html">
<link title="Scheduler" rel="Chapter" href="Scheduler.html">
<link title="Select_file_descr_watcher" rel="Chapter" href="Select_file_descr_watcher.html">
<link title="Shutdown" rel="Chapter" href="Shutdown.html">
<link title="Signal" rel="Chapter" href="Signal.html">
<link title="Signal_manager" rel="Chapter" href="Signal_manager.html">
<link title="Std" rel="Chapter" href="Std.html">
<link title="Syscall" rel="Chapter" href="Syscall.html">
<link title="Thread_pool" rel="Chapter" href="Thread_pool.html">
<link title="Thread_safe" rel="Chapter" href="Thread_safe.html">
<link title="Thread_safe_pipe" rel="Chapter" href="Thread_safe_pipe.html">
<link title="Unix_syscalls" rel="Chapter" href="Unix_syscalls.html">
<link title="Writer" rel="Chapter" href="Writer.html"><title>Std.Unix.Fd</title>
</head>
<body>
<div class="navbar"> <a class="up" href="Std.Unix.html" title="Std.Unix">Up</a>
</div>
<h1>Module <a href="type_Std.Unix.Fd.html">Std.Unix.Fd</a></h1>
<pre><span class="keyword">module</span> Fd: <code class="type"><a href="Std.Fd.html">Std.Fd</a></code></pre><hr width="100%">
<pre><span class="keyword">module</span> <a href="Fd.Kind.html">Kind</a>: <code class="code">sig</code> <a href="Fd.Kind.html">..</a> <code class="code">end</code></pre>
<pre><span id="TYPEt"><span class="keyword">type</span> <code class="type"></code>t</span> </pre>
<pre><span id="VALinfo"><span class="keyword">val</span> info</span> : <code class="type"><a href="Fd.html#TYPEt">t</a> -> Core.Std.Info.t</code></pre>
<pre><span id="VALto_string"><span class="keyword">val</span> to_string</span> : <code class="type"><a href="Fd.html#TYPEt">t</a> -> string</code></pre><div class="info ">
<code class="code">to_string t</code> returns a pretty sexp of the representation of <code class="code">t</code><br>
</div>
<pre><span id="VALcreate"><span class="keyword">val</span> create</span> : <code class="type"><a href="Fd.Kind.html#TYPEt">Kind.t</a> -> Core.Std.Unix.File_descr.t -> Core.Std.Info.t -> <a href="Fd.html#TYPEt">t</a></code></pre><div class="info ">
<code class="code">create kind file_descr</code> creates a new <code class="code">t</code> of the underlying kind and file
descriptor.
<p>
We thought about using <code class="code">fstat()</code> rather than requiring the user to supply the kind.
But <code class="code">fstat</code> can block, which would require putting this in a thread, which has some
consequences, and it isn't clear that it gets us that much. Also, <code class="code">create</code> is mostly
used within the Async implementation -- clients shouldn't need it unless they are
mixing Async and non-Async code.<br>
</div>
<pre><span id="VALkind"><span class="keyword">val</span> kind</span> : <code class="type"><a href="Fd.html#TYPEt">t</a> -> <a href="Fd.Kind.html#TYPEt">Kind.t</a></code></pre><div class="info ">
<code class="code">kind t</code> returns the kind of file descriptor that <code class="code">t</code> is.<br>
</div>
<pre><span id="VALsupports_nonblock"><span class="keyword">val</span> supports_nonblock</span> : <code class="type"><a href="Fd.html#TYPEt">t</a> -> bool</code></pre><div class="info ">
<code class="code">supports_nonblock t</code> returns true if <code class="code">t</code> supports nonblocking system calls.<br>
</div>
<pre><span id="VALclose"><span class="keyword">val</span> close</span> : <code class="type">?should_close_file_descriptor:bool -> <a href="Fd.html#TYPEt">t</a> -> unit Import.Deferred.t</code></pre><div class="info ">
<code class="code">close t</code> prevents further use of <code class="code">t</code>, and closes the underlying file descriptor once
all the current uses are finished. The result of <code class="code">close</code> becomes determined once the
underlying file descriptor has been closed, i.e. once the <code class="code">close()</code> system call
returns. It is ok to call <code class="code">close</code> multiple times on the same <code class="code">t</code>; calls subsequent to
the initial call will have no effect, but will return the same deferred as the
original call.
<p>
In some situations, one may need to cause async to release an fd that it is managing
without closing the underlying file descriptor. In that case, one should supply
<code class="code">~should_close_file_descriptor:false</code>, which will skip the underlying <code class="code">close()</code> system
call.
<p>
<code class="code">close_finished t</code> becomes determined after the <code class="code">close()</code> system call on <code class="code">t</code>'s
underlying file descriptor returns. <code class="code">close_finished</code> differs from <code class="code">close</code> in that it
does not have the side effect of initiating a close.
<p>
<code class="code">is_closed t</code> returns <code class="code">true</code> iff <code class="code">close t</code> has been called.<br>
</div>
<pre><span id="VALclose_finished"><span class="keyword">val</span> close_finished</span> : <code class="type"><a href="Fd.html#TYPEt">t</a> -> unit Import.Deferred.t</code></pre>
<pre><span id="VALis_closed"><span class="keyword">val</span> is_closed</span> : <code class="type"><a href="Fd.html#TYPEt">t</a> -> bool</code></pre>
<pre><span id="VALwith_close"><span class="keyword">val</span> with_close</span> : <code class="type"><a href="Fd.html#TYPEt">t</a> -> f:(<a href="Fd.html#TYPEt">t</a> -> 'a Import.Deferred.t) -> 'a Import.Deferred.t</code></pre><div class="info ">
<code class="code">with_close t f</code> applies <code class="code">f</code> to <code class="code">t</code>, returns the result of <code class="code">f</code>, and closes <code class="code">t</code>.<br>
</div>
<pre><span id="VALis_open"><span class="keyword">val</span> is_open</span> : <code class="type"><a href="Fd.html#TYPEt">t</a> -> bool</code></pre><div class="info ">
<code class="code">is_open t</code> is <code class="code">not (is_closed t</code>)<br>
</div>
<pre><span id="VALstdin"><span class="keyword">val</span> stdin</span> : <code class="type">unit -> <a href="Fd.html#TYPEt">t</a></code></pre><div class="info ">
<code class="code">stdin</code>, <code class="code">stdout</code>, and <code class="code">stderr</code> are wrappers around the standard Unix file
descriptors.<br>
</div>
<pre><span id="VALstdout"><span class="keyword">val</span> stdout</span> : <code class="type">unit -> <a href="Fd.html#TYPEt">t</a></code></pre>
<pre><span id="VALstderr"><span class="keyword">val</span> stderr</span> : <code class="type">unit -> <a href="Fd.html#TYPEt">t</a></code></pre>
<pre><span id="VALwith_file_descr"><span class="keyword">val</span> with_file_descr</span> : <code class="type">?nonblocking:bool -><br> <a href="Fd.html#TYPEt">t</a> -><br> (Core.Std.Unix.File_descr.t -> 'a) -><br> [ `Already_closed | `Error of exn | `Ok of 'a ]</code></pre><div class="info ">
<code class="code">with_file_descr t f</code> runs <code class="code">f</code> on the file descriptor underlying <code class="code">t</code>, if <code class="code">is_open t</code>,
and returns <code class="code">`Ok</code> or <code class="code">`Error</code> according to <code class="code">f</code>. If <code class="code">is_closed t</code>, then it does not
call <code class="code">f</code> and returns <code class="code">`Already_closed</code>.<br>
</div>
<pre><span id="VALwith_file_descr_exn"><span class="keyword">val</span> with_file_descr_exn</span> : <code class="type">?nonblocking:bool -> <a href="Fd.html#TYPEt">t</a> -> (Core.Std.Unix.File_descr.t -> 'a) -> 'a</code></pre><div class="info ">
<code class="code">with_file_descr_exn</code> is like <code class="code">with_file_descr</code> except that it raises rather than
return <code class="code">`Already_closed</code> or <code class="code">`Error</code>.<br>
</div>
<pre><span id="VALwith_file_descr_deferred"><span class="keyword">val</span> with_file_descr_deferred</span> : <code class="type"><a href="Fd.html#TYPEt">t</a> -><br> (Core.Std.Unix.File_descr.t -> 'a Import.Deferred.t) -><br> [ `Already_closed | `Error of exn | `Ok of 'a ] Import.Deferred.t</code></pre><div class="info ">
<code class="code">with_file_descr_deferred t f</code> runs <code class="code">f</code> on the file descriptor underlying <code class="code">t</code>, if
<code class="code">is_open t</code>, and returns <code class="code">`Ok</code> or <code class="code">`Error</code> according to <code class="code">f</code>. If <code class="code">is_closed t</code>, then
it does not call <code class="code">f</code> and returns <code class="code">`Already_closed</code>. It ensures that the file
descriptor underlying <code class="code">t</code> is not closed until the result of <code class="code">f</code> becomes determined (or
<code class="code">f</code> raises).<br>
</div>
<pre><span id="VALready_to_interruptible"><span class="keyword">val</span> ready_to_interruptible</span> : <code class="type"><a href="Fd.html#TYPEt">t</a> -><br> [ `Read | `Write ] -><br> interrupt:unit Import.Deferred.t -><br> [ `Bad_fd | `Closed | `Interrupted | `Ready ] Import.Deferred.t</code></pre><div class="info ">
<code class="code">ready_to_interruptible t read_write ~interrupt</code> returns a deferred that will become
determined when the file descriptor underlying <code class="code">t</code> can be read from or written to
without blocking, or when <code class="code">interrupt</code> becomes determined.<br>
</div>
<pre><span id="VALready_to"><span class="keyword">val</span> ready_to</span> : <code class="type"><a href="Fd.html#TYPEt">t</a> -><br> [ `Read | `Write ] -> [ `Bad_fd | `Closed | `Ready ] Import.Deferred.t</code></pre><div class="info ">
<code class="code">ready_to t read_write</code> is like <code class="code">ready_to_interruptible</code>, but without the possibility
of interruption.<br>
</div>
<pre><span id="VALsyscall"><span class="keyword">val</span> syscall</span> : <code class="type">?nonblocking:bool -><br> <a href="Fd.html#TYPEt">t</a> -><br> (Core.Std.Unix.File_descr.t -> 'a) -><br> [ `Already_closed | `Error of exn | `Ok of 'a ]</code></pre><div class="info ">
<code class="code">syscall t f</code> runs <code class="code">Async_unix.syscall</code> with <code class="code">f</code> on the file descriptor underlying
<code class="code">t</code>, if <code class="code">is_open t</code>, and returns <code class="code">`Ok</code> or <code class="code">`Error</code> according to <code class="code">f</code>. If
<code class="code">is_closed t</code>, it does not call <code class="code">f</code> and returns <code class="code">`Already_closed</code>.<br>
</div>
<pre><span id="VALsyscall_exn"><span class="keyword">val</span> syscall_exn</span> : <code class="type">?nonblocking:bool -> <a href="Fd.html#TYPEt">t</a> -> (Core.Std.Unix.File_descr.t -> 'a) -> 'a</code></pre><div class="info ">
<code class="code">syscall_exn t f</code> is like <code class="code">syscall</code>, except it raises rather than return
<code class="code">`Already_closed</code> or <code class="code">`Error</code>.<br>
</div>
<pre><span id="VALsyscall_in_thread"><span class="keyword">val</span> syscall_in_thread</span> : <code class="type"><a href="Fd.html#TYPEt">t</a> -><br> name:string -><br> (Core.Std.Unix.File_descr.t -> 'a) -><br> [ `Already_closed | `Error of exn | `Ok of 'a ] Import.Deferred.t</code></pre><div class="info ">
<code class="code">syscall_in_thread t f</code> runs <code class="code">In_thread.syscall</code> with <code class="code">f</code> on the file descriptor
underlying <code class="code">t</code>, if <code class="code">is_open t</code>, and returns a deferred that becomes determined with
<code class="code">`Ok</code> or <code class="code">`Error</code> when the system call completes. If <code class="code">is_closed t</code>, it does not call
<code class="code">f</code> and returns <code class="code">`Already_closed</code>.<br>
</div>
<pre><span id="VALsyscall_in_thread_exn"><span class="keyword">val</span> syscall_in_thread_exn</span> : <code class="type"><a href="Fd.html#TYPEt">t</a> -><br> name:string -> (Core.Std.Unix.File_descr.t -> 'a) -> 'a Import.Deferred.t</code></pre><div class="info ">
<code class="code">syscall_in_thread_exn</code> is like <code class="code">syscall_in_thread</code>, except it raises rather than
return <code class="code">`Already_closed</code> or <code class="code">`Error</code>.<br>
</div>
<pre><span id="VALof_in_channel"><span class="keyword">val</span> of_in_channel</span> : <code class="type">Core.Std.In_channel.t -> <a href="Fd.Kind.html#TYPEt">Kind.t</a> -> <a href="Fd.html#TYPEt">t</a></code></pre><div class="info ">
<code class="code">of_in_channel</code> and <code class="code">of_out_channel</code> create an fd from their underlying file
descriptor.<br>
</div>
<pre><span id="VALof_out_channel"><span class="keyword">val</span> of_out_channel</span> : <code class="type">Core.Std.Out_channel.t -> <a href="Fd.Kind.html#TYPEt">Kind.t</a> -> <a href="Fd.html#TYPEt">t</a></code></pre>
<pre><span id="VALof_in_channel_auto"><span class="keyword">val</span> of_in_channel_auto</span> : <code class="type">Core.Std.In_channel.t -> <a href="Fd.html#TYPEt">t</a> Import.Deferred.t</code></pre><div class="info ">
<code class="code">of_in_channel_auto ic</code> is just like of_in_channel, but uses <code class="code">fstat</code> to determine the
kind. It makes some assumptions about sockets, specifically it assumes that a socket
is either listening, or connected to something (and it uses getsockopt to find out
which). Don't pass an in_channel containing an unconnected non-listening socket.<br>
</div>
<pre><span id="VALof_out_channel_auto"><span class="keyword">val</span> of_out_channel_auto</span> : <code class="type">Core.Std.Out_channel.t -> <a href="Fd.html#TYPEt">t</a> Import.Deferred.t</code></pre><div class="info ">
<code class="code">of_out_channel_auto ic</code> is just like of_out_channel, but uses <code class="code">fstat</code> to determine
the kind. It makes some assumptions about sockets, specifically it assumes that a
socket is either listening, or connected to something (and it uses getsockopt to find
out which). Don't pass an in_channel containing an unconnected non listening
socket.<br>
</div>
<pre><span id="VALfile_descr_exn"><span class="keyword">val</span> file_descr_exn</span> : <code class="type"><a href="Fd.html#TYPEt">t</a> -> Core.Std.Unix.File_descr.t</code></pre><div class="info ">
<code class="code">file_descr_exn t</code> returns the file descriptor underlying <code class="code">t</code>, unless <code class="code">is_closed t</code>,
in which case it raises. One must be very careful when using this function, and
should try not to, since any uses of the resulting file descriptor are unknown to
the <code class="code">Fd</code> module, and hence can violate the guarantee it is trying to enforce.<br>
</div>
<pre><span id="VALto_int_exn"><span class="keyword">val</span> to_int_exn</span> : <code class="type"><a href="Fd.html#TYPEt">t</a> -> int</code></pre><div class="info ">
<code class="code">to_int_exn t</code> returns the the underlying file descriptor as an int. It has the same
caveats as <code class="code">file_descr_exn</code>.<br>
</div>
<pre><span id="VALreplace"><span class="keyword">val</span> replace</span> : <code class="type"><a href="Fd.html#TYPEt">t</a> -> <a href="Fd.Kind.html#TYPEt">Kind.t</a> -> Core.Std.Info.t -> unit</code></pre><div class="info ">
<code class="code">replace t kind</code> is for internal use only, by <code class="code">Unix_syscalls</code>. It is used when one
wants to reuse a file descriptor in an fd with a new kind.<br>
</div>
<pre><span id="VALsexp_of_t"><span class="keyword">val</span> sexp_of_t</span> : <code class="type"><a href="Fd.html#TYPEt">t</a> -> Sexplib.Sexp.t</code></pre><br>
<code class="code">to_string t</code> returns a pretty sexp of the representation of <code class="code">t</code><br>
<br>
<code class="code">create kind file_descr</code> creates a new <code class="code">t</code> of the underlying kind and file
descriptor.
<p>
We thought about using <code class="code">fstat()</code> rather than requiring the user to supply the kind.
But <code class="code">fstat</code> can block, which would require putting this in a thread, which has some
consequences, and it isn't clear that it gets us that much. Also, <code class="code">create</code> is mostly
used within the Async implementation -- clients shouldn't need it unless they are
mixing Async and non-Async code.<br>
<br>
<code class="code">kind t</code> returns the kind of file descriptor that <code class="code">t</code> is.<br>
<br>
<code class="code">supports_nonblock t</code> returns true if <code class="code">t</code> supports nonblocking system calls.<br>
<br>
<code class="code">close t</code> prevents further use of <code class="code">t</code>, and closes the underlying file descriptor once
all the current uses are finished. The result of <code class="code">close</code> becomes determined once the
underlying file descriptor has been closed, i.e. once the <code class="code">close()</code> system call
returns. It is ok to call <code class="code">close</code> multiple times on the same <code class="code">t</code>; calls subsequent to
the initial call will have no effect, but will return the same deferred as the
original call.
<p>
In some situations, one may need to cause async to release an fd that it is managing
without closing the underlying file descriptor. In that case, one should supply
<code class="code">~should_close_file_descriptor:false</code>, which will skip the underlying <code class="code">close()</code> system
call.
<p>
<code class="code">close_finished t</code> becomes determined after the <code class="code">close()</code> system call on <code class="code">t</code>'s
underlying file descriptor returns. <code class="code">close_finished</code> differs from <code class="code">close</code> in that it
does not have the side effect of initiating a close.
<p>
<code class="code">is_closed t</code> returns <code class="code">true</code> iff <code class="code">close t</code> has been called.<br>
<br>
<code class="code">with_close t f</code> applies <code class="code">f</code> to <code class="code">t</code>, returns the result of <code class="code">f</code>, and closes <code class="code">t</code>.<br>
<br>
<code class="code">is_open t</code> is <code class="code">not (is_closed t</code>)<br>
<br>
<code class="code">stdin</code>, <code class="code">stdout</code>, and <code class="code">stderr</code> are wrappers around the standard Unix file
descriptors.<br>
<br>
<code class="code">with_file_descr t f</code> runs <code class="code">f</code> on the file descriptor underlying <code class="code">t</code>, if <code class="code">is_open t</code>,
and returns <code class="code">`Ok</code> or <code class="code">`Error</code> according to <code class="code">f</code>. If <code class="code">is_closed t</code>, then it does not
call <code class="code">f</code> and returns <code class="code">`Already_closed</code>.<br>
<br>
<code class="code">with_file_descr_exn</code> is like <code class="code">with_file_descr</code> except that it raises rather than
return <code class="code">`Already_closed</code> or <code class="code">`Error</code>.<br>
<br>
<code class="code">with_file_descr_deferred t f</code> runs <code class="code">f</code> on the file descriptor underlying <code class="code">t</code>, if
<code class="code">is_open t</code>, and returns <code class="code">`Ok</code> or <code class="code">`Error</code> according to <code class="code">f</code>. If <code class="code">is_closed t</code>, then
it does not call <code class="code">f</code> and returns <code class="code">`Already_closed</code>. It ensures that the file
descriptor underlying <code class="code">t</code> is not closed until the result of <code class="code">f</code> becomes determined (or
<code class="code">f</code> raises).<br>
<br>
<code class="code">ready_to_interruptible t read_write ~interrupt</code> returns a deferred that will become
determined when the file descriptor underlying <code class="code">t</code> can be read from or written to
without blocking, or when <code class="code">interrupt</code> becomes determined.<br>
<br>
<code class="code">ready_to t read_write</code> is like <code class="code">ready_to_interruptible</code>, but without the possibility
of interruption.<br>
<br>
<code class="code">syscall t f</code> runs <code class="code">Async_unix.syscall</code> with <code class="code">f</code> on the file descriptor underlying
<code class="code">t</code>, if <code class="code">is_open t</code>, and returns <code class="code">`Ok</code> or <code class="code">`Error</code> according to <code class="code">f</code>. If
<code class="code">is_closed t</code>, it does not call <code class="code">f</code> and returns <code class="code">`Already_closed</code>.<br>
<br>
<code class="code">syscall_exn t f</code> is like <code class="code">syscall</code>, except it raises rather than return
<code class="code">`Already_closed</code> or <code class="code">`Error</code>.<br>
<br>
<code class="code">syscall_in_thread t f</code> runs <code class="code">In_thread.syscall</code> with <code class="code">f</code> on the file descriptor
underlying <code class="code">t</code>, if <code class="code">is_open t</code>, and returns a deferred that becomes determined with
<code class="code">`Ok</code> or <code class="code">`Error</code> when the system call completes. If <code class="code">is_closed t</code>, it does not call
<code class="code">f</code> and returns <code class="code">`Already_closed</code>.<br>
<br>
<code class="code">syscall_in_thread_exn</code> is like <code class="code">syscall_in_thread</code>, except it raises rather than
return <code class="code">`Already_closed</code> or <code class="code">`Error</code>.<br>
<br>
<code class="code">of_in_channel</code> and <code class="code">of_out_channel</code> create an fd from their underlying file
descriptor.<br>
<br>
<code class="code">of_in_channel_auto ic</code> is just like of_in_channel, but uses <code class="code">fstat</code> to determine the
kind. It makes some assumptions about sockets, specifically it assumes that a socket
is either listening, or connected to something (and it uses getsockopt to find out
which). Don't pass an in_channel containing an unconnected non-listening socket.<br>
<br>
<code class="code">of_out_channel_auto ic</code> is just like of_out_channel, but uses <code class="code">fstat</code> to determine
the kind. It makes some assumptions about sockets, specifically it assumes that a
socket is either listening, or connected to something (and it uses getsockopt to find
out which). Don't pass an in_channel containing an unconnected non listening
socket.<br>
<br>
<code class="code">file_descr_exn t</code> returns the file descriptor underlying <code class="code">t</code>, unless <code class="code">is_closed t</code>,
in which case it raises. One must be very careful when using this function, and
should try not to, since any uses of the resulting file descriptor are unknown to
the <code class="code">Fd</code> module, and hence can violate the guarantee it is trying to enforce.<br>
<br>
<code class="code">to_int_exn t</code> returns the the underlying file descriptor as an int. It has the same
caveats as <code class="code">file_descr_exn</code>.<br>
<br>
<code class="code">replace t kind</code> is for internal use only, by <code class="code">Unix_syscalls</code>. It is used when one
wants to reuse a file descriptor in an fd with a new kind.<br>
</body></html>
