Subversion Repositories openrisc

NAME

       socket - create an endpoint for communication

SYNOPSIS

       #include <network.h>

       int socket(int domain, int type, int protocol);

DESCRIPTION

       Socket creates an endpoint for communication and returns a

       descriptor.

       The domain parameter  specifies  a  communications  domain

       within  which  communication will take place; this selects

       the protocol family which should be used.  These  families

       are  defined  in <sys/socket.h>.  The currently understood

       formats include:

       PF_INET

              IPv4 Internet protocols; see ip(4)

       The socket has the indicated  type,  which  specifies  the

       semantics of communication.  Currently defined types are:

       SOCK_STREAM

              Provides  sequenced,  reliable, two-way connection-

              based byte streams.  An out-of-band data  transmis-

              sion mechanism may be supported.

       SOCK_DGRAM

              Supports datagrams (connectionless, unreliable mes-

              sages of a fixed maximum length).

       SOCK_SEQPACKET

              Provides a sequenced, reliable, two-way connection-

              based data transmission path for datagrams of fixed

              maximum length; a consumer is required to  read  an

              entire packet with each read system call.

       SOCK_RAW

              Provides raw network protocol access.

       The  protocol  specifies  a particular protocol to be used

       with the socket.  Normally only a single  protocol  exists

       to  support a particular socket type within a given proto-

       col family.  However, it is possible that  many  protocols

       may  exist,  in  which  case a particular protocol must be

       specified in this manner.  The protocol number to  use  is

       particular to the "communication domain" in which communi-

       cation is to take place; see  protocols(5).   See  getpro-

       toent(3)  on  how to map protocol name strings to protocol

       numbers.

       Sockets of type SOCK_STREAM are full-duplex byte  streams,

       similar  to pipes.  A stream socket must be in a connected

       state before any data may be sent or received  on  it.   A

       connection  to another socket is created with a connect(2)

       call.  Once  connected,  data  may  be  transferred  using

       read(2)  and write(2) calls or some variant of the send(2)

       and recv(2) calls.  When a session has  been  completed  a

       close(2)  may  be performed.  Out-of-band data may also be

       transmitted  as  described  in  send(2)  and  received  as

       described in recv(2).

       The communications protocols which implement a SOCK_STREAM

       ensure that data is not lost or duplicated.  If a piece of

       data  for  which the peer protocol has buffer space cannot

       be successfully transmitted within a reasonable length  of

       time,  then the connection is considered When SO_KEEPALIVE

       is enabled on the socket the protocol checks in  a  proto-

       col-specific  manner  if  the other end is still alive.

       SOCK_DGRAM and SOCK_RAW sockets allow sending of datagrams

       to correspondents named in send(2) calls.   Datagrams  are

       generally  received  with  recvfrom(2),  which returns the

       next datagram with its return address.

       When  the network signals an error condition to the proto-

       col module (e.g.  using a ICMP message for IP) the pending

       error  flag  is set for the socket.  The next operation on

       this socket will return the  error  code  of  the  pending

       error.  For some protocols it is possible to enable a per-

       socket error queue to retrieve detailed information  about

       the error; see IP_RECVERR in ip(4).

       The  operation  of  sockets  is controlled by socket level

       options.  These options  are  defined  in  <sys/socket.h>.

       Setsockopt(2)  and  getsockopt(2)  are used to set and get

       options, respectively.

RETURN VALUES

       -1 is returned if an error occurs;  otherwise  the  return

       value is a descriptor referencing the socket.

ERRORS

       EPROTONOSUPPORT

               The protocol type or the specified protocol is not

               supported within this domain.

       EMFILE  There are too many open files.

       EACCES  Permission  to  create  a  socket of the specified

               type and/or protocol is denied.

       ENOBUFS or ENOMEM

               Insufficient memory is available.  The socket can-

               not  be  created  until  sufficient  resources are

               freed.

       EINVAL  Unknown protocol, or protocol  family  not  avail-

               able.