/** @file  ../include/sys/socket.h

@internalComponent

*/

/** @fn  accept(int s, struct sockaddr *  addr, socklen_t *  addrlen)

@param s

@param addr

@param addrlen

  The argument s is a socket that has been created with socket, bound to an address with bind and is listening for connections after a listen . The accept system call extracts the first connection request on the queue 

of pending connections and creates a new socket which it allocates a new file 

descriptor. The new socket inherits the state of the O_NONBLOCK property from the original socket s.

 If no pending connections are present on the queue, and the original socket 

  is not marked as non-blocking, accept blocks the caller until a connection is present. If the original 

  socket is marked non-blocking and no pending connections are present on the 

  queue, accept returns an error as described below.

 The accepted socket may not be used to accept more connections. The original 

  socket s remains open.

 The argument addr is a result argument that is filled-in with the address of the 

  connecting entity as it is known to the communications layer. The exact format 

  of the addr argument is determined by the domain in which the communication 

  is occurring. A null pointer may be specified for addr if the address information is not required. In this case addrlen is not used and should also be null. Otherwise, the addrlen argument is a value-result argument: It should initially contain 

  the amount of space pointed to by addr and on return will contain the actual length (in bytes) of the 

  address returned. This call is used with connection-based socket types, currently 

  with SOCK_STREAM.

 It is possible to select a socket for the purposes of doing an accept by selecting it for read.

 For certain protocols, such as ISO or DATAKIT which require an explicit confirmation, accept can be thought of as merely dequeueing the next connection 

  request and not implying confirmation. Confirmation can be implied by a normal 

  read or write on the new file descriptor, and rejection can be implied by closing 

  the new socket.

Examples:

@code

#include <sys/socket.h>

#include <netinet/in.h>

#include <unistd.h>

void GetSockName()

{

   int sock_fd;

   int newsock_fd;

   struct sockaddr_in addr;

   struct sockaddr_in ss;

   struct sockaddr_in new_socket;

   unsigned int len;

   unsigned int addr_len;

   sock_fd = socket(AF_INET, SOCK_STREAM, IPPROTO_TCP);

   addr.sin_family = AF_INET;

   addr.sin_addr.s_addr = htonl(INADDR_ANY);

   addr.sin_port = htons(5000);

   bind(sock_fd,(sockaddr*)&addr;,sizeof(addr));

   listen(sock_fd,1);

   newsock_fd = accept(sock_fd,(sockaddr*)&new;_socket,&addr;_len); // Code blocks here

   if (newsock_fd <= 0)

   {

                perror("accept:");

   }

   close(newsock_fd);

   close(sock_fd);

}

@endcode

@return   The call returns -1 on error.

If it succeeds, it returns a non-negative

integer that is a descriptor for the accepted socket.

@see bind()

@see connect()

@see getpeername()

@see listen()

@see select()

@see socket()

@capability Deferred @ref RSocket::Open(RSocketServ &,TUint,TUint,TUint)

@publishedAll

@externallyDefinedApi

*/

/** @fn  bind(int s, const struct sockaddr *addr, socklen_t addrlen)

@param s

@param addr

@param addrlen

  The bind system call

assigns the local protocol address to a socket.

When a socket is created

with socket it exists in an address family space but has no protocol address assigned.

The bind system call requests that addr be assigned to the socket.

Examples:

@code

#include <sys/socket.h>

#include <netinet/in.h>

#include <unistd.h>

TInt GetSockName()

{

   int sock_fd;

   struct sockaddr_in addr,ss;

   unsigned int len;   

   sock_fd = socket(AF_INET, SOCK_STREAM, IPPROTO_TCP);

   addr.sin_family = AF_INET;

   addr.sin_addr.s_addr = htonl(INADDR_ANY);

   addr.sin_port = htons(5000);

   bind(sock_fd,(struct sockaddr*)&addr;,sizeof(addr));

   close(sock_fd);

}

@endcode

Notes:

 For maximum portability always initialise the socket address structure to 

  zero before populating it and passing it to bind.

@return   The bind() function returns the value 0 if successful; otherwise the

value -1 is returned and the global variable errno is set to indicate the

error.

@see connect()

@see getsockname()

@see listen()

@see socket()

@publishedAll

@externallyDefinedApi

*/

