%SS_RECV

Receive bytes from a socket

status = %SS_RECV(socket, buf, bytes_received[, SS_MSG_PEEK])

Return value

status

Returns SS_SUCCESS (0) or one of the errors in Error codes returned by %SS_RECV below. (n)

Arguments

socket

A descriptor of an open socket created by %SS_SOCKET. (i4)

buf

Buffer returned with the incoming data. (a)

bytes_received

Returned with the number of bytes received and placed into buf. (i4)

SS_MSG_PEEK

(optional) Peek into the data that is next in line to be received without removing it from the system’s buffers. (n)

Discussion

%SS_RECV reads incoming data from a connected stream socket or from a datagram socket with an established peer address. (To receive data from a datagram socket without an established peer address, use %SS_RECVFROM.)

For connected stream sockets, %SS_RECV returns all available data up to the size of buf. Although you can call %SS_RECV in a loop to receive all bytes sent from the peer stream socket, instead we recommend you use %SS_RECVBUF, which performs the loop for you.

Unlike %SS_RECVBUF, however, you can pass the SS_MSG_PEEK flag to %SS_RECV to peek into the data to be received without actually removing that data from the system’s buffers.

For datagram sockets, %SS_RECV extracts data from the first queued datagram, up to the size of buf. If the datagram is larger than buf, the overflow data is lost, and %SS_RECV returns the error SS_EMSGSIZE.

If no incoming data is available at the socket, %SS_RECV blocks until data arrives.

Error codes returned by %SS_RECV

See the Socket Errors table for additional information about these errors.

SS_EBADF

SS_ECONNABORTED

SS_ECONNRESET

SS_EINTR

SS_EINVAL

SS_EMSGSIZE

SS_ENETDOWN

SS_ENOBUFS

SS_ENOTCONN

SS_ENOTSOCK

SS_EUNKNOWN

SS_NOTINITIALISED