reference.html

快速开发

<PRE>
#include &lt;st.h&gt;

st_netfd_t st_netfd_open_socket(int osfd);
</PRE>
<P>
<H5>Parameters</H5>
<TT>st_netfd_open_socket()</TT> has the following parameters:<P>
<TT>osfd</TT><P>
An open OS file descriptor which is a socket initially obtained from a<TT>
socket(3) or socketpair(3)</TT> call.
<P>
<H5>Returns</H5>
Upon successful completion, a new file descriptor object identifier is
returned. Otherwise, <TT>NULL</TT> is returned and <TT>errno</TT> is set
to indicate the error.
<P>
<H5>Description</H5>
This function creates a new file descriptor object of type
<A HREF=#netfd_t><B>st_netfd_t</B></A> which represents an open end
point of network communication.<P>
Unlike the <A HREF=#netfd_open>st_netfd_open()</A> function which may be used
on OS file descriptors of any origin, <TT>st_netfd_open_socket()</TT> must
be used only on sockets. It is slightly more efficient than
<A HREF=#netfd_open>st_netfd_open()</A>.<P>
<B>Note:</B> Among other things, this function sets a non-blocking flag
on the underlying OS socket. You should not modify this flag directly.
See <A HREF=#netfd_open>st_netfd_open()</A>.
<P>
<HR>
<P>
<A NAME="netfd_free">
<H4>st_netfd_free()</H4>
</A>
Frees a file descriptor object without closing the underlying OS file
descriptor.
<P>
<H5>Syntax</H5>

<PRE>
#include &lt;st.h&gt;

