recvfrom.3p (7403B)
- '\" et
- .TH RECVFROM "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
- .\"
- .SH PROLOG
- This manual page is part of the POSIX Programmer's Manual.
- The Linux implementation of this interface may differ (consult
- the corresponding Linux manual page for details of Linux behavior),
- or the interface may not be implemented on Linux.
- .\"
- .SH NAME
- recvfrom
- \(em receive a message from a socket
- .SH SYNOPSIS
- .LP
- .nf
- #include <sys/socket.h>
- .P
- ssize_t recvfrom(int \fIsocket\fP, void *restrict \fIbuffer\fP, size_t \fIlength\fP,
- int \fIflags\fP, struct sockaddr *restrict \fIaddress\fP,
- socklen_t *restrict \fIaddress_len\fP);
- .fi
- .SH DESCRIPTION
- The
- \fIrecvfrom\fR()
- function shall receive a message from a connection-mode or
- connectionless-mode socket. It is normally used with
- connectionless-mode sockets because it permits the application to
- retrieve the source address of received data.
- .P
- The
- \fIrecvfrom\fR()
- function takes the following arguments:
- .IP "\fIsocket\fR" 12
- Specifies the socket file descriptor.
- .IP "\fIbuffer\fR" 12
- Points to the buffer where the message should be stored.
- .IP "\fIlength\fR" 12
- Specifies the length in bytes of the buffer pointed to by the
- .IR buffer
- argument.
- .IP "\fIflags\fR" 12
- Specifies the type of message reception. Values of this argument are
- formed by logically OR'ing zero or more of the following values:
- .RS 12
- .IP MSG_PEEK 12
- Peeks at an incoming message. The data is treated as unread and the
- next
- \fIrecvfrom\fR()
- or similar function shall still return this data.
- .IP MSG_OOB 12
- Requests out-of-band data. The significance and semantics of
- out-of-band data are protocol-specific.
- .IP MSG_WAITALL 12
- On SOCK_STREAM sockets this requests that the function block until the
- full amount of data can be returned. The function may return the
- smaller amount of data if the socket is a message-based socket, if a
- signal is caught, if the connection is terminated, if MSG_PEEK was
- specified, or if an error is pending for the socket.
- .RE
- .IP "\fIaddress\fR" 12
- A null pointer, or points to a
- .BR sockaddr
- structure in which the sending address is to be stored. The length and
- format of the address depend on the address family of the socket.
- .IP "\fIaddress_len\fR" 12
- Either a null pointer, if
- .IR address
- is a null pointer, or a pointer to a
- .BR socklen_t
- object which on input specifies the length of the supplied
- .BR sockaddr
- structure, and on output specifies the length of the stored address.
- .P
- The
- \fIrecvfrom\fR()
- function shall return the length of the message written to the buffer
- pointed to by the
- .IR buffer
- argument. For message-based sockets, such as
- SOCK_RAW,
- SOCK_DGRAM, and SOCK_SEQPACKET, the entire message shall be read in a
- single operation. If a message is too long to fit in the supplied
- buffer, and MSG_PEEK is not set in the
- .IR flags
- argument, the excess bytes shall be discarded. For stream-based
- sockets, such as SOCK_STREAM, message boundaries shall be ignored. In
- this case, data shall be returned to the user as soon as it becomes
- available, and no data shall be discarded.
- .P
- If the MSG_WAITALL flag is not set, data shall be returned only up to
- the end of the first message.
- .P
- Not all protocols provide the source address for messages. If the
- .IR address
- argument is not a null pointer and the protocol provides the source
- address of messages, the source address of the received message shall
- be stored in the
- .BR sockaddr
- structure pointed to by the
- .IR address
- argument, and the length of this address shall be stored in the object
- pointed to by the
- .IR address_len
- argument.
- .P
- If the actual length of the address is greater than the length of the
- supplied
- .BR sockaddr
- structure, the stored address shall be truncated.
- .P
- If the
- .IR address
- argument is not a null pointer and the protocol does not provide the
- source address of messages, the value stored in the object pointed to
- by
- .IR address
- is unspecified.
- .P
- If no messages are available at the socket and O_NONBLOCK is not set on
- the socket's file descriptor,
- \fIrecvfrom\fR()
- shall block until a message arrives. If no messages are available at
- the socket and O_NONBLOCK is set on the socket's file descriptor,
- \fIrecvfrom\fR()
- shall fail and set
- .IR errno
- to
- .BR [EAGAIN]
- or
- .BR [EWOULDBLOCK] .
- .SH "RETURN VALUE"
- Upon successful completion,
- \fIrecvfrom\fR()
- shall return the length of the message in bytes. If no messages are
- available to be received and the peer has performed an orderly
- shutdown,
- \fIrecvfrom\fR()
- shall return 0. Otherwise, the function shall return \-1 and set
- .IR errno
- to indicate the error.
- .SH ERRORS
- The
- \fIrecvfrom\fR()
- function shall fail if:
- .TP
- .BR EAGAIN " or " EWOULDBLOCK
- .br
- The socket's file descriptor is marked O_NONBLOCK and no data is
- waiting to be received; or MSG_OOB is set and no out-of-band data is
- available and either the socket's file descriptor is marked O_NONBLOCK
- or the socket does not support blocking to await out-of-band data.
- .TP
- .BR EBADF
- The
- .IR socket
- argument is not a valid file descriptor.
- .TP
- .BR ECONNRESET
- A connection was forcibly closed by a peer.
- .TP
- .BR EINTR
- A signal interrupted
- \fIrecvfrom\fR()
- before any data was available.
- .TP
- .BR EINVAL
- The MSG_OOB flag is set and no out-of-band data is available.
- .TP
- .BR ENOTCONN
- A receive is attempted on a connection-mode socket that is not connected.
- .TP
- .BR ENOTSOCK
- The
- .IR socket
- argument does not refer to a socket.
- .TP
- .BR EOPNOTSUPP
- The specified flags are not supported for this socket type.
- .TP
- .BR ETIMEDOUT
- The connection timed out during connection establishment, or due to a
- transmission timeout on active connection.
- .P
- The
- \fIrecvfrom\fR()
- function may fail if:
- .TP
- .BR EIO
- An I/O error occurred while reading from or writing to the file
- system.
- .TP
- .BR ENOBUFS
- Insufficient resources were available in the system to perform the
- operation.
- .TP
- .BR ENOMEM
- Insufficient memory was available to fulfill the request.
- .LP
- .IR "The following sections are informative."
- .SH "EXAMPLES"
- None.
- .SH "APPLICATION USAGE"
- The
- \fIselect\fR()
- and
- \fIpoll\fR()
- functions can be used to determine when data is available to be
- received.
- .SH "RATIONALE"
- None.
- .SH "FUTURE DIRECTIONS"
- None.
- .SH "SEE ALSO"
- .IR "\fIpoll\fR\^(\|)",
- .IR "\fIpselect\fR\^(\|)",
- .IR "\fIread\fR\^(\|)",
- .IR "\fIrecv\fR\^(\|)",
- .IR "\fIrecvmsg\fR\^(\|)",
- .IR "\fIsend\fR\^(\|)",
- .IR "\fIsendmsg\fR\^(\|)",
- .IR "\fIsendto\fR\^(\|)",
- .IR "\fIshutdown\fR\^(\|)",
- .IR "\fIsocket\fR\^(\|)",
- .IR "\fIwrite\fR\^(\|)"
- .P
- The Base Definitions volume of POSIX.1\(hy2017,
- .IR "\fB<sys_socket.h>\fP"
- .\"
- .SH COPYRIGHT
- Portions of this text are reprinted and reproduced in electronic form
- from IEEE Std 1003.1-2017, Standard for Information Technology
- -- Portable Operating System Interface (POSIX), The Open Group Base
- Specifications Issue 7, 2018 Edition,
- Copyright (C) 2018 by the Institute of
- Electrical and Electronics Engineers, Inc and The Open Group.
- In the event of any discrepancy between this version and the original IEEE and
- The Open Group Standard, the original IEEE and The Open Group Standard
- is the referee document. The original Standard can be obtained online at
- http://www.opengroup.org/unix/online.html .
- .PP
- Any typographical or formatting errors that appear
- in this page are most likely
- to have been introduced during the conversion of the source files to
- man page format. To report such errors, see
- https://www.kernel.org/doc/man-pages/reporting_bugs.html .