Seth Woolley's Man Viewer

Manual for accept - man 2 accept

([section] manual, -k keyword, -K [section] search, -f whatis)
man plain no title

ACCEPT(2)                  Linux Programmer's Manual                 ACCEPT(2)



NAME
       accept(2,8) - accept(2,8) a connection on a socket(2,7,n)

SYNOPSIS
       #include <sys/types.h>
       #include <sys/socket.h>

       int accept(2,8)(int s, struct sockaddr *addr, socklen_t *addrlen);

DESCRIPTION
       The   accept(2,8)  function  is  used  with  connection-based  socket(2,7,n)  types
       (SOCK_STREAM, SOCK_SEQPACKET and SOCK_RDM).  It extracts the first con-
       nection request on the queue(1,3) of pending connections, creates a new con-
       nected socket(2,7,n) with mostly the same properties as s, and allocates a new
       file(1,n)  descriptor  for the socket(2,7,n), which is returned.  The newly created
       socket(2,7,n) is no longer in(1,8) the listening state.  The original socket(2,7,n)  s  is
       unaffected  by  this  call.  Note  that  any  per file(1,n) descriptor flags
       (everything that can be set(7,n,1 builtins) with the F_SETFL fcntl, like  non  blocking
       or async state) are not inherited across an accept(2,8).

       The  argument s is a socket(2,7,n) that has been created with socket(2,7,n)(2), bound
       to a local address with bind(2,n,1 builtins)(2), and is listening for connections after
       a listen(1,2,7)(2).

       The  argument addr is a pointer to a sockaddr structure. This structure
       is filled in(1,8) with the address of the connecting entity, as known to the
       communications  layer.   The  exact format of the address passed in(1,8) the
       addr parameter is determined by the socket(2,7,n)'s family (see socket(2,7,n)(2)  and
       the  respective  protocol man(1,5,7) pages).  The addrlen argument is a value-
       result parameter: it should initially contain the size of the structure
       pointed  to  by  addr;  on return it will contain the actual length (in(1,8)
       bytes) of the address returned. When addr is NULL nothing is filled in.

       If  no  pending connections are present on the queue(1,3), and the socket(2,7,n) is
       not marked as non-blocking, accept(2,8) blocks the caller until a connection
       is  present.   If the socket(2,7,n) is marked non-blocking and no pending con-
       nections are present on the queue(1,3), accept(2,8) returns EAGAIN.

       In order to be notified of incoming connections on a  socket(2,7,n),  you  can
       use  select(2,7,2 select_tut)(2)  or  poll(2).  A readable event will be delivered when a
       new connection is attempted and you may  then  call  accept(2,8)  to  get  a
       socket(2,7,n)  for  that connection.  Alternatively, you can set(7,n,1 builtins) the socket(2,7,n) to
       deliver SIGIO when activity occurs  on  a  socket(2,7,n);  see  socket(2,7,n)(7)  for
       details.

       For  certain  protocols which require an explicit confirmation, such as
       DECNet, accept(2,8) can be thought of as merely dequeuing the  next  connec-
       tion  request  and  not  implying  confirmation.   Confirmation  can be
       implied by a normal read(2,n,1 builtins) or write(1,2)  on  the  new  file(1,n)  descriptor,  and
       rejection can be implied by closing the new socket. Currently only DEC-
       Net has these semantics on Linux.

NOTES
       There may not always be a connection waiting after a SIGIO is delivered
       or  select(2,7,2 select_tut)(2) or poll(2) return a readability event because the connec-
       tion might have been  removed  by  an  asynchronous  network  error(8,n)  or
       another  thread before accept(2,8) is called.  If this happens then the call
       will block waiting for the next connection to arrive.  To  ensure  that
       accept(2,8)  never  blocks, the passed socket(2,7,n) s needs to have the O_NONBLOCK
       flag set(7,n,1 builtins) (see socket(2,7,n)(7)).

RETURN VALUE
       The call returns -1 on error.  If it succeeds, it returns  a  non-nega-
       tive integer that is a descriptor for the accepted socket.

ERROR HANDLING
       Linux accept(2,8) passes already-pending network errors on the new socket(2,7,n) as
       an error(8,n) code from accept(2,8).   This  behaviour  differs  from  other  BSD
       socket(2,7,n)  implementations.  For reliable operation the application should
       detect the network errors defined for the  protocol  after  accept(2,8)  and
       treat  them  like EAGAIN by retrying. In case of TCP/IP these are ENET-
       DOWN, EPROTO, ENOPROTOOPT, EHOSTDOWN, ENONET, EHOSTUNREACH, EOPNOTSUPP,
       and ENETUNREACH.

