aacccceepptt() -- Sockets Function (libsocket)

Accept a connection on a socket
#iinncclluuddee <ssyyss/ttyyppeess.hh>
#iinncclluuddee <ssyyss/ssoocckkeett.hh>
iinntt aacccceepptt(_s_o_c_k_e_t, _a_d_d_r_e_s_s, _a_d_d_r_l_e_n)
iinntt _s_o_c_k_e_t, *_a_d_d_r_l_e_n; ssttrruucctt ssoocckkaaddddrr *_a_d_d_r_e_s_s;

aacccceepptt()  accepts  a  connection  on  a  socket.   It  extracts  the  first
connection  request on  the  queue of  pending connections,  creates a  new
socket with the same properties  as _s_o_c_k_e_t, and allocates a file descriptor
for the  newly created socket.   It is used with  connection-based types of
sockets, currently with SSOOCCKK_SSTTRREEAAMM.

_s_o_c_k_e_t gives a file descriptor that identifies a socket.  It must have been
returned by a call to ssoocckkeett(),  have been bound to an address by a call to
bbiinndd(), and be listening for connections after a call to lliisstteenn().

If no connections are pending on the queue and _s_o_c_k_e_t is not marked as non-
blocking,  aacccceepptt() blocks  the calling  process until  it can  establish a
connection.   If  _s_o_c_k_e_t  is marked  non-blocking  and  no connections  are
pending on  the queue, aacccceepptt() returns an error,  as described below.  The
accepted socket  may not be  used to accept more  connections; however, the
original _s_o_c_k_e_t remains open.

_a_d_d_r_e_s_s  gives  the address  of  the  connecting entity,  as  known to  the
``communications layer''.   Its exact format  is dictated by  the domain in
which communication occurs.

_a_d_d_r_l_e_n points  to an integer that  gives the number of  bytes available at
_a_d_d_r_e_s_s. Upon  return, that integer  contains the number of  bytes to which
_a_d_d_r_e_s_s actually points.

The  function sseelleecctt()  can  perform the  same action  as aacccceepptt():  simply
select the socket for reading.

If all  goes well,  aacccceepptt() returns the  file descriptor for  the accepted
socket, which is a non-negative integer.  If something goes wrong, aacccceepptt()
returns -1 and set eerrrrnnoo to  an appropriate value.  The following lists the
errors that can occur, by the value to which aacccceepptt() sets eerrrrnnoo:

EEBBAADDFF
     _s_o_c_k_e_t is somehow invalid.

EENNOOTTSSOOCCKK
     _s_o_c_k_e_t references a file, not a socket.

EEOOPPNNOOTTSSUUPPPP
     _s_o_c_k_e_t references a socket that is not of type SSOOCCKK_SSTTRREEAAMM.

EEFFAAUULLTT
     aaddddrr contains an illegal address.

EEWWOOUULLDDBBLLOOCCKK
     The socket  is marked non-blocking, and no  connections are present to
     be accepted.

_E_x_a_m_p_l_e
For an example of this function, see the Lexicon entry for lliibbssoocckkeett.

_S_e_e _A_l_s_o
bbiinndd(), ccoonnnneecctt(), lliibbssoocckkeett, lliisstteenn(), sseelleecctt()
