1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/ossrv/genericopenlibs/openenvcore/include/sys/socket.dosc Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,1618 @@
1.4 +/** @file ../include/sys/socket.h
1.5 +@internalComponent
1.6 +*/
1.7 +
1.8 +/** @fn accept(int s, struct sockaddr * addr, socklen_t * addrlen)
1.9 +@param s
1.10 +@param addr
1.11 +@param addrlen
1.12 +
1.13 + 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
1.14 +of pending connections and creates a new socket which it allocates a new file
1.15 +descriptor. The new socket inherits the state of the O_NONBLOCK property from the original socket s.
1.16 +
1.17 + If no pending connections are present on the queue, and the original socket
1.18 + is not marked as non-blocking, accept blocks the caller until a connection is present. If the original
1.19 + socket is marked non-blocking and no pending connections are present on the
1.20 + queue, accept returns an error as described below.
1.21 +
1.22 + The accepted socket may not be used to accept more connections. The original
1.23 + socket s remains open.
1.24 +
1.25 + The argument addr is a result argument that is filled-in with the address of the
1.26 + connecting entity as it is known to the communications layer. The exact format
1.27 + of the addr argument is determined by the domain in which the communication
1.28 + 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
1.29 + the amount of space pointed to by addr and on return will contain the actual length (in bytes) of the
1.30 + address returned. This call is used with connection-based socket types, currently
1.31 + with SOCK_STREAM.
1.32 +
1.33 + It is possible to select a socket for the purposes of doing an accept by selecting it for read.
1.34 +
1.35 + For certain protocols, such as ISO or DATAKIT which require an explicit confirmation, accept can be thought of as merely dequeueing the next connection
1.36 + request and not implying confirmation. Confirmation can be implied by a normal
1.37 + read or write on the new file descriptor, and rejection can be implied by closing
1.38 + the new socket.
1.39 +
1.40 +Examples:
1.41 +@code
1.42 +#include <sys/socket.h>
1.43 +#include <netinet/in.h>
1.44 +#include <unistd.h>
1.45 +void GetSockName()
1.46 +{
1.47 + int sock_fd;
1.48 + int newsock_fd;
1.49 + struct sockaddr_in addr;
1.50 + struct sockaddr_in ss;
1.51 + struct sockaddr_in new_socket;
1.52 + unsigned int len;
1.53 + unsigned int addr_len;
1.54 +
1.55 + sock_fd = socket(AF_INET, SOCK_STREAM, IPPROTO_TCP);
1.56 +
1.57 + addr.sin_family = AF_INET;
1.58 + addr.sin_addr.s_addr = htonl(INADDR_ANY);
1.59 + addr.sin_port = htons(5000);
1.60 + bind(sock_fd,(sockaddr*)&addr;,sizeof(addr));
1.61 + listen(sock_fd,1);
1.62 + newsock_fd = accept(sock_fd,(sockaddr*)&new;_socket,&addr;_len); // Code blocks here
1.63 + if (newsock_fd <= 0)
1.64 + {
1.65 + perror("accept:");
1.66 + }
1.67 + close(newsock_fd);
1.68 + close(sock_fd);
1.69 +}
1.70 +
1.71 +@endcode
1.72 +@return The call returns -1 on error.
1.73 +If it succeeds, it returns a non-negative
1.74 +integer that is a descriptor for the accepted socket.
1.75 +
1.76 +@see bind()
1.77 +@see connect()
1.78 +@see getpeername()
1.79 +@see listen()
1.80 +@see select()
1.81 +@see socket()
1.82 +
1.83 +
1.84 +
1.85 +@capability Deferred @ref RSocket::Open(RSocketServ &,TUint,TUint,TUint)
1.86 +
1.87 +@publishedAll
1.88 +@externallyDefinedApi
1.89 +*/
1.90 +
1.91 +
1.92 +/** @fn bind(int s, const struct sockaddr *addr, socklen_t addrlen)
1.93 +@param s
1.94 +@param addr
1.95 +@param addrlen
1.96 +
1.97 + The bind system call
1.98 +assigns the local protocol address to a socket.
1.99 +When a socket is created
1.100 +with socket it exists in an address family space but has no protocol address assigned.
1.101 +The bind system call requests that addr be assigned to the socket.
1.102 +
1.103 +Examples:
1.104 +@code
1.105 +#include <sys/socket.h>
1.106 +#include <netinet/in.h>
1.107 +#include <unistd.h>
1.108 +TInt GetSockName()
1.109 +{
1.110 + int sock_fd;
1.111 + struct sockaddr_in addr,ss;
1.112 + unsigned int len;
1.113 +
1.114 + sock_fd = socket(AF_INET, SOCK_STREAM, IPPROTO_TCP);
1.115 +
1.116 + addr.sin_family = AF_INET;
1.117 + addr.sin_addr.s_addr = htonl(INADDR_ANY);
1.118 + addr.sin_port = htons(5000);
1.119 + bind(sock_fd,(struct sockaddr*)&addr;,sizeof(addr));
1.120 + close(sock_fd);
1.121 +}
1.122 +
1.123 +@endcode
1.124 +
1.125 +Notes:
1.126 +
1.127 + For maximum portability always initialise the socket address structure to
1.128 + zero before populating it and passing it to bind.
1.129 +
1.130 +@return The bind() function returns the value 0 if successful; otherwise the
1.131 +value -1 is returned and the global variable errno is set to indicate the
1.132 +error.
1.133 +
1.134 +@see connect()
1.135 +@see getsockname()
1.136 +@see listen()
1.137 +@see socket()
1.138 +
1.139 +
1.140 +
1.141 +
1.142 +@publishedAll
1.143 +@externallyDefinedApi
1.144 +*/
1.145 +
1.146 +/** @fn connect(int s, const struct sockaddr *name, socklen_t namelen)
1.147 +@param s
1.148 +@param name
1.149 +@param namelen
1.150 +
1.151 +
1.152 + 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
1.153 + specifiies the address to which datagrams are to be sent and the only address
1.154 + from which datagrams are to be received.
1.155 +
1.156 + If the socket is of type SOCK_STREAM, this call attempts to make a connection to another socket.
1.157 + The other socket is specified by name, which is an address in the communications space of the socket.
1.158 + Each communications space interprets the name argument in its own way.
1.159 +
1.160 + Generally, stream sockets may successfully connect only once and datagram sockets may use connect multiple times to change their association. Datagram sockets
1.161 + may dissolve the association by connecting to an invalid address, such as a
1.162 + null address.
1.163 +
1.164 +Examples:
1.165 +@code
1.166 +#include <sys/socket.h>
1.167 +#include <netinet/in.h>
1.168 +#include <unistd.h>
1.169 +void Connect()
1.170 +{
1.171 + struct sockaddr_in serv_addr;
1.172 + int sock_fd;
1.173 + serv_addr.sin_family = AF_INET;
1.174 + serv_addr.sin_addr.s_addr = htonl(INADDR_LOOPBACK);
1.175 + serv_addr.sin_port = htons(5000);
1.176 + sock_fd = socket(AF_INET,SOCK_STREAM,IPPROTO_TCP);
1.177 + connect(sock_fd,(struct sockaddr*)&serv;_addr,sizeof(serv_addr));
1.178 +
1.179 + close(sock_fd);
1.180 +}
1.181 +
1.182 +@endcode
1.183 +@return The connect() function returns the value 0 if successful; otherwise it returns
1.184 +the value -1 and the sets global variable errno to indicate the error.
1.185 +
1.186 +@see accept()
1.187 +@see getpeername()
1.188 +@see getsockname()
1.189 +@see select()
1.190 +@see socket()
1.191 +
1.192 +
1.193 +
1.194 +@capability Deferred @ref RSocket::Open(RSocketServ &,TUint,TUint,TUint)
1.195 +
1.196 +@publishedAll
1.197 +@externallyDefinedApi
1.198 +*/
1.199 +
1.200 +
1.201 +/** @fn getpeername(int s, struct sockaddr * name, socklen_t * namelen)
1.202 +@param s
1.203 +@param name
1.204 +@param namelen
1.205 +@return The getpeername() function returns the value 0 if successful; otherwise
1.206 +the value -1 is returned and the global variable errno is set to indicate
1.207 +the error.
1.208 +
1.209 + The getpeername system call
1.210 +returns the name of the peer connected to
1.211 +socket s. The namelen argument should be initialized to indicate
1.212 +the amount of space pointed to by name. On return it contains the actual size of the name
1.213 +returned (in bytes).
1.214 +The name is truncated if the buffer provided is too small.
1.215 +
1.216 +Examples:
1.217 +@code
1.218 +#include <sys/socket.h>
1.219 +#include <netinet/in.h>
1.220 +#include <unistd.h>
1.221 +void GetSockName()
1.222 +{
1.223 + int sock_fd;
1.224 + int newsock_fd;
1.225 + struct sockaddr_in addr;
1.226 + struct sockaddr_in ss;
1.227 + struct sockaddr_in new_socket;
1.228 + unsigned int len;
1.229 + unsigned int addr_len;
1.230 +
1.231 + sock_fd = socket(AF_INET, SOCK_STREAM, IPPROTO_TCP);
1.232 +
1.233 + addr.sin_family = AF_INET;
1.234 + addr.sin_addr.s_addr = htonl(INADDR_ANY);
1.235 + addr.sin_port = htons(5000);
1.236 + bind(sock_fd,(struct sockaddr*)&addr;,sizeof(addr));
1.237 + listen(sock_fd,1);
1.238 + newsock_fd = accept(sock_fd,(struct sockaddr*)&new;_socket,&addr;_len); // Code blocks here
1.239 +
1.240 + // Assuming client has connected to the server.
1.241 + len = sizeof(ss);
1.242 + getpeername(sock_fd,(struct sockaddr*)&ss;,&len;);
1.243 + close(newsock_fd);
1.244 + close(sock_fd);
1.245 + }
1.246 +
1.247 +@endcode
1.248 +@see accept()
1.249 +@see bind()
1.250 +@see getsockname()
1.251 +@see socket()
1.252 +
1.253 +
1.254 +
1.255 +
1.256 +@publishedAll
1.257 +@externallyDefinedApi
1.258 +*/
1.259 +
1.260 +
1.261 +/** @fn getsockname(int s, struct sockaddr * name, socklen_t * namelen)
1.262 +@param s
1.263 +@param name
1.264 +@param namelen
1.265 +@return The getsockname() function returns the value 0 if successful; otherwise
1.266 +the value -1 is returned and the global variable errno is set to indicate
1.267 +the error.
1.268 +
1.269 + The getsockname system call
1.270 +returns the current name for the specified socket.
1.271 +The namelen argument should be initialized to indicate
1.272 +the amount of space pointed to by name. On return it contains the actual size of the name
1.273 +returned (in bytes).
1.274 +
1.275 +Examples:
1.276 +@code
1.277 +#include <sys/socket.h>
1.278 +#include <netinet/in.h>
1.279 +#include <unistd.h>
1.280 +TInt GetSockName()
1.281 +{
1.282 + int sock_fd;
1.283 + struct sockaddr_in addr,ss;
1.284 + unsigned int len;
1.285 +
1.286 + sock_fd = socket(AF_INET, SOCK_STREAM, IPPROTO_TCP);
1.287 +
1.288 + addr.sin_family = AF_INET;
1.289 + addr.sin_addr.s_addr = htonl(INADDR_ANY);
1.290 + addr.sin_port = htons(5000);
1.291 + bind(sock_fd,(struct sockaddr*)&addr;,sizeof(addr));
1.292 +
1.293 + len=sizeof(ss);
1.294 + getsockname(sock_fd,(struct sockaddr*)&ss;,&len;);
1.295 + close(sock_fd);
1.296 +}
1.297 +
1.298 +@endcode
1.299 +@see bind()
1.300 +@see getpeername()
1.301 +@see socket()
1.302 +
1.303 +
1.304 +
1.305 +
1.306 +@publishedAll
1.307 +@externallyDefinedApi
1.308 +*/
1.309 +
1.310 +/** @fn getsockopt(int s, int level, int optname, void * optval, socklen_t * optlen)
1.311 +@param s
1.312 +@param level
1.313 +@param optname
1.314 +@param optval
1.315 +@param optlen
1.316 +Note: This description also covers the following functions -
1.317 + setsockopt()
1.318 +
1.319 +@return Upon successful completion, the value 0 is returned; otherwise the
1.320 +value -1 is returned and the global variable errno is set to indicate the
1.321 +error.
1.322 +
1.323 +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.
1.324 +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;
1.325 +
1.326 +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.
1.327 +
1.328 +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.
1.329 +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
1.330 + @code
1.331 + #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
1.332 + #include <sys/time.h.>
1.333 +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
1.334 +SO_REUSEADDR Allows a socket to be bound to an local address that is already in use.
1.335 +SO_REUSEPORT enables duplicate address and port bindings
1.336 +SO_KEEPALIVE enables keep connections alive
1.337 +SO_DONTROUTE enables routing bypass for outgoing messages
1.338 +SO_BROADCAST enables permission to transmit broadcast messages (enable only)
1.339 +SO_OOBINLINE enables reception of out-of-band data in band
1.340 +SO_SNDBUF set buffer size for output
1.341 +SO_RCVBUF set buffer size for input
1.342 +SO_SNDLOWAT set minimum count for output
1.343 +SO_RCVLOWAT set minimum count for input
1.344 +SO_SNDTIMEO set timeout value for output
1.345 +SO_RCVTIMEO set timeout value for input
1.346 +SO_ACCEPTFILTER set accept filter on listening socket
1.347 +SO_TYPE get the type of the socket (get only)
1.348 +SO_ERROR get and clear error on the socket (get only)
1.349 +
1.350 +
1.351 +@endcode
1.352 +
1.353 +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.
1.354 +
1.355 +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."
1.356 +
1.357 +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.
1.358 +
1.359 +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.
1.360 +
1.361 +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.
1.362 +
1.363 +SO_LINGER option is not supported by this api.
1.364 +
1.365 +@code
1.366 +struct accept_filter_arg {
1.367 + char af_name[16];
1.368 + char af_arg[256-16];
1.369 +};
1.370 +@endcode
1.371 +
1.372 +
1.373 +
1.374 +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.
1.375 +
1.376 +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.
1.377 +
1.378 +
1.379 +
1.380 +
1.381 +Examples:
1.382 +@code
1.383 +#include <sys/socket.h>
1.384 +#include <netinet/in.h>
1.385 +#include <unistd.h>
1.386 +void SocketOptions()
1.387 +{
1.388 + int sock_fd;
1.389 + int optval = 1;
1.390 + unsigned int optlen = sizeof(optval);
1.391 + int rdoptval;
1.392 + sock_fd = socket(AF_INET, SOCK_STREAM, IPPROTO_TCP);
1.393 + setsockopt(sock_fd,SOL_SOCKET,SO_KEEPALIVE,&optval;,optlen);
1.394 + getsockopt(sock_fd,SOL_SOCKET,SO_KEEPALIVE,(void*)&rdoptval;,&optlen;);
1.395 +close(sock_fd);
1.396 +}
1.397 +
1.398 +@endcode
1.399 +@see ioctl()
1.400 +@see socket()
1.401 +
1.402 +
1.403 +
1.404 +
1.405 +@publishedAll
1.406 +@externallyDefinedApi
1.407 +*/
1.408 +
1.409 +/** @fn listen(int fd, int n)
1.410 +@param fd
1.411 +@param n
1.412 +@return The listen() function returns the value 0 if successful; otherwise the
1.413 +value -1 is returned and the global variable errno is set to indicate the
1.414 +error.
1.415 +
1.416 + To accept connections a socket is first created with socket . A willingness to accept incoming connections
1.417 +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.
1.418 +
1.419 + The n argument defines the maximum length the queue of pending connections
1.420 + may grow to. The real maximum queue length will be 1.5 times more than the value
1.421 + specified in the n argument. A subsequent listen system call on the listening socket allows the caller to change
1.422 + the maximum queue length using a new n argument. If a connection request arrives with the queue full
1.423 + the client may receive an error with an indication of ECONNREFUSED , or, in the case of TCP, the connection will be silently
1.424 + dropped.
1.425 +
1.426 + Note that before BSD 4.5 and the introduction of the syncache the n argument also determined the length of the incomplete connection
1.427 + queue, which held TCP sockets in the process of completing TCP's 3-way
1.428 + handshake. These incomplete connections are now held entirely in the syncache,
1.429 + which is unaffected by queue lengths. Inflated n values to help handle denial of service attacks are no longer
1.430 + necessary.
1.431 +
1.432 +
1.433 +
1.434 +Examples:
1.435 +@code
1.436 +#include <sys/socket.h>
1.437 +#include <netinet/in.h>
1.438 +#include <unistd.h>
1.439 +void listen_example()
1.440 +{
1.441 + int sock_fd;
1.442 + int newsock_fd;
1.443 + struct sockaddr_in addr;
1.444 + struct sockaddr_in ss;
1.445 + struct sockaddr_in new_socket;
1.446 + unsigned int len;
1.447 + unsigned int addr_len;
1.448 +
1.449 + sock_fd = socket(AF_INET, SOCK_STREAM, IPPROTO_TCP);
1.450 +
1.451 + addr.sin_family = AF_INET;
1.452 + addr.sin_addr.s_addr = htonl(INADDR_ANY);
1.453 + addr.sin_port = htons(5000);
1.454 + bind(sock_fd,(struct sockaddr*)&addr;,sizeof(addr));
1.455 + listen(sock_fd,1);
1.456 + close(sock_fd);
1.457 +}
1.458 +
1.459 +@endcode
1.460 +@see accept()
1.461 +@see connect()
1.462 +@see socket()
1.463 +
1.464 +
1.465 +
1.466 +
1.467 +@publishedAll
1.468 +@externallyDefinedApi
1.469 +*/
1.470 +
1.471 +/** @fn recv(int fd, void *buf, size_t cnt, int flags)
1.472 +@param fd
1.473 +@param buf
1.474 +@param cnt
1.475 +@param flags
1.476 +
1.477 +Note: This description also covers the following functions -
1.478 + recvfrom() recvmsg()
1.479 +
1.480 +@return These calls return the number of bytes received, or -1
1.481 +if an error occurred.
1.482 +
1.483 +@code
1.484 + MSG_OOB process out-of-band data
1.485 +@endcode
1.486 +
1.487 + The recvfrom and recvmsg system calls
1.488 +are used to receive messages from a socket,
1.489 +and may be used to receive data on a socket whether or not
1.490 +it is connection-oriented.
1.491 +
1.492 + If from is not a null pointer
1.493 +and the socket is not connection-oriented,
1.494 +the source address of the message is filled in.
1.495 +The fromlen argument
1.496 +is a value-result argument, initialized to the size of
1.497 +the buffer associated with from, and modified on return to indicate the actual size of the
1.498 +address stored there.
1.499 +
1.500 + The recv function is normally used only on a connected socket (see connect )
1.501 +and is identical to recvfrom with a
1.502 +null pointer passed as its from argument.
1.503 +As it is redundant, it may not be supported in future releases.
1.504 +
1.505 + All three routines return the length of the message on successful
1.506 +completion.
1.507 +If a message is too long to fit in the supplied buffer,
1.508 +excess bytes may be discarded depending on the type of socket
1.509 +the message is received from (see socket )
1.510 +
1.511 + If no messages are available at the socket, the
1.512 +receive call waits for a message to arrive, unless
1.513 +the socket is nonblocking (see fcntl )
1.514 +in which case the value
1.515 +-1 is returned and the external variable errno set to EAGAIN. The receive calls normally return any data available,
1.516 +up to the requested amount,
1.517 +rather than waiting for receipt of the full amount requested;
1.518 +this behavior is affected by the socket-level options SO_RCVLOWAT and SO_RCVTIMEO described in getsockopt .
1.519 +
1.520 + The select system call may be used to determine when more data arrive.
1.521 +
1.522 + 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
1.523 +
1.524 + The MSG_OOB flag requests receipt of out-of-band data
1.525 +that would not be received in the normal data stream.
1.526 +Some protocols place expedited data at the head of the normal
1.527 +data queue, and thus this flag cannot be used with such protocols.
1.528 +The MSG_PEEK flag causes the receive operation to return data
1.529 +from the beginning of the receive queue without removing that
1.530 +data from the queue.
1.531 +Thus, a subsequent receive call will return the same data.
1.532 +The MSG_WAITALL flag requests that the operation block until
1.533 +the full request is satisfied.
1.534 +The MSG_DONTWAIT flag requests the call to return when it would block otherwise.
1.535 +If no data is available, errno is set to EAGAIN.
1.536 +
1.537 +The flags MSG_OOB, MSG_PEEK, MSG_WAITALL and MSG_DONTWAIT are not supported for
1.538 +local sockets(AF_LOCAL, AF_LINUX etc..).
1.539 +
1.540 + The recvmsg system call uses a msghdr structure to minimize the number of directly supplied arguments.
1.541 +This structure has the following form, as defined in \#include \<sys/socket.h\>
1.542 +@code
1.543 + struct msghdr {
1.544 +caddr_tmsg_name;/* optional address */
1.545 +u_intmsg_namelen;/* size of address */
1.546 +structiovec *msg_iov;/* scatter/gather array */
1.547 +u_intmsg_iovlen;/* # elements in msg_iov */
1.548 +caddr_tmsg_control;/* ancillary data, see below */
1.549 +u_intmsg_controllen; /* ancillary data buffer len */
1.550 +intmsg_flags;/* flags on received message */
1.551 +};
1.552 +@endcode
1.553 +
1.554 + Here msg_name and msg_namelen specify the destination address if the socket is unconnected; msg_name may be given as a null pointer if no names are desired or required.
1.555 +The msg_iov and msg_iovlen arguments
1.556 +describe scatter gather locations, as discussed in read .
1.557 +The msg_control argument,
1.558 +which has length msg_controllen, points to a buffer for other protocol control related messages
1.559 +or other miscellaneous ancillary data.
1.560 +The messages are of the form:
1.561 +@code
1.562 +struct cmsghdr {
1.563 +u_intcmsg_len;/* data byte count, including hdr */
1.564 +intcmsg_level;/* originating protocol */
1.565 +intcmsg_type;/* protocol-specific type */
1.566 +/* followed by
1.567 +u_charcmsg_data[]; */
1.568 +};
1.569 +@endcode
1.570 +
1.571 + As an example, one could use this to learn of changes in the data-stream
1.572 +in XNS/SPP, or in ISO, to obtain user-connection-request data by requesting
1.573 +a recvmsg with no data buffer provided immediately after an accept system call.
1.574 +
1.575 + Open file descriptors are now passed as ancillary data for AF_UNIX domain sockets, with cmsg_level set to SOL_SOCKET and cmsg_type set to SCM_RIGHTS.
1.576 +
1.577 + Process credentials can also be passed as ancillary data for AF_UNIX domain sockets using a cmsg_type of SCM_CREDS. In this case, cmsg_data should be a structure of type cmsgcred, which is defined in \#include \<sys/socket.h\> as follows:
1.578 +@code
1.579 + struct cmsgcred {
1.580 +pid_tcmcred_pid;/* PID of sending process */
1.581 +uid_tcmcred_uid;/* real UID of sending process */
1.582 +uid_tcmcred_euid;/* effective UID of sending process */
1.583 +gid_tcmcred_gid;/* real GID of sending process */
1.584 +shortcmcred_ngroups;/* number or groups */
1.585 +gid_tcmcred_groups[CMGROUP_MAX];/* groups */
1.586 +};
1.587 +@endcode
1.588 +
1.589 + The kernel will fill in the credential information of the sending process
1.590 +and deliver it to the receiver.
1.591 +
1.592 + The msg_flags field is set on return according to the message received. MSG_EOR indicates end-of-record; the data returned completed a record
1.593 + (generally used with sockets of type SOCK_SEQPACKET). MSG_TRUNC indicates that the trailing portion of a datagram was discarded
1.594 + because the datagram was larger than the buffer supplied. MSG_CTRUNC indicates that some control data were discarded due to
1.595 + lack of space in the buffer for ancillary data. MSG_OOB is returned to indicate that expedited or out-of-band data
1.596 + were received.
1.597 +
1.598 +Examples:
1.599 +@code
1.600 +#include <sys/socket.h>
1.601 +#include <netinet/in.h>
1.602 +#include <unistd.h>
1.603 +void Recv()
1.604 +{
1.605 + struct sockaddr_in serv_addr;
1.606 + int sock_fd;
1.607 + char line[10];
1.608 + int size = 10;
1.609 + serv_addr.sin_family = AF_INET;
1.610 + serv_addr.sin_addr.s_addr = htonl(INADDR_LOOPBACK);
1.611 + serv_addr.sin_port = htons(5000);
1.612 + sock_fd = socket(AF_INET,SOCK_STREAM,IPPROTO_TCP);
1.613 + connect(sock_fd,(struct sockaddr*)&serv;_addr,sizeof(serv_addr));
1.614 + recv(sock_fd, line, size, 0);
1.615 + close(sock_fd);
1.616 +}
1.617 +
1.618 +@endcode
1.619 +@code
1.620 +#include <sys/socket.h>
1.621 +#include <netinet/in.h>
1.622 +#include <unistd.h>
1.623 +void Sendto()
1.624 +{
1.625 + struct sockaddr_in sender_addr;
1.626 + int sock_fd;
1.627 + char line[15] = "Hello World!";
1.628 + unsigned int size = sizeof(sender_addr);
1.629 + sock_fd = socket(AF_INET,SOCK_DGRAM,IPPROTO_UDP);
1.630 + sender_addr.sin_family = AF_INET;
1.631 + sender_addr.sin_addr.s_addr = htonl(INADDR_LOOPBACK);
1.632 + sender_addr.sin_port = htons(5000);
1.633 + recvfrom(sock_fd,line,13,0,(struct sockaddr*)&sender;_addr,&size;);
1.634 + close(sock_fd);
1.635 +}
1.636 +
1.637 +@endcode
1.638 +@code
1.639 +#include <sys/socket.h>
1.640 +#include <netinet/in.h>
1.641 +#include <unistd.h>
1.642 +void SendMsgRecvMsg()
1.643 +{
1.644 + int sock_fd;
1.645 + unsigned int sender_len;
1.646 + struct msghdr msg;
1.647 + struct iovec iov;
1.648 + struct sockaddr_in receiver_addr,sender_addr;
1.649 + char line[10];
1.650 + sock_fd = socket(AF_INET,SOCK_DGRAM,IPPROTO_UDP);
1.651 + receiver_addr.sin_family = AF_INET;
1.652 + receiver_addr.sin_addr.s_addr = htonl(INADDR_ANY);
1.653 + receiver_addr.sin_port = htons(5000);
1.654 + bind(sock_fd,(struct sockaddr*)&receiver;_addr,sizeof(receiver_addr));
1.655 + sender_len = sizeof(sender_addr);
1.656 + msg.msg_name = &sender;_addr;
1.657 + msg.msg_namelen = sender_len;
1.658 + msg.msg_iov = &iov;
1.659 + msg.msg_iovlen = 1;
1.660 + msg.msg_iov->iov_base = line;
1.661 + msg.msg_iov->iov_len = 10;
1.662 + msg.msg_control = 0;
1.663 + msg.msg_controllen = 0;
1.664 + msg.msg_flags = 0;
1.665 + recvmsg(sock_fd,&msg;,0);
1.666 + close(sock_fd);
1.667 +}
1.668 +
1.669 +@endcode
1.670 +@see fcntl()
1.671 +@see getsockopt()
1.672 +@see read()
1.673 +@see select()
1.674 +@see socket()
1.675 +
1.676 +
1.677 +
1.678 +@capability Deferred @ref RSocket::Open(RSocketServ &,TUint,TUint,TUint)
1.679 +
1.680 +@publishedAll
1.681 +@externallyDefinedApi
1.682 +*/
1.683 +
1.684 +
1.685 +/** @fn recvfrom(int s, void * buf, size_t len, int flags, struct sockaddr * from, socklen_t * fromlen)
1.686 +@param s
1.687 +@param buf
1.688 +@param len
1.689 +@param flags
1.690 +@param from
1.691 +@param fromlen
1.692 +
1.693 +Refer to recv() for the documentation
1.694 +
1.695 +@see fcntl()
1.696 +@see getsockopt()
1.697 +@see read()
1.698 +@see select()
1.699 +@see socket()
1.700 +
1.701 +
1.702 +
1.703 +@capability Deferred @ref RSocket::Open(RSocketServ &,TUint,TUint,TUint)
1.704 +
1.705 +@publishedAll
1.706 +@externallyDefinedApi
1.707 +*/
1.708 +
1.709 +
1.710 +/** @fn recvmsg(int fd, struct msghdr *message, int flags)
1.711 +@param fd
1.712 +@param message
1.713 +@param flags
1.714 +
1.715 +Refer to recv() for the documentation
1.716 +
1.717 +@see fcntl()
1.718 +@see getsockopt()
1.719 +@see read()
1.720 +@see select()
1.721 +@see socket()
1.722 +
1.723 +
1.724 +
1.725 +@capability Deferred @ref RSocket::Open(RSocketServ &,TUint,TUint,TUint)
1.726 +
1.727 +@publishedAll
1.728 +@externallyDefinedApi
1.729 +*/
1.730 +
1.731 +/** @fn send(int fd, const void *buf, size_t cnt, int flags)
1.732 +@param fd
1.733 +@param buf
1.734 +@param cnt
1.735 +@param flags
1.736 +
1.737 +Note: This description also covers the following functions -
1.738 + sendto() sendmsg()
1.739 +
1.740 + The send function,
1.741 +and sendto and sendmsg system calls
1.742 +are used to transmit a message to another socket.
1.743 +The send function
1.744 +may be used only when the socket is in a connected state, while sendto and sendmsg may be used at any time.
1.745 +
1.746 + The address of the target is given by to with tolen specifying its size.
1.747 +The length of the message is given by len. If the message is too long to pass atomically through the
1.748 +underlying protocol, the error EMSGSIZE is returned, and
1.749 +the message is not transmitted.
1.750 +
1.751 + No indication of failure to deliver is implicit in a send. Locally detected errors are indicated by a return value of -1.
1.752 +
1.753 + If no messages space is available at the socket to hold
1.754 +the message to be transmitted, then send normally blocks, unless the socket has been placed in
1.755 +non-blocking I/O mode.
1.756 +The select system call may be used to determine when it is possible to
1.757 +send more data.
1.758 +
1.759 + The flags argument may include one or more of the following:
1.760 +@code
1.761 +#defineMSG_OOB0x00001 //process out-of-band data
1.762 +#defineMSG_PEEK0x00002 // peek at incoming message
1.763 +#defineMSG_DONTROUTE0x00004 // bypass routing, use direct interface
1.764 +#define MSG_EOR0x00008 // data completes record
1.765 +#defineMSG_EOF0x00100 // data completes transaction
1.766 +@endcode
1.767 +
1.768 + The flag MSG_OOB is used to send "out-of-band"
1.769 +data on sockets that support this notion (e.g. SOCK_STREAM); the underlying protocol must also support "out-of-band"
1.770 +data. MSG_EOR is used to indicate a record mark for protocols which support the
1.771 +concept. MSG_EOF requests that the sender side of a socket be shut down, and that an
1.772 +appropriate indication be sent at the end of the specified data;
1.773 +this flag is only implemented for SOCK_STREAM sockets in the PF_INET protocol family, and is used to implement Transaction TCP MSG_DONTROUTE is usually used only by diagnostic or routing programs.
1.774 +
1.775 + See recv for a description of the msghdr structure.
1.776 +
1.777 +Examples:
1.778 +@code
1.779 +#include <sys/socket.h>
1.780 +#include <netinet/in.h>
1.781 +#include <unistd.h>
1.782 +void Recv()
1.783 +{
1.784 + struct sockaddr_in serv_addr;
1.785 + int sock_fd;
1.786 + char line[15] = "Hello world!";
1.787 + int size = 13;
1.788 + serv_addr.sin_family = AF_INET;
1.789 + serv_addr.sin_addr.s_addr = htonl(INADDR_LOOPBACK);
1.790 + serv_addr.sin_port = htons(5000);
1.791 + sock_fd = socket(AF_INET,SOCK_STREAM,IPPROTO_TCP);
1.792 + connect(sock_fd,(struct sockaddr*)&serv;_addr,sizeof(serv_addr));
1.793 + send(sock_fd, line, size, 0);
1.794 + close(sock_fd);
1.795 +}
1.796 +
1.797 +@endcode
1.798 +@code
1.799 +#include <sys/socket.h>
1.800 +#include <netinet/in.h>
1.801 +#include <unistd.h>
1.802 +void Sendto()
1.803 +{
1.804 + sockaddr_in receiver_addr;
1.805 + int sock_fd;
1.806 + char line[15] = "Hello World!";
1.807 + sock_fd = socket(AF_INET,SOCK_DGRAM,IPPROTO_UDP);
1.808 + receiver_addr.sin_family = AF_INET;
1.809 + receiver_addr.sin_addr.s_addr = htonl(INADDR_LOOPBACK);
1.810 + receiver_addr.sin_port = htons(5000);
1.811 + sendto(sock_fd, line, 13, 0,(struct sockaddr*)&receiver;_addr,sizeof(receiver_addr));
1.812 + close(sock_fd);
1.813 +}
1.814 +
1.815 +@endcode
1.816 +@code
1.817 +#include <sys/socket.h>
1.818 +#include <netinet/in.h>
1.819 +#include <unistd.h>
1.820 +void sendmsg()
1.821 +{
1.822 + struct sockaddr_in receiver_addr;
1.823 + int sock_fd;
1.824 + char line[15] = "Hello World!";
1.825 + struct msghdr msg;
1.826 + struct iovec iov;
1.827 + sock_fd = socket(AF_INET,SOCK_DGRAM,IPPROTO_UDP);
1.828 +
1.829 + receiver_addr.sin_family = AF_INET;
1.830 + receiver_addr.sin_addr.s_addr = htonl(INADDR_LOOPBACK);
1.831 + receiver_addr.sin_port = htons(5000);
1.832 + msg.msg_name = &receiver;_addr;
1.833 + msg.msg_namelen = sizeof(receiver_addr);
1.834 + msg.msg_iov = &iov;
1.835 + msg.msg_iovlen = 1;
1.836 + msg.msg_iov->iov_base = line;
1.837 + msg.msg_iov->iov_len = 13;
1.838 + msg.msg_control = 0;
1.839 + msg.msg_controllen = 0;
1.840 + msg.msg_flags = 0;
1.841 + sendmsg(sock_fd,&msg;,0);
1.842 + close(sock_fd);
1.843 +}
1.844 +
1.845 +@endcode
1.846 +@return This function call returns the number of characters sent; otherwise the
1.847 +value -1 is returned and the global variable errno is set to indicate the
1.848 +error.
1.849 +
1.850 +@see fcntl()
1.851 +@see getsockopt()
1.852 +@see recv()
1.853 +@see select()
1.854 +@see socket()
1.855 +@see write()
1.856 +
1.857 +
1.858 +Bugs:
1.859 +
1.860 + Because sendmsg does not necessarily block until the data has been transferred, it
1.861 +is possible to transfer an open file descriptor across an AF_UNIX domain socket
1.862 +(see recv then close it before it has actually been sent, the result being that the receiver
1.863 +gets a closed file descriptor.
1.864 +It is left to the application to
1.865 +implement an acknowledgment mechanism to prevent this from happening.
1.866 +
1.867 +@capability Deferred @ref RSocket::Open(RSocketServ &,TUint,TUint,TUint)
1.868 +
1.869 +@publishedAll
1.870 +@externallyDefinedApi
1.871 +*/
1.872 +
1.873 +/** @fn sendto(int s, const void *msg, size_t len, int flags, const struct sockaddr *to, socklen_t tolen)
1.874 +@param s
1.875 +@param msg
1.876 +@param len
1.877 +@param flags
1.878 +@param to
1.879 +@param tolen
1.880 +
1.881 +Refer to send() for the documentation
1.882 +
1.883 +@see fcntl()
1.884 +@see getsockopt()
1.885 +@see recv()
1.886 +@see select()
1.887 +@see socket()
1.888 +@see write()
1.889 +
1.890 +
1.891 +
1.892 +@capability Deferred @ref RSocket::Open(RSocketServ &,TUint,TUint,TUint)
1.893 +
1.894 +@publishedAll
1.895 +@externallyDefinedApi
1.896 +*/
1.897 +
1.898 +/** @fn sendmsg(int fd, const struct msghdr *message, int flags)
1.899 +@param fd
1.900 +@param message
1.901 +@param flags
1.902 +
1.903 +Refer to send() for the documentation
1.904 +
1.905 +@see fcntl()
1.906 +@see getsockopt()
1.907 +@see recv()
1.908 +@see select()
1.909 +@see socket()
1.910 +@see write()
1.911 +
1.912 +
1.913 +
1.914 +@capability Deferred @ref RSocket::Open(RSocketServ &,TUint,TUint,TUint)
1.915 +
1.916 +@publishedAll
1.917 +@externallyDefinedApi
1.918 +*/
1.919 +
1.920 +
1.921 +/** @fn setsockopt(int s, int level, int optname, const void *optval, socklen_t optlen)
1.922 +@param s
1.923 +@param level
1.924 +@param optname
1.925 +@param optval
1.926 +@param optlen
1.927 +
1.928 +Refer to getsockopt() for the documentation
1.929 +
1.930 +@see ioctl()
1.931 +@see socket()
1.932 +
1.933 +
1.934 +Note:For multicast to work on Symbian OS the connection for the interface needs to be started first.
1.935 +On most of the desktop Operating Systems,the network interface is always running, so things like setsockopt() will always pass.
1.936 +But on Symbian, the interface is not always running (in order to save battery and/or data charges) so some options in setsockopt() will not work until the connection is started.
1.937 +
1.938 +
1.939 +
1.940 +@publishedAll
1.941 +@externallyDefinedApi
1.942 +*/
1.943 +
1.944 +
1.945 +/** @fn shutdown(int fd, int how)
1.946 +@param fd
1.947 +@param how
1.948 +@return The shutdown() function returns the value 0 if successful; otherwise the
1.949 +value -1 is returned and the global variable errno is set to indicate the
1.950 +error.
1.951 +
1.952 +@code
1.953 + SHUT_RD further receives will be disallowed.
1.954 + SHUT_WR further sends will be disallowed.
1.955 + SHUT_RDWR
1.956 + further sends and receives will be disallowed.
1.957 +
1.958 +@endcode
1.959 + The shutdown system call causes all or part of a full-duplex connection on
1.960 +the socket associated with the file descriptor sockfd to be shut down.
1.961 +The how argument specifies the type of shutdown.
1.962 +Possible values are: SHUT_RD further receives will be disallowed. SHUT_WR further sends will be disallowed. SHUT_RDWR further sends and receives will be disallowed.
1.963 +
1.964 +Examples:
1.965 +@code
1.966 +#include <sys/socket.h>
1.967 +#include <netinet/in.h>
1.968 +#include <unistd.h>
1.969 +TInt shutdown_example()
1.970 +{
1.971 + int sock_fd;
1.972 + sockaddr_in addr,ss;
1.973 + unsigned int len;
1.974 +
1.975 + sock_fd = socket(AF_INET, SOCK_STREAM, IPPROTO_TCP);
1.976 +
1.977 + addr.sin_family = AF_INET;
1.978 + addr.sin_addr.s_addr = htonl(INADDR_ANY);
1.979 + addr.sin_port = htons(5000);
1.980 + bind(sock_fd,(sockaddr*)&addr;,sizeof(addr));
1.981 + shutdown(sock_fd, SHUT_RD)
1.982 + close(sock_fd);
1.983 +}
1.984 +
1.985 +@endcode
1.986 +@see connect()
1.987 +@see socket()
1.988 +
1.989 +
1.990 +
1.991 +
1.992 +@publishedAll
1.993 +@externallyDefinedApi
1.994 +*/
1.995 +
1.996 +/** @fn sockatmark(int s)
1.997 +@param s
1.998 +@return Upon successful completion, the sockatmark function returns the value 1 if the read pointer is pointing at
1.999 +the OOB mark, 0 if it is not.Otherwise the value -1 is returned
1.1000 +and the global variable errno is set to indicate the error.
1.1001 +
1.1002 + To find out if the read pointer is currently pointing at
1.1003 +the mark in the data stream, the sockatmark function is provided.
1.1004 +If sockatmark returns 1, the next read will return data
1.1005 +after the mark.
1.1006 +Otherwise (assuming out of band data has arrived),
1.1007 +the next read will provide data sent by the client prior
1.1008 +to transmission of the out of band signal.
1.1009 +The routine used
1.1010 +in the remote login process to flush output on receipt of an
1.1011 +interrupt or quit signal is shown below.
1.1012 +It reads the normal data up to the mark (to discard it),
1.1013 +then reads the out-of-band byte.
1.1014 +@code
1.1015 +#include <sys/socket.h>
1.1016 +oob()
1.1017 +{
1.1018 +int out = FWRITE, mark;
1.1019 +char waste[BUFSIZ];
1.1020 +/* flush local terminal output */
1.1021 +ioctl(1, TIOCFLUSH, (char *)&out;);
1.1022 +for (;;) {
1.1023 +if ((mark = sockatmark(rem)) < 0) {
1.1024 +perror("sockatmark");
1.1025 +break;
1.1026 +}
1.1027 +if (mark)
1.1028 +break;
1.1029 +(void) read(rem, waste, sizeof (waste));
1.1030 +}
1.1031 +if (recv(rem, &mark;, 1, MSG_OOB) < 0) {
1.1032 +perror("recv");
1.1033 +...
1.1034 +}
1.1035 +...
1.1036 +}
1.1037 +@endcode
1.1038 +
1.1039 +Examples:
1.1040 +@code
1.1041 +#include <sys/socket.h>
1.1042 +#include <netinet/in.h>
1.1043 +#include <unistd.h>
1.1044 +void SockAtMark()
1.1045 +{
1.1046 + int sockfd;
1.1047 + sockaddr_in selfAddr;
1.1048 + sockfd = socket(AF_INET,SOCK_STREAM,IPPROTO_TCP);
1.1049 +
1.1050 + selfAddr.sin_family = AF_INET;
1.1051 + selfAddr.sin_addr.s_addr = INADDR_ANY;
1.1052 + selfAddr.sin_port = htons(5000);
1.1053 + bind(sockfd,(struct sockaddr*)&selfAddr;, sizeof(selfAddr));
1.1054 + sockatmark(sockfd);
1.1055 + close(sockfd);
1.1056 +}
1.1057 +
1.1058 +@endcode
1.1059 +@see recv()
1.1060 +@see send()
1.1061 +@see ioctl()
1.1062 +
1.1063 +
1.1064 +
1.1065 +
1.1066 +@publishedAll
1.1067 +@externallyDefinedApi
1.1068 +*/
1.1069 +
1.1070 +
1.1071 +/** @fn socket(int family, int style, int protocol)
1.1072 +@param family
1.1073 +@param style
1.1074 +@param protocol
1.1075 +@return The socket() function returns valid socket descriptor if successful; otherwise the
1.1076 +value -1 is returned and the global variable errno is set to indicate the
1.1077 +error.
1.1078 +
1.1079 + The socket system call
1.1080 +creates an endpoint for communication and returns a descriptor.
1.1081 +
1.1082 + The family argument specifies a communications domain within which communication
1.1083 + will take place; this selects the protocol family which should be used. These
1.1084 + families are defined in the include file \#include \<sys/socket.h\> The currently understood formats
1.1085 + are:
1.1086 +
1.1087 + PF_LOCALHost-internal protocols, formerly called PF_UNIX,
1.1088 +PF_INETInternet version 4 protocols,
1.1089 +
1.1090 + The socket has the indicated style, which specifies the semantics of communication.
1.1091 +Currently
1.1092 +defined types are:
1.1093 +
1.1094 +@code
1.1095 +
1.1096 +SOCK_STREAMStream socket,
1.1097 +SOCK_DGRAMDatagram socket,
1.1098 +SOCK_SEQPACKETSequenced packet stream
1.1099 +
1.1100 +@endcode
1.1101 +
1.1102 + A SOCK_STREAM type provides sequenced, reliable,
1.1103 +two-way connection based byte streams.
1.1104 +An out-of-band data transmission mechanism may be supported.
1.1105 +A SOCK_DGRAM socket supports
1.1106 +datagrams (connectionless, unreliable messages of
1.1107 +a fixed (typically small) maximum length).
1.1108 +A SOCK_SEQPACKET socket may provide a sequenced, reliable,
1.1109 +two-way connection-based data transmission path for datagrams
1.1110 +of fixed maximum length; a consumer may be required to read
1.1111 +an entire packet with each read system call.
1.1112 +This facility is protocol specific, and presently unimplemented.
1.1113 +
1.1114 + The protocol argument
1.1115 +specifies a particular protocol to be used with the socket.
1.1116 +Normally only a single protocol exists to support a particular
1.1117 +socket type within a given protocol family.
1.1118 +However, it is possible
1.1119 +that many protocols may exist, in which case a particular protocol
1.1120 +must be specified in this manner.
1.1121 +The protocol number to use is
1.1122 +particular to the "communication domain"
1.1123 +in which communication
1.1124 +is to take place.
1.1125 +
1.1126 + Sockets of type SOCK_STREAM are full-duplex byte streams, similar
1.1127 +to pipes.
1.1128 +A stream socket must be in a connected state before any data may be sent or received
1.1129 +on it.
1.1130 +A connection to another socket is created with a connect system call.
1.1131 +Once connected, data may be transferred using read and write calls or some variant of the send and recv functions.
1.1132 +(Some protocol families, such as the Internet family,
1.1133 +support the notion of an "implied connect,"
1.1134 +which permits data to be sent piggybacked onto a connect operation by
1.1135 +using the sendto system call.)
1.1136 +When a session has been completed a close may be performed.
1.1137 +Out-of-band data may also be transmitted as described in send and received as described in recv
1.1138 +
1.1139 + The communications protocols used to implement a SOCK_STREAM insure that data
1.1140 +is not lost or duplicated.
1.1141 +If a piece of data for which the
1.1142 +peer protocol has buffer space cannot be successfully transmitted
1.1143 +within a reasonable length of time, then
1.1144 +the connection is considered broken and calls
1.1145 +will indicate an error with
1.1146 +-1 returns and with ETIMEDOUT as the specific code
1.1147 +in the global variable errno. The protocols optionally keep sockets "warm"
1.1148 +by forcing transmissions
1.1149 +roughly every minute in the absence of other activity.
1.1150 +An error is then indicated if no response can be
1.1151 +elicited on an otherwise
1.1152 +idle connection for an extended period (e.g. 5 minutes).
1.1153 +
1.1154 + SOCK_SEQPACKET sockets employ the same system calls as SOCK_STREAM sockets. The only difference is that read calls will return only the amount of data
1.1155 + requested and any remaining in the arriving packet will be discarded.
1.1156 +
1.1157 + SOCK_DGRAM sockets allow sending of datagrams to correspondents named
1.1158 + in send calls. Datagrams are generally received
1.1159 + with recvfrom which returns the next datagram with
1.1160 + its return address.
1.1161 +
1.1162 +Examples:
1.1163 +@code
1.1164 +#include <sys/socket.h>
1.1165 +#include <unistd.h>
1.1166 +#include <stdio.h>
1.1167 +#inlcude <netinet/in.h>
1.1168 +void SocketExample()
1.1169 +{
1.1170 + int sock_fd;
1.1171 + sock_fd = socket(AF_INET, SOCK_DGRAM, IPPROTO_UDP);
1.1172 + close(sock_fd);
1.1173 +}
1.1174 +
1.1175 +@endcode
1.1176 +@see accept()
1.1177 +@see bind()
1.1178 +@see connect()
1.1179 +@see getpeername()
1.1180 +@see getsockname()
1.1181 +@see getsockopt()
1.1182 +@see ioctl()
1.1183 +@see listen()
1.1184 +@see read()
1.1185 +@see recv()
1.1186 +@see select()
1.1187 +@see send()
1.1188 +@see shutdown()
1.1189 +@see write()
1.1190 +
1.1191 +
1.1192 +
1.1193 +@capability Deferred @ref RSocket::Open(RSocketServ &,TUint,TUint,TUint)
1.1194 +
1.1195 +@publishedAll
1.1196 +@externallyDefinedApi
1.1197 +*/
1.1198 +
1.1199 +
1.1200 +/** @typedef typedef __sa_family_t sa_family_t
1.1201 +
1.1202 +Address family type
1.1203 +
1.1204 +@publishedAll
1.1205 +@externallyDefinedApi
1.1206 +*/
1.1207 +
1.1208 +/** @typedef typedef __socklen_t socklen_t
1.1209 +
1.1210 +Socket address length type.
1.1211 +
1.1212 +@publishedAll
1.1213 +@externallyDefinedApi
1.1214 +*/
1.1215 +
1.1216 +/** @struct sockaddr
1.1217 +
1.1218 +Structure used by kernel to store most addresses.
1.1219 +
1.1220 +@publishedAll
1.1221 +@externallyDefinedApi
1.1222 +*/
1.1223 +
1.1224 +/** @var sockaddr::sa_len
1.1225 +total length
1.1226 +*/
1.1227 +
1.1228 +/** @var sockaddr::sa_family
1.1229 +address family
1.1230 +*/
1.1231 +
1.1232 +/** @var sockaddr::sa_data
1.1233 +actually longer; address value
1.1234 +*/
1.1235 +
1.1236 +/** @struct cmsghdr
1.1237 +
1.1238 +Header for ancillary data objects in msg_control buffer.
1.1239 +Used for additional information with/about a datagram not expressible by flags.
1.1240 +The format is a sequence of message elements headed by cmsghdr structures.
1.1241 +
1.1242 +@publishedAll
1.1243 +@externallyDefinedApi
1.1244 +*/
1.1245 +
1.1246 +/** @var cmsghdr::cmsg_len
1.1247 +data byte count, including hdr
1.1248 +*/
1.1249 +
1.1250 +/** @var cmsghdr::cmsg_level
1.1251 +originating protocol
1.1252 +*/
1.1253 +
1.1254 +/** @var cmsghdr::cmsg_type
1.1255 +protocol-specific type
1.1256 +*/
1.1257 +
1.1258 +
1.1259 +/** @struct msghdr
1.1260 +
1.1261 +Message header for recvmsg and sendmsg calls.
1.1262 +Used value-result for recvmsg, value only for sendmsg.
1.1263 +
1.1264 +@publishedAll
1.1265 +@externallyDefinedApi
1.1266 +*/
1.1267 +
1.1268 +/** @var msghdr::msg_name
1.1269 +optional address
1.1270 +*/
1.1271 +
1.1272 +/** @var msghdr::msg_namelen
1.1273 +size of address
1.1274 +*/
1.1275 +
1.1276 +/** @var msghdr::msg_iov
1.1277 +scatter or gather array
1.1278 +*/
1.1279 +
1.1280 +/** @var msghdr::msg_iovlen
1.1281 +x elements in msg_iov
1.1282 +*/
1.1283 +
1.1284 +/** @var msghdr::msg_control
1.1285 +ancillary data, see below
1.1286 +*/
1.1287 +
1.1288 +/** @var msghdr::msg_controllen
1.1289 +ancillary data buffer len
1.1290 +*/
1.1291 +
1.1292 +/** @var msghdr::msg_flags
1.1293 +flags on received message
1.1294 +*/
1.1295 +
1.1296 +/** @def CMSG_DATA(cmsg)
1.1297 +
1.1298 +given pointer to struct cmsghdr, return pointer to data
1.1299 +
1.1300 +@publishedAll
1.1301 +@externallyDefinedApi
1.1302 +*/
1.1303 +
1.1304 +/** @def CMSG_NXTHDR(mhdr, cmsg)
1.1305 +
1.1306 +given pointer to struct cmsghdr, return pointer to next cmsghdr
1.1307 +
1.1308 +@publishedAll
1.1309 +@externallyDefinedApi
1.1310 +*/
1.1311 +
1.1312 +
1.1313 +/** @def CMSG_FIRSTHDR(mhdr)
1.1314 +
1.1315 +RFC 2292 requires to check msg_controllen, in case that the kernel returns an empty list for some reasons.
1.1316 +
1.1317 +@publishedAll
1.1318 +@externallyDefinedApi
1.1319 +*/
1.1320 +
1.1321 +/** @struct linger
1.1322 +
1.1323 +Structure used for manipulating linger option.
1.1324 +
1.1325 +@publishedAll
1.1326 +@externallyDefinedApi
1.1327 +*/
1.1328 +
1.1329 +/** @var linger::l_onoff
1.1330 +option on or off
1.1331 +*/
1.1332 +
1.1333 +/** @var linger::l_linger
1.1334 +linger time
1.1335 +*/
1.1336 +
1.1337 +
1.1338 +/** @def AF_UNIX
1.1339 +
1.1340 +local to host (pipes, portals)
1.1341 +
1.1342 +@publishedAll
1.1343 +@externallyDefinedApi
1.1344 +*/
1.1345 +
1.1346 +/** @def AF_INET
1.1347 +
1.1348 +internetwork: UDP, TCP, etc.
1.1349 +
1.1350 +@publishedAll
1.1351 +@externallyDefinedApi
1.1352 +*/
1.1353 +
1.1354 +/** @def AF_UNSPEC
1.1355 +
1.1356 +Address family. Unspecified.
1.1357 +
1.1358 +@publishedAll
1.1359 +@externallyDefinedApi
1.1360 +*/
1.1361 +
1.1362 +/** @def SHUT_RD
1.1363 +
1.1364 +shut down the reading side
1.1365 +
1.1366 +@publishedAll
1.1367 +@externallyDefinedApi
1.1368 +*/
1.1369 +
1.1370 +/** @def SHUT_WR
1.1371 +
1.1372 +shut down the writing side
1.1373 +
1.1374 +@publishedAll
1.1375 +@externallyDefinedApi
1.1376 +*/
1.1377 +
1.1378 +/** @def SHUT_RDWR
1.1379 +
1.1380 +shut down both sides
1.1381 +
1.1382 +@publishedAll
1.1383 +@externallyDefinedApi
1.1384 +*/
1.1385 +
1.1386 +
1.1387 +/** @def MSG_OOB
1.1388 +
1.1389 +process out-of-band data
1.1390 +
1.1391 +@publishedAll
1.1392 +@externallyDefinedApi
1.1393 +*/
1.1394 +
1.1395 +/** @def MSG_PEEK
1.1396 +
1.1397 +peek at incoming message
1.1398 +
1.1399 +@publishedAll
1.1400 +@externallyDefinedApi
1.1401 +*/
1.1402 +
1.1403 +/** @def MSG_DONTROUTE
1.1404 +
1.1405 +send without using routing tables
1.1406 +
1.1407 +@publishedAll
1.1408 +@externallyDefinedApi
1.1409 +*/
1.1410 +
1.1411 +/** @def MSG_EOR
1.1412 +
1.1413 +data completes record
1.1414 +
1.1415 +@publishedAll
1.1416 +@externallyDefinedApi
1.1417 +*/
1.1418 +
1.1419 +/** @def MSG_TRUNC
1.1420 +
1.1421 +data discarded before delivery
1.1422 +
1.1423 +@publishedAll
1.1424 +@externallyDefinedApi
1.1425 +*/
1.1426 +
1.1427 +/** @def MSG_CTRUNC
1.1428 +
1.1429 +control data lost before delivery
1.1430 +
1.1431 +@publishedAll
1.1432 +@externallyDefinedApi
1.1433 +*/
1.1434 +
1.1435 +/** @def MSG_WAITALL
1.1436 +
1.1437 +wait for full request or error
1.1438 +
1.1439 +@publishedAll
1.1440 +@externallyDefinedApi
1.1441 +*/
1.1442 +
1.1443 +/** @def SO_ACCEPTCONN
1.1444 +
1.1445 +socket has had listen()
1.1446 +
1.1447 +@publishedAll
1.1448 +@externallyDefinedApi
1.1449 +*/
1.1450 +
1.1451 +/** @def SO_BROADCAST
1.1452 +
1.1453 +permit sending of broadcast msgs
1.1454 +
1.1455 +@publishedAll
1.1456 +@externallyDefinedApi
1.1457 +*/
1.1458 +
1.1459 +
1.1460 +/** @def SO_DEBUG
1.1461 +
1.1462 +turn on debugging info recording KSODebug
1.1463 +
1.1464 +@publishedAll
1.1465 +@externallyDefinedApi
1.1466 +*/
1.1467 +
1.1468 +/** @def SO_DONTROUTE
1.1469 +
1.1470 +just use interface addresses
1.1471 +
1.1472 +@publishedAll
1.1473 +@externallyDefinedApi
1.1474 +*/
1.1475 +
1.1476 +/** @def SO_ERROR
1.1477 +
1.1478 +get error status and clear
1.1479 +
1.1480 +@publishedAll
1.1481 +@externallyDefinedApi
1.1482 +*/
1.1483 +
1.1484 +/** @def SO_KEEPALIVE
1.1485 +
1.1486 +keep connections alive KSoTcpKeepAlive
1.1487 +
1.1488 +@publishedAll
1.1489 +@externallyDefinedApi
1.1490 +*/
1.1491 +
1.1492 +/** @def SO_LINGER
1.1493 +
1.1494 +linger on close if data present
1.1495 +
1.1496 +@publishedAll
1.1497 +@externallyDefinedApi
1.1498 +*/
1.1499 +
1.1500 +/** @def SO_OOBINLINE
1.1501 +
1.1502 +leave received OOB data in line KSoTcpOobInline
1.1503 +
1.1504 +@publishedAll
1.1505 +@externallyDefinedApi
1.1506 +*/
1.1507 +
1.1508 +
1.1509 +/** @def SO_RCVBUF
1.1510 +
1.1511 +receive buffer size KSORecvBuf
1.1512 +
1.1513 +@publishedAll
1.1514 +@externallyDefinedApi
1.1515 +*/
1.1516 +
1.1517 +/** @def SO_RCVLOWAT
1.1518 +
1.1519 +receive low-water mark
1.1520 +
1.1521 +@publishedAll
1.1522 +@externallyDefinedApi
1.1523 +*/
1.1524 +
1.1525 +/** @def SO_RCVTIMEO
1.1526 +
1.1527 +receive timeout
1.1528 +
1.1529 +@publishedAll
1.1530 +@externallyDefinedApi
1.1531 +*/
1.1532 +
1.1533 +/** @def SO_REUSEADDR
1.1534 +
1.1535 +Allow a socket to be bound to an local address that is already in use.
1.1536 +
1.1537 +@publishedAll
1.1538 +@externallyDefinedApi
1.1539 +*/
1.1540 +
1.1541 +
1.1542 +/** @def SO_SNDBUF
1.1543 +
1.1544 +send buffer size KSOSendBuf
1.1545 +
1.1546 +@publishedAll
1.1547 +@externallyDefinedApi
1.1548 +*/
1.1549 +
1.1550 +/** @def SO_SNDLOWAT
1.1551 +
1.1552 +send low-water mark
1.1553 +
1.1554 +@publishedAll
1.1555 +@externallyDefinedApi
1.1556 +*/
1.1557 +
1.1558 +/** @def SO_SNDTIMEO
1.1559 +
1.1560 +send timeout
1.1561 +
1.1562 +@publishedAll
1.1563 +@externallyDefinedApi
1.1564 +*/
1.1565 +
1.1566 +
1.1567 +/** @def SO_TYPE
1.1568 +
1.1569 +get socket type
1.1570 +
1.1571 +@publishedAll
1.1572 +@externallyDefinedApi
1.1573 +*/
1.1574 +
1.1575 +/** @def SOCK_DGRAM
1.1576 +
1.1577 +datagram socket
1.1578 +
1.1579 +@publishedAll
1.1580 +@externallyDefinedApi
1.1581 +*/
1.1582 +
1.1583 +/** @def SOCK_STREAM
1.1584 +
1.1585 +stream socket
1.1586 +
1.1587 +@publishedAll
1.1588 +@externallyDefinedApi
1.1589 +*/
1.1590 +
1.1591 +/** @def SOCK_SEQPACKET
1.1592 +
1.1593 +sequenced packet stream
1.1594 +
1.1595 +@publishedAll
1.1596 +@externallyDefinedApi
1.1597 +*/
1.1598 +
1.1599 +
1.1600 +/** @def SOL_SOCKET
1.1601 +
1.1602 +options for socket level KSOLSocket
1.1603 +
1.1604 +@publishedAll
1.1605 +@externallyDefinedApi
1.1606 +*/
1.1607 +
1.1608 +
1.1609 +/** @def SOCK_RAW
1.1610 +
1.1611 +raw-protocol interface
1.1612 +
1.1613 +@publishedAll
1.1614 +@released
1.1615 +*/
1.1616 +
1.1617 +
1.1618 +
1.1619 +
1.1620 +
1.1621 +