/** @fn  connect(int s, const struct sockaddr *name, socklen_t namelen)

@param s

@param name

@param namelen

 The s argument is a socket. If it is of type SOCK_DGRAM name specifies the peer with which the socket is to be associated. It 

  specifiies the address to which datagrams are to be sent and the only address 

  from which datagrams are to be received.

 If the socket is of type SOCK_STREAM, this call attempts to make a connection to another socket. 

  The other socket is specified by name, which is an address in the communications space of the socket. 

  Each communications space interprets the name argument in its own way.

 Generally, stream sockets may successfully connect only once and datagram sockets may use connect multiple times to change their association. Datagram sockets 

  may dissolve the association by connecting to an invalid address, such as a 

  null address.

Examples:

@code

#include <sys/socket.h>

#include <netinet/in.h>

#include <unistd.h>

void Connect()

{

   struct sockaddr_in serv_addr;

   int sock_fd;

   serv_addr.sin_family = AF_INET;

   serv_addr.sin_addr.s_addr = htonl(INADDR_LOOPBACK);

   serv_addr.sin_port = htons(5000);

   sock_fd = socket(AF_INET,SOCK_STREAM,IPPROTO_TCP);

   connect(sock_fd,(struct sockaddr*)&serv;_addr,sizeof(serv_addr));

   close(sock_fd);

}

@endcode

@return   The connect() function returns the value 0 if successful; otherwise it returns 

the value -1 and the sets global variable errno to indicate the error.

@see accept()

@see getpeername()

@see getsockname()

@see select()

@see socket()

@capability Deferred @ref RSocket::Open(RSocketServ &,TUint,TUint,TUint)

@publishedAll

@externallyDefinedApi

*/

/** @fn  getpeername(int s, struct sockaddr *  name, socklen_t *  namelen)

@param s

@param name

@param namelen

@return   The getpeername() function returns the value 0 if successful; otherwise

the value -1 is returned and the global variable errno is set to indicate

the error.

  The getpeername system call

returns the name of the peer connected to

socket s. The namelen argument should be initialized to indicate

the amount of space pointed to by name. On return it contains the actual size of the name

returned (in bytes).

The name is truncated if the buffer provided is too small.

Examples:

@code

#include <sys/socket.h>

#include <netinet/in.h>

#include <unistd.h>

void GetSockName()

{

   int sock_fd;

   int newsock_fd;

   struct sockaddr_in addr;

   struct sockaddr_in ss;

   struct sockaddr_in new_socket;

   unsigned int len;

   unsigned int addr_len;

   sock_fd = socket(AF_INET, SOCK_STREAM, IPPROTO_TCP);

   addr.sin_family = AF_INET;

   addr.sin_addr.s_addr = htonl(INADDR_ANY);

   addr.sin_port = htons(5000);

   bind(sock_fd,(struct sockaddr*)&addr;,sizeof(addr));

   listen(sock_fd,1);

   newsock_fd = accept(sock_fd,(struct sockaddr*)&new;_socket,&addr;_len); // Code blocks here

   // Assuming client has connected to the server. 

   len = sizeof(ss);

   getpeername(sock_fd,(struct sockaddr*)&ss;,&len;);

   close(newsock_fd);

   close(sock_fd);

 }

@endcode

@see accept()

@see bind()

@see getsockname()

@see socket()

@publishedAll

@externallyDefinedApi

*/

/** @fn  getsockname(int s, struct sockaddr *  name, socklen_t *  namelen)

@param s

@param name

@param namelen

@return   The getsockname() function returns the value 0 if successful; otherwise

the value -1 is returned and the global variable errno is set to indicate

the error.

  The getsockname system call

returns the current name for the specified socket.

The namelen argument should be initialized to indicate

the amount of space pointed to by name. On return it contains the actual size of the name

returned (in bytes).

Examples:

@code

#include <sys/socket.h>

#include <netinet/in.h>

#include <unistd.h>

TInt GetSockName()

{

   int sock_fd;

   struct sockaddr_in addr,ss;

   unsigned int len;   

   sock_fd = socket(AF_INET, SOCK_STREAM, IPPROTO_TCP);

   addr.sin_family = AF_INET;

   addr.sin_addr.s_addr = htonl(INADDR_ANY);

   addr.sin_port = htons(5000);

   bind(sock_fd,(struct sockaddr*)&addr;,sizeof(addr));

  len=sizeof(ss);

  getsockname(sock_fd,(struct sockaddr*)&ss;,&len;);

  close(sock_fd);

}

@endcode

@see bind()

@see getpeername()

@see socket()

@publishedAll

@externallyDefinedApi

*/