void st_netfd_free(st_netfd_t fd);
</PRE>
<P>
<H5>Parameters</H5>
<TT>st_netfd_free()</TT> has the following parameters:<P>
<TT>fd</TT><P>
A file descriptor object identifier (see
<A HREF=#netfd_t><B>st_netfd_t</B></A>).
<P>
<H5>Returns</H5>
Nothing.
<P>
<H5>Description</H5>
This function frees the memory and other resources identified by the
<TT>fd</TT> parameter without closing the underlying OS file descriptor.
Any non-<TT>NULL</TT> descriptor-specific data is destroyed by invoking
the specified destructor function (see <A
HREF=#netfd_setspecific>st_netfd_setspecific()</A>).<P> A thread should
not free file descriptor objects that are in use by other threads
because it may lead to unpredictable results (e.g., a freed file
descriptor may be reused without other threads knowing that).
<P>
<HR>
<P>
<A NAME="netfd_close">
<H4>st_netfd_close()</H4>
</A>
Closes a file descriptor.
<P>
<H5>Syntax</H5>

<PRE>
#include &lt;st.h&gt;

int st_netfd_close(st_netfd_t fd);
</PRE>
<P>
<H5>Parameters</H5>
<TT>st_netfd_close()</TT> has the following parameters:<P>
<TT>fd</TT><P>
A file descriptor object identifier (see
<A HREF=#netfd_t><B>st_netfd_t</B></A>).
<P>
<H5>Returns</H5>
Upon successful completion, a value of <TT>0</TT> is returned.
Otherwise, a value of <TT>-1</TT> is returned and <TT>errno</TT> is set
to indicate the error.
<P>
<H5>Description</H5>
This function closes the underlying OS file descriptor, frees the memory and
other resources identified by the <TT>fd</TT> parameter. Any non-<TT>NULL</TT>
descriptor-specific data is destroyed by invoking the specified destructor
function (see <A HREF=#netfd_setspecific>st_netfd_setspecific()</A>).<P>
A thread should not close file descriptor objects that are in use by other
threads because it may lead to unpredictable results (e.g., a closed
file descriptor may be reused without other threads knowing that).
<P>
<HR>
<P>
<A NAME="netfd_fileno">
<H4>st_netfd_fileno()</H4>
</A>
Returns an underlying OS file descriptor.
<P>
<H5>Syntax</H5>

<PRE>
#include &lt;st.h&gt;

int st_netfd_fileno(st_netfd_t fd);
</PRE>
<P>
<H5>Parameters</H5>
<TT>st_netfd_fileno()</TT> has the following parameters:<P>
<TT>fd</TT><P>
A file descriptor object identifier (see
<A HREF=#netfd_t><B>st_netfd_t</B></A>).
<P>
<H5>Returns</H5>
An underlying OS file descriptor.
<P>
<H5>Description</H5>
This function returns the integer OS file descriptor associated with the named
file descriptor object.
<P>
<HR>
<P>
<A NAME="netfd_setspecific">
<H4>st_netfd_setspecific()</H4>
</A>
Sets per-descriptor private data.
<P>
<H5>Syntax</H5>

<PRE>
#include &lt;st.h&gt;

void st_netfd_setspecific(st_netfd_t fd, void *value,
                          void (*destructor)(void *));
</PRE>
<P>
<H5>Parameters</H5>
<TT>st_netfd_setspecific()</TT> has the following parameters:<P>
<TT>fd</TT><P>
A valid file descriptor object identifier (see
<A HREF=#netfd_t><B>st_netfd_t</B></A>).
<P>
<TT>value</TT><P>
The per-descriptor private data, or more likely, a pointer to the data which
is being associated with the named file descriptor object.
<P>
<TT>destructor</TT><P>
Specifies an optional destructor function for the private data associated
with <TT>fd</TT>. This function can be specified as <TT>NULL</TT>.
If <TT>value</TT> is not <TT>NULL</TT>, then this destructor function will
be called with <TT>value</TT> as an argument upon freeing the file descriptor
object (see <A HREF=#netfd_free>st_netfd_free()</A> and
<A HREF=#netfd_close>st_netfd_close()</A>).
<P>
<H5>Returns</H5>
Nothing.
<P>
<H5>Description</H5>
This function allows to associate any data with the specified file
descriptor object (network connection). If a non-<TT>NULL</TT> destructor
function is registered, it will be called at one of two times, as long as
the associated data is not <TT>NULL</TT>:
<UL>
<LI>when private data is replaced by calling
<TT>st_netfd_setspecific()</TT> again
<LI>upon freeing the file descriptor object (see
<A HREF=#netfd_free>st_netfd_free()</A> and
<A HREF=#netfd_close>st_netfd_close()</A>)
</UL>
<P>
<HR>
<P>
<A NAME="netfd_getspecific">
<H4>st_netfd_getspecific()</H4>
</A>
Retrieves the per-descriptor private data.
<P>
<H5>Syntax</H5>

<PRE>
#include &lt;st.h&gt;

void *st_netfd_getspecific(st_netfd_t fd);
</PRE>
<P>
<H5>Parameters</H5>
<TT>st_netfd_getspecific()</TT> has the following parameters:<P>
<TT>fd</TT><P>
A valid file descriptor object identifier (see
<A HREF=#netfd_t><B>st_netfd_t</B></A>).
<P>
<H5>Returns</H5>
The data associated with the named file descriptor object. If no data is
associated with <TT>fd</TT>, then <TT>NULL</TT> is returned. 
<P>
<H5>Description</H5>
This function allows to retrieve the data that was associated with the
specified file descriptor object (see
<A HREF=#netfd_setspecific>st_netfd_setspecific()</A>).
<P>
<HR>
<P>
<A NAME="netfd_serialize_accept">
<H4>st_netfd_serialize_accept()</H4>
</A>
Serializes all subsequent <TT>accept(3)</TT> calls on a specified file
descriptor object.
<P>
<H5>Syntax</H5>

<PRE>
#include &lt;st.h&gt;

int st_netfd_serialize_accept(st_netfd_t fd);
</PRE>
<P>
<H5>Parameters</H5>
<TT>st_netfd_serialize_accept()</TT> has the following parameters:<P>
<TT>fd</TT><P>
A file descriptor object identifier (see
<A HREF=#netfd_t><B>st_netfd_t</B></A>) which has been successfully created
from a valid listening socket by <A HREF=#netfd_open>st_netfd_open()</A> or
<A HREF=#netfd_open_socket>st_netfd_open_socket()</A>.
<P>
<H5>Returns</H5>
Upon successful completion, a value of <TT>0</TT> is returned.
Otherwise, a value of <TT>-1</TT> is returned and <TT>errno</TT> is set
to indicate the error.
<P>
<H5>Description</H5>
On some platforms (e.g., Solaris 2.5 and possibly other SVR4 implementations)
<TT>accept(3)</TT> calls from different processes on
the same listening socket (see <TT>bind(3)</TT>, <TT>listen(3)</TT>) must be
serialized. This function causes all subsequent <TT>accept(3)</TT> calls
made by <A HREF=#accept>st_accept()</A> on the specified file descriptor
object to be serialized.
<P>
<TT>st_netfd_serialize_accept()</TT> must be called <I>before</I>
creating multiple server processes via <TT>fork(2)</TT>. If the application
does not create multiple processes to accept network connections on
the same listening socket, there is no need to call this function.
<P>
Deciding whether or not to serialize accepts is tricky.  On some
platforms (IRIX, Linux) it's not needed at all and
<TT>st_netfd_serialize_accept()</TT> is a no-op.  On other platforms
it depends on the version of the OS (Solaris 2.6 doesn't need it but
earlier versions do).  Serializing accepts does incur a slight
performance penalty so you want to enable it only if necessary.  Read
your system's manual pages for <tt>accept(2)</tt> and <tt>select(2)</tt>
to see if accept serialization is necessary on your system.
<P>
<TT>st_netfd_serialize_accept()</TT> allocates resources that are
freed upon freeing of the specified file descriptor object (see
<A HREF=#netfd_free>st_netfd_free()</A> and
<A HREF=#netfd_close>st_netfd_close()</A>).
<P>
<HR>
<P>
<A NAME="netfd_poll">
<H4>st_netfd_poll()</H4>
</A>
Waits for I/O on a single file descriptor object.
<P>
<H5>Syntax</H5>

<PRE>
#include &lt;st.h&gt;

int st_netfd_poll(st_netfd_t fd, int how, st_utime_t timeout);
</PRE>
<P>
<H5>Parameters</H5>
<TT>st_netfd_poll()</TT> has the following parameters:<P>
<TT>fd</TT><P>
A file descriptor object identifier (see
<A HREF=#netfd_t><B>st_netfd_t</B></A>).
<P>
<TT>how</TT><P>
Specifies I/O events of interest. This parameter can be constructed by
OR-ing any combination of the following event flags which are defined
in the <TT>poll.h</TT> header file:<P>
<TABLE BORDER=0>
<TR><TD><TT>POLLIN</TT></TD><TD><TT>fd</TT> is readable.</TD></TR>
<TR><TD><TT>POLLOUT</TT></TD><TD><TT>fd</TT> is is writable.</TD></TR>
<TR><TD><TT>POLLPRI</TT></TD><TD><TT>fd</TT> has an exception condition.</TD>
</TR>
</TABLE>
<P>
<TT>timeout</TT><P>
Amount of time in microseconds the call will block waiting for I/O
to become ready. This parameter is a variable of type
<A HREF=#utime_t><B>st_utime_t</B></A>. If this time expires without any
I/O becoming ready, <TT>st_netfd_poll()</TT> returns an error and sets
<TT>errno</TT> to <TT>ETIME</TT>.
Note that timeouts are measured <A HREF="notes.html#timeouts">since the
last context switch</A>.
<P>
<H5>Returns</H5>
If the named file descriptor object is ready for I/O within the specified
amount of time, a value of <TT>0</TT> is returned. Otherwise, a value
of <TT>-1</TT> is returned and <TT>errno</TT> is set to indicate the error:
<P>
<TABLE BORDER=0>
<TR><TD><TT>EBADF</TT></TD><TD>The underlying OS file descriptor is invalid.
</TD></TR>
<TR><TD><TT>EINTR</TT></TD><TD>The current thread was interrupted by
<A HREF=#thread_interrupt>st_thread_interrupt()</A>.</TD></TR>
<TR><TD><TT>ETIME</TT></TD><TD>The timeout occurred without any I/O
becoming ready.</TD></TR>
</TABLE>
<P>
<H5>Description</H5>
This function returns as soon as I/O is ready on the named file
descriptor object or the specified amount of time expires. The
<TT>how</TT> parameter should be set to the I/O events (readable,
writable, exception, or some combination) that the caller is interested
in. If the value of <TT>timeout</TT> is <tt>ST_UTIME_NO_TIMEOUT</tt>
(<TT>-1</TT>), this function blocks until a requested I/O event occurs
or until the call is interrupted by <A
HREF=#thread_interrupt>st_thread_interrupt()</A>.<p>
Despite having an interface like <tt>poll(2)</tt>, this function uses
the same event notification mechanism as the rest of the library.  For
instance if an alternative event nofication mechanism was set using <a
href=#set_eventsys>st_set_eventsys()</a>, this function uses that
mechanism to check for events.<p>
<b>Note: </b> if <TT>kqueue(2)</TT> is used as an alternative event
notification mechanism (see <A
HREF=#set_eventsys>st_set_eventsys()</A>), the <TT>POLLPRI</TT>
event flag is not supported and <TT>st_netfd_poll()</TT> will return an error
if it's set (<TT>errno</TT> will be set to <TT>EINVAL</TT>).
<P>
<HR>
<P>
<A NAME="accept">
<H4>st_accept()</H4>
</A>
Accepts a connection on a specified file descriptor object.
<P>
<H5>Syntax</H5>

<PRE>
#include &lt;st.h&gt;

st_netfd_t st_accept(st_netfd_t fd, struct sockaddr *addr, int *addrlen,
                     st_utime_t timeout);
</PRE>
<P>
<H5>Parameters</H5>
<TT>st_accept()</TT> has the following parameters:<P>
<TT>fd</TT><P>
A file descriptor object identifier (see
<A HREF=#netfd_t><B>st_netfd_t</B></A>) representing the rendezvous socket
on which the caller is willing to accept new connections. This object has been
created from a valid listening socket by
<A HREF=#netfd_open>st_netfd_open()</A> or
<A HREF=#netfd_open_socket>st_netfd_open_socket()</A>.<P>
<TT>addr</TT><P>
If this value is non-zero, it is a result parameter that is filled
in with the address of the connecting entity, as known to the communications
layer (see <TT>accept(3)</TT>).<P>
<TT>addrlen</TT><P>
This parameter should initially contain the amount of space pointed to by
<TT>addr</TT>; on return it will contain the actual length (in bytes) of the
address returned (see <TT>accept(3)</TT>).<P>
<TT>timeout</TT><P>
A value of type <A HREF=#utime_t><B>st_utime_t</B></A> specifying the time
limit in microseconds for completion of the accept operation.
Note that timeouts are measured <A HREF="notes.html#timeouts">since the
last context switch</A>.
<P>
<H5>Returns</H5>
Upon successful completion, a new file descriptor object identifier
representing the newly accepted connection is returned. Otherwise,
<TT>NULL</TT> is returned and <TT>errno</TT> is set to indicate the error.
Possible <TT>errno</TT> values are the same as set by the <TT>accept(3)</TT>
call with two exceptions:<P>
<TABLE BORDER=0>
<TR><TD><TT>EINTR</TT></TD><TD>The current thread was interrupted by
<A HREF=#thread_interrupt>st_thread_interrupt()</A>.</TD></TR>
<TR><TD><TT>ETIME</TT></TD><TD>The timeout occurred and no pending
connection was accepted.</TD></TR>
</TABLE>
<P>
<H5>Description</H5>
This function accepts the first connection from the queue of pending
connections and creates a new file descriptor object for the newly
accepted connection. The rendezvous socket can still be used to accept
more connections.<P>
<TT>st_accept()</TT> blocks the calling thread until either a new connection
is successfully accepted or an error occurs. If no pending connection can
be accepted before the time limit, this function returns <TT>NULL</TT>
and sets <TT>errno</TT> to <TT>ETIME</TT>.
<P>
<HR>
<P>
<A NAME="connect">
<H4>st_connect()</H4>
</A>
Initiates a connection on a specified file descriptor object.
<P>
<H5>Syntax</H5>

<PRE>
#include &lt;st.h&gt;

int st_connect(st_netfd_t fd, struct sockaddr *addr, int addrlen,
               st_utime_t timeout);
</PRE>
<P>
<H5>Parameters</H5>
<TT>st_connect()</TT> has the following parameters:<P>
<TT>fd</TT><P>
A file descriptor object identifier (see
<A HREF=#netfd_t><B>st_netfd_t</B></A>) representing a socket.<P>
<TT>addr</TT><P>
A pointer to