recv()--Receive Data

BSD 4.3 Syntax

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

 int recv(int socket_descriptor,
         char *buffer,
         int buffer_length,
         int flags)

  Service Program Name: QSOSRV1

  Default Public Authority: *USE

  Threadsafe: Yes

UNIX^® 98 Compatible Syntax

  #define _XOPEN_SOURCE 520
  #include <sys/socket.h>

 ssize_t recv(int socket_descriptor,
         void *buffer,
         size_t buffer_length,
         int flags)

  Service Program Name: QSOSRV1

  Default Public Authority: *USE

  Threadsafe: Yes

The recv() function is used to receive data through a socket.

There are two versions of the API, as shown above. The base IBM^® i API uses BSD 4.3 structures and syntax. The other uses syntax and structures compatible with the UNIX 98 programming interface specifications. You can select the UNIX 98 compatible interface with the _XOPEN_SOURCE macro.

Parameters

socket_descriptor

(Input) The socket descriptor that is to be read from.

buffer

(Input) The pointer to the buffer in which the data that is to be read is stored.

buffer_length

(Input) The length of the buffer.

flags

(Input) A flag value that controls the reception of the data. The flags value is either zero, or is obtained by performing an OR operation on one or more of the following constants:

`MSG_OOB`	Receive out-of-band data. Valid only for sockets with an address family of `AF_INET` or `AF_INET6` and type `SOCK_STREAM`.
`MSG_PEEK`	Obtain a copy of the message without removing the message from the socket.
`MSG_WAITALL`	Wait for a full request or an error.

Authorities

No authorization is required.

Return Value

recv() returns an integer. Possible values are:

-1 (unsuccessful)
n (successful), where n is the number of bytes received.

Error Conditions

When recv() fails, errno can be set to one of the following:

[EACCES]	Permission denied. The socket pointed to by the socket_descriptor parameter is using a connection-oriented transport service, and a connect() was previously completed. The process, however, does not have the appropriate privileges to the objects that were needed to establish a connection. For example, the connect() required the use of an APPC device that the process was not authorized to.
[EBADF]	Descriptor not valid.
[ECONNABORTED]	Connection ended abnormally. This error code indicates that the transport provider ended the connection abnormally because of one of the following: The retransmission limit has been reached for data that was being sent on the socket. A protocol error was detected.
[ECONNREFUSED]	The destination socket refused an attempted connect operation.
[ECONNRESET]	A connection with a remote socket was reset by that socket.
[EFAULT]	Bad address. The system detected an address which was not valid while attempting to access the buffer parameter.
[EINTR]	Interrupted function call.
[EINVAL]	Parameter not valid. This error code indicates one of the following: The buffer_length parameter specifies a negative value. The flags parameter specifies a value that includes the `MSG_OOB` flag, but no OOB data was available to be received. The flags parameter specifies a value that includes the `MSG_OOB` flag, and the socket option `SO_OOBINLINE` has been set. The socket_descriptor parameter points to a socket that is using a connectionless transport service, is not a socket of type `SOCK_RAW`, and is not bound to an address.
[EIO]	Input/output error.
[ENOBUFS]	There is not enough buffer space for the requested operation.
[ENOTCONN]	Requested operation requires a connection. This error code is returned only on sockets that use a connection-oriented transport service.
[ENOTSOCK]	The specified descriptor does not reference a socket.
[EOPNOTSUPP]	Operation not supported. This error code indicates one of the following: The flags parameter specifies a value that includes the `MSG_OOB` flag, but the socket_descriptor parameter points to a connectionless socket. The flags parameter specifies a value that includes the `MSG_OOB` flag, but the socket_descriptor parameter points to a socket that does not have an address family of `AF_INET` or `AF_INET6`.
[ETIMEDOUT]	A remote host did not respond within the timeout period. A nonblocking connect() call was previously done that resulted in the connection establishment timing out. No connection is established. This error code is returned only on sockets that use a connection-oriented transport service.
[EUNATCH]	The protocol required to support the specified address family is not available at this time.
[EUNKNOWN]	Unknown system state.
[EWOULDBLOCK]	Operation would have caused the thread to be suspended.

Error Messages

Message ID	Error Message Text
CPE3418 E	Possible APAR condition or hardware failure.
CPF9872 E	Program or service program &1 in library &2 ended. Reason code &3.
CPFA081 E	Unable to set return value or error code.

Usage Notes

For sockets that use a connection-oriented transport service (for example, sockets with a type of SOCK_STREAM), a returned value of zero indicates one of the following:
- The partner program has issued a close() for the socket.
- The partner program has issued a shutdown() to disable writing to the socket.
- The connection is broken and the error was returned on a previously issued socket function.
- A shutdown() to disable reading was previously done on the socket.
The following applies to sockets that use a connectionless transport service (for example, a socket with a type of SOCK_DGRAM):
- If a connect() has been issued previously, then data can be received only from the address specified in the previous connect().
- The address from which data is received is discarded, since the recv() has no address parameter.
- The entire message must be read in a single read operation. If the size of the message is too large to fit in the user supplied buffer, the remaining bytes of the message are discarded.
- A returned value of zero indicates one of the following:
  - The partner program has sent a NULL message (a datagram with no user data),
  - A shutdown() to disable reading was previously done on the socket.
  - The buffer length specified was zero.
When you develop in C-based languages and an application is compiled with the _XOPEN_SOURCE macro defined to the value 520 or greater, the recv() API is mapped to qso_recv98().

Related Information

_XOPEN_SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface
fcntl()--Perform File Control Command
ioctl()--Perform I/O Control Request
recvfrom()--Receive Data
recvmsg()--Receive Data or Descriptors or Both

API introduced: V3R1

[ Back to top | UNIX-Type APIs | APIs by category ]