/** @fn  getsockopt(int s, int level, int optname, void *  optval, socklen_t *  optlen)

@param s

@param level

@param optname

@param optval

@param optlen

Note: This description also covers the following functions -

 setsockopt() 

@return   Upon successful completion, the value 0 is returned; otherwise the

value -1 is returned and the global variable errno is set to indicate the

error.

The getsockopt and setsockopt system calls manipulate the options associated with a socket. Options may exist at multiple protocol levels; they are always present at the uppermost "socket" level. 

When manipulating socket options the level at which the option resides and the name of the option must be specified. To manipulate options at the socket level, level is specified as SOL_SOCKET. To manipulate options at any other level the protocol number of the appropriate protocol controlling the option is supplied. For example, to indicate that an option is to be interpreted by the TCP protocol, level should be set to the protocol number of TCP; 

The optval and optlen arguments are used to access option values for setsockopt. For getsockopt they identify a buffer in which the value for the requested option(s) are to be returned. For getsockopt, optlen is a value-result argument, initially containing the size of the buffer pointed to by optval, and modified on return to indicate the actual size of the value returned. If no option value is to be supplied or returned, optval may be NULL. 

The optname argument and any specified options are passed uninterpreted to the appropriate protocol module for interpretation. The include file   \#include \<sys/socket.h\>contains definitions for socket level options, described below. Options at other protocol levels vary in format and name; consult the appropriate entries in section 4 of the manual. 

Most socket-level options utilize an int argument for optval. For setsockopt, the argument should be non-zero to enable a boolean option, or zero if the option is to be disabled. SO_LINGER uses a struct linger argument, defined in 

 @code

  #include <sys/socket.h,> which specifies the desired state of the option and the linger interval (see below). SO_SNDTIMEO and SO_RCVTIMEO use a struct timeval argument, defined in  

  #include <sys/time.h.> 

The following options are recognized at the socket level. Except as noted, each may be examined with getsockopt and set with setsockopt. SO_DEBUG            enables recording of debugging information 

SO_REUSEADDR       Allows a socket to be bound to an local address that is already in use. 

SO_REUSEPORT       enables duplicate address and port bindings 

SO_KEEPALIVE       enables keep connections alive 

SO_DONTROUTE       enables routing bypass for outgoing messages 

SO_BROADCAST       enables permission to transmit broadcast messages (enable only)

SO_OOBINLINE       enables reception of out-of-band data in band 

SO_SNDBUF          set buffer size for output 

SO_RCVBUF          set buffer size for input 

SO_SNDLOWAT        set minimum count for output 

SO_RCVLOWAT        set minimum count for input 

SO_SNDTIMEO        set timeout value for output 

SO_RCVTIMEO        set timeout value for input 

SO_ACCEPTFILTER            set accept filter on listening socket 

SO_TYPE            get the type of the socket (get only) 

SO_ERROR           get and clear error on the socket (get only)  

@endcode

SO_DEBUG enables debugging in the underlying protocol modules. SO_REUSEADDR indicates that the rules used in validating addresses supplied in a bind system call should allow reuse of local addresses. SO_REUSEPORT allows completely duplicate bindings by multiple processes if they all set SO_REUSEPORT before binding the port. This option permits multiple instances of a program to each receive UDP/IP multicast or broadcast datagrams destined for the bound port. SO_KEEPALIVE enables the periodic transmission of messages on a connected socket. SO_DONTROUTE indicates that outgoing messages should bypass the standard routing facilities. Instead, messages are directed to the appropriate network interface according to the network portion of the destination address. 

The option SO_BROADCAST requests permission to send broadcast datagrams on the socket. Broadcast was a privileged operation in earlier versions of the system. With protocols that support out-of-band data, the SO_OOBINLINE option requests that out-of-band data be placed in the normal data input queue as received; it will then be accessible with recv or read calls without the MSG_OOB flag. Some protocols always behave as if this option is set. SO_SNDBUF and SO_RCVBUF are options to adjust the normal buffer sizes allocated for output and input buffers, respectively. The buffer size may be increased for high-volume connections, or may be decreased to limit the possible backlog of incoming data. The system places an absolute maximum on these values, which is accessible through the sysctl MIB variable "kern.ipc.maxsockbuf." 

SO_SNDLOWAT is an option to set the minimum count for output operations. Most output operations process all of the data supplied by the call, delivering data to the protocol for transmission and blocking as necessary for flow control. Nonblocking output operations will process as much data as permitted subject to flow control without blocking, but will process no data if flow control does not allow the smaller of the low water mark value or the entire request to be processed. A select operation testing the ability to write to a socket will return true only if the low water mark amount could be processed. The default value for SO_SNDLOWAT is set to a convenient size for network efficiency, often 1024. SO_RCVLOWAT is an option to set the minimum count for input operations. In general, receive calls will block until any (non-zero) amount of data is received, then return with the smaller of the amount available or the amount requested. The default value for SO_RCVLOWAT is 1. If SO_RCVLOWAT is set to a larger value, blocking receive calls normally wait until they have received the smaller of the low water mark value or the requested amount. 

SO_SNDTIMEO is an option to set a timeout value for output operations. It accepts a struct timeval argument with the number of seconds and microseconds used to limit waits for output operations to complete. If a send operation has blocked for this much time, it returns with a partial count or with the error EWOULDBLOCK if no data were sent. In the current implementation, this timer is restarted each time additional data are delivered to the protocol, implying that the limit applies to output portions ranging in size from the low water mark to the high water mark for output. SO_RCVTIMEO is an option to set a timeout value for input operations. It accepts a struct timeval argument with the number of seconds and microseconds used to limit waits for input operations to complete. In the current implementation, this timer is restarted each time additional data are received by the protocol, and thus the limit is in effect an inactivity timer. If a receive operation has been blocked for this much time without receiving additional data, it returns with a short count or with the error EWOULDBLOCK if no data were received. 

SO_ACCEPTFILTER places an accept_filter on the socket, which will filter incoming connections on a listening stream socket before being presented for accept. Once more, listen must be called on the socket before trying to install the filter on it, or else the setsockopt system call will fail. 

SO_LINGER option is not supported by this api.

@code

struct  accept_filter_arg {

        char    af_name[16];

        char    af_arg[256-16];

};

@endcode

The optval argument should point to a struct accept_filter_arg that will select and configure the accept_filter. The af_name argument should be filled with the name of the accept filter that the application wishes to place on the listening socket. The optional argument af_arg can be passed to the accept filter specified by af_name to provide additional configuration options at attach time. Passing in an optval of NULL will remove the filter. 

Finally, SO_TYPE and SO_ERROR are options used only with getsockopt. SO_TYPE returns the type of the socket, such as SOCK_STREAM; it is useful for servers that inherit sockets on startup. SO_ERROR returns any pending error on the socket and clears the error status. It may be used to check for asynchronous errors on connected datagram sockets or for other asynchronous errors. 

Examples:

@code

#include <sys/socket.h>

#include <netinet/in.h>

#include <unistd.h>

void SocketOptions()

{

   int sock_fd;

   int optval = 1;

   unsigned int optlen = sizeof(optval);

   int rdoptval;

   sock_fd = socket(AF_INET, SOCK_STREAM, IPPROTO_TCP);

   setsockopt(sock_fd,SOL_SOCKET,SO_KEEPALIVE,&optval;,optlen);

   getsockopt(sock_fd,SOL_SOCKET,SO_KEEPALIVE,(void*)&rdoptval;,&optlen;);

close(sock_fd);

}

@endcode

@see ioctl()

@see socket()

@publishedAll

@externallyDefinedApi

*/