ERRORS
       accept(2,8) shall fail if:

       EAGAIN or EWOULDBLOCK
              The socket(2,7,n) is marked non-blocking and no connections are present
              to be accepted.

       EBADF  The descriptor is invalid.

       ECONNABORTED
              A connection has been aborted.

       EINTR  The system call was interrupted by  a  signal(2,7)  that  was  caught
              before a valid connection arrived.

       EINVAL Socket is not listening for connections.

       EMFILE The per-process limit of open(2,3,n) file(1,n) descriptors has been reached.

       ENFILE The system limit on the total number  of  open(2,3,n)  files  has  been
              reached.

       ENOTSOCK
              The descriptor references a file(1,n), not a socket.

       EOPNOTSUPP
              The referenced socket(2,7,n) is not of type SOCK_STREAM.

       accept(2,8) may fail if:

       EFAULT The addr parameter is not in(1,8) a writable part of the user address
              space.

       ENOBUFS, ENOMEM
              Not enough free memory.  This often means that the memory  allo-
              cation is limited by the socket(2,7,n) buffer limits, not by the system
              memory.

       EPROTO Protocol error.

       Linux accept(2,8) may fail if:

       EPERM  Firewall rules forbid connection.

       In addition, network errors for the new socket(2,7,n) and as defined  for  the
       protocol may be returned. Various Linux kernels can return other errors
       such as ENOSR, ESOCKTNOSUPPORT, EPROTONOSUPPORT, ETIMEDOUT.  The  value
       ERESTARTSYS may be seen during a trace.

CONFORMING TO
       SVr4,  4.4BSD (the accept(2,8) function first appeared in(1,8) BSD 4.2).  The BSD
       man(1,5,7) page documents five possible error(8,n) returns (EBADF,  ENOTSOCK,  EOP-
       NOTSUPP,  EWOULDBLOCK,  EFAULT).  SUSv3 documents errors EAGAIN, EBADF,
       ECONNABORTED, EINTR, EINVAL, EMFILE, ENFILE, ENOBUFS, ENOMEM, ENOTSOCK,
       EOPNOTSUPP,  EPROTO,  EWOULDBLOCK.  In addition, SUSv2 documents EFAULT
       and ENOSR.

       Linux accept(2,8) does _not_ inherit socket(2,7,n) flags like O_NONBLOCK.  This be-
       haviour  differs  from other BSD socket(2,7,n) implementations.  Portable pro-
       grams should not rely on this behaviour and  always  set(7,n,1 builtins)  all  required
       flags on the socket(2,7,n) returned from accept.

NOTE
       The third argument of accept(2,8) was originally declared as an `int *' (and
       is that under libc4 and libc5 and on many other systems like  BSD  4.*,
       SunOS  4, SGI); a POSIX 1003.1g draft standard wanted to change it into
       a `size_t *', and that is what it is for SunOS 5.  Later  POSIX  drafts
       have `socklen_t *', and so do the Single Unix Specification and glibc2.
       Quoting Linus Torvalds:

       "_Any_ sane library _must_ have "socklen_t" be the same  size  as  int.
       Anything else breaks any BSD socket(2,7,n) layer stuff.  POSIX initially _did_
       make it a size_t, and I (and hopefully others, but  obviously  not  too
       many)  complained  to  them  very loudly indeed.  Making it a size_t is
       completely broken, exactly because size_t very seldom is the same  size
       as  "int" on 64-bit architectures, for example.  And it _has_ to be the
       same size as "int" because that's what the  BSD  socket(2,7,n)  interface  is.
       Anyway,   the   POSIX   people  eventually  got  a  clue,  and  created
       "socklen_t".  They shouldn't have touched it in(1,8) the  first  place,  but
       once  they  did  they felt it had to have a named(5,8) type for some unfath-
       omable reason (probably somebody didn't like losing  face  over  having
       done  the  original  stupid  thing, so they silently just renamed their
       blunder)."


SEE ALSO
       bind(2,n,1 builtins)(2), connect(2), listen(1,2,7)(2), select(2,7,2 select_tut)(2), socket(2,7,n)(2)



Linux 2.6.7                       2004-06-17                         ACCEPT(2)

References for this manual (incoming links)