read: Read data on a socket

The read socket function reads data on a socket with descriptor s and stores it in a buffer.

Note: This description applies only to sockets.

Last updated

  • Changed for PUT15 (information only; no code change).
  • Changed for PUT14.

Format

#include  <sys/socket.h>
int       read(int s,
               char *buf,
               int len);
s
The socket descriptor.
buf
A pointer to the buffer that receives the data.
len
The length, in bytes, of the buffer pointed to by the buf parameter. The maximum amount of data that can be received is 1048576 bytes.

Normal return

If successful, the function returns the length, in bytes, of the message or datagram:
  • For UDP sockets, zero length messages can be received on the socket.
  • For TCP sockets, if the connection is closed, 0 is returned.

Error return

A return code equal to -1 indicates an error. You can get the specific error code by calling sock_errno. For more information about socket errors, see Socket error return codes.
E1052STATE
The socket was closed because the system was in or cycling down to 1052 state.
ESYSTEMERROR
A system error has occurred and closed the socket.
SOCFAULT
Using buf and len results in an attempt to access a protected address space.
SOCNETUNREACH
An ICMP message was received on this socket (in response to sent data) indicating that the destination IP address and/or destination port are not reachable.
SOCNOTCONN
The socket is not connected.
SOCNOTSOCK
The s parameter is not a valid socket descriptor.
SOCTIMEDOUT
The operation timed out. The socket is still available.
SOCWOULDBLOCK
The s parameter is in nonblocking mode and either no data is available to read or the traffic limit has been reached for the socket or application.

Programming considerations

  • This function applies only to connected sockets.
  • This function returns up to the number of bytes of data specified by the len parameter. If fewer than the number of bytes requested is available, the function returns the number currently available.
  • If data is not available for the sockets s, and s is in blocking mode, the read function blocks the caller until data arrives. If data is not available, and s is in nonblocking mode, read returns a -1 and sets sock_errno to SOCWOULDBLOCK.
  • The receive timeout value (the SO_RCVTIMEO setsockopt option) determines how long to wait for data to be received before the read function times out.
  • The receive low-water mark (the SO_RCVLOWAT setsockopt option) determines the minimum amount of data that must be received before the read function is completed. If the read function times out, any data that was received is returned to the application even if the amount of data received is less than the receive low-water mark value.
  • The read function cannot be issued if an activate_on_receipt, activate_on_receipt_with_length, activate_on_receipt_of_TCP_message, or tpf_read_TCP_message call is pending for the socket. These operations are mutually exclusive.

Examples

After the server accepts a client connection, it reads in a message from its client. 
#include <sys/socket.h>
⋮
int rc;
int newclient_sock;
int server_sock;
char recv_client_msg[100];
⋮
newclient_sock = accept(server_sock, (struct sockaddr *) 0, (int) 0);
rc = read(newclient_sock,recv_client_msg,sizeof(recv_client_msg));