/** @fn  listen(int fd, int n)

@param fd

@param n

@return   The listen() function returns the value 0 if successful; otherwise the

value -1 is returned and the global variable errno is set to indicate the

error.

  To accept connections a socket is first created with socket . A willingness to accept incoming connections 

and a queue limit for incoming connections are specified with listen and then the connections are accepted with accept . The listen system call applies only to sockets of type SOCK_STREAM or SOCK_SEQPACKET.

 The n argument defines the maximum length the queue of pending connections 

  may grow to. The real maximum queue length will be 1.5 times more than the value 

  specified in the n argument. A subsequent listen system call on the listening socket allows the caller to change 

  the maximum queue length using a new n argument. If a connection request arrives with the queue full 

  the client may receive an error with an indication of ECONNREFUSED , or, in the case of TCP, the connection will be silently 

  dropped.

 Note that before BSD 4.5 and the introduction of the syncache the n argument also determined the length of the incomplete connection 

  queue, which held TCP sockets in the process of completing TCP's 3-way 

  handshake. These incomplete connections are now held entirely in the syncache, 

  which is unaffected by queue lengths. Inflated n values to help handle denial of service attacks are no longer 

  necessary.

Examples:

@code

#include <sys/socket.h>

#include <netinet/in.h>

#include <unistd.h>

void listen_example()

{

   int sock_fd;

   int newsock_fd;

   struct sockaddr_in addr;

   struct sockaddr_in ss;

   struct sockaddr_in new_socket;

   unsigned int len;

   unsigned int addr_len;

   sock_fd = socket(AF_INET, SOCK_STREAM, IPPROTO_TCP);

   addr.sin_family = AF_INET;

   addr.sin_addr.s_addr = htonl(INADDR_ANY);

   addr.sin_port = htons(5000);

   bind(sock_fd,(struct sockaddr*)&addr;,sizeof(addr));

   listen(sock_fd,1);

   close(sock_fd);

}

@endcode

@see accept()

@see connect()

@see socket()

@publishedAll

@externallyDefinedApi

*/

