*** UNIX MANUAL PAGE BROWSER ***

recvmsg(2) System Calls Manual recvmsg(2) NAME recvmsg - Receives a message from a socket using a message structure SYNOPSIS #include <sys/socket.h> ssize_t recvmsg( int socket, struct msghdr *message, int flags ) ; [Digital] The following definition of the recvmsg() function does not conform to current standards and is supported only for backward compat- ibility (see standards(5)): int recvmsg( int socket, struct msghdr *message, int flags ) ; STANDARDS Interfaces documented on this reference page conform to industry stan- dards as follows: recvmsg(): XPG4-UNIX Refer to the standards(5) reference page for more information about in- dustry standards and associated tags. PARAMETERS Specifies the socket descriptor. Points to a msghdr structure, con- taining pointers to both the destination address for the incoming mes- sage and to buffers containing ancillary data. The format of the ad- dress is determined by the behavior requested for the socket. [Digital] If the compile-time option _SOCKADDR_LEN is defined before the <sys/socket.h> header file is included, the msghdr structure takes 4.4BSD behavior. Otherwise, the default 4.3BSD msghdr structure is used. In 4.4BSD, the msghdr structure has a separate msg_flags field for holding flags from the received message. In addition, the msg_accrights field is generalized into a msg_control field. See DESCRIPTION for more information. If _SOCKADDR_LEN is defined, the 4.3BSD msghdr structure is de- fined with the name omsghdr. Permits the caller of this func- tion to exercise control over the reception of messages. The value for this parameter is formed by a logical OR of one or more of the following values: Peeks at the incoming message. Processes out-of-band data on sockets that support out-of-band data. Requests that the func- tion block wait until the full amount of data requested can be returned. The function may return a smaller amount of data if a signal is caught, the connection is terminated, or an error is pending for the socket. DESCRIPTION The recvmsg() function receives messages from unconnected or connected sockets and returns the length of the message. When a message is too long for the buffer, the message may be truncated depending on the type of socket from which the message is written. When no messages are available at the socket specified by the socket parameter, the recvmsg() function waits for a message to arrive. When the socket is nonblocking and no message is available, the recvmsg() function fails and sets errno to [EWOULDBLOCK]. Use the select() function to determine when more data arrives. The recvmsg() function uses a msghdr structure to minimize the number of directly supplied parameters. In the msghdr structure, the msg_name and msg_namelen fields specify the destination address if the socket is unconnected. The msg_name field may be given as a null pointer if no names are desired or required. The msg_iov and msg_iovlen fields de- scribe the scatter gather locations. [Digital] In 4.3BSD, the msg_accrights field is a buffer for passing access rights. In 4.4BSD, the msg_accrights field has been expanded into a msg_control field, to include other protocol control messages or other miscellaneous ancillary data. In the 4.4BSD msghdr structure, the msg_flags field holds flags from the received message. In addition to MSG_PEEK and MSG_OOB, the incom- ing flags reported in the msg_flags field can be any of the following values: Data includes the end-of-record marker. Data was truncated be- fore delivery. Control data was truncated before delivery. NOTES [Digital] When compiled in the X/Open UNIX environment, calls to the recvmsg() function are internally renamed by prepending _E to the func- tion name. When you are debugging a module that includes the recvmsg() function and for which _XOPEN_SOURCE_EXTENDED has been defined, use _Erecvmsg to refer to the recvmsg() call. See standards(5) for further information. RETURN VALUES Upon successful completion, the recvmsg() function returns the length of the message in bytes, and fills in the fields of the msghdr struc- ture pointed to by the message parameter as appropriate. Otherwise, a value of -1 is returned and errno is set to indicate the error. ERRORS If the recvmsg() function fails, errno may be set to one of the follow- ing values: The socket parameter is not valid. A connection was forcibly closed by a peer. The message parameter is not in a readable or writable part of user address-space. This function was interrupted by a signal before any data was available. The MSG-OOB flag is set and no out-of-band data is available. A receive is attempted on a connec- tion-oriented socket that is not connected. The socket parameter refers to a file, not a socket. The specified flags are not supported this socket type. The connection timed out during connection estab- lishment, or due to a transmission timeout on active connection. The socket is marked nonblocking and no data is ready to be received. RELATED INFORMATION Functions: recv(2), recvfrom(2), send(2), sendmsg(2), sendto(2), se- lect(2), shutdown(2), socket(2) Standards: standards(5) delim off recvmsg(2)