/** @fn  recv(int fd, void *buf, size_t cnt, int flags)

@param fd

@param buf

@param cnt

@param flags

Note: This description also covers the following functions -

 recvfrom()  recvmsg() 

@return   These calls return the number of bytes received, or -1

if an error occurred.

@code

 MSG_OOB                process out-of-band data

@endcode

  The recvfrom and recvmsg system calls

are used to receive messages from a socket,

and may be used to receive data on a socket whether or not

it is connection-oriented.

 If from is not a null pointer

and the socket is not connection-oriented,

the source address of the message is filled in.

The fromlen argument

is a value-result argument, initialized to the size of

the buffer associated with from, and modified on return to indicate the actual size of the

address stored there.

 The recv function is normally used only on a connected socket (see connect )

and is identical to recvfrom with a

null pointer passed as its from argument.

As it is redundant, it may not be supported in future releases.

 All three routines return the length of the message on successful

completion.

If a message is too long to fit in the supplied buffer,

excess bytes may be discarded depending on the type of socket

the message is received from (see socket )

 If no messages are available at the socket, the

receive call waits for a message to arrive, unless

the socket is nonblocking (see fcntl )

in which case the value

-1 is returned and the external variable errno set to EAGAIN. The receive calls normally return any data available,

up to the requested amount,

rather than waiting for receipt of the full amount requested;

this behavior is affected by the socket-level options SO_RCVLOWAT and SO_RCVTIMEO described in getsockopt .

 The select system call may be used to determine when more data arrive.

 The flags argument to a recv function is formed by or Ap ing one or more of the values: MSG_OOB                process out-of-band data MSG_PEEK                peek at incoming message MSG_WAITALL                wait for full request or error MSG_DONTWAIT                do not block 

 The MSG_OOB flag requests receipt of out-of-band data

that would not be received in the normal data stream.

Some protocols place expedited data at the head of the normal

data queue, and thus this flag cannot be used with such protocols.

The MSG_PEEK flag causes the receive operation to return data

from the beginning of the receive queue without removing that

data from the queue.

Thus, a subsequent receive call will return the same data.