BSD 4_3_Reno release

[unix-history] / usr / src / lib / libc / sys / recv.2

diff --git a/usr/src/lib/libc/sys/recv.2 b/usr/src/lib/libc/sys/recv.2
index 0d5787f..862232a 100644 (file)
--- a/usr/src/lib/libc/sys/recv.2
+++ b/usr/src/lib/libc/sys/recv.2
@@ -1,10 +1,23 @@
-.\" Copyright (c) 1983 Regents of the University of California.
-.\" All rights reserved.  The Berkeley software License Agreement
-.\" specifies the terms and conditions for redistribution.
+.\" Copyright (c) 1983, 1990 The Regents of the University of California.
+.\" All rights reserved.

 .\"
 .\"

-.\"    @(#)recv.2      6.1 (Berkeley) %G%
+.\" Redistribution and use in source and binary forms are permitted
+.\" provided that: (1) source distributions retain this entire copyright
+.\" notice and comment, and (2) distributions including binaries display
+.\" the following acknowledgement:  ``This product includes software
+.\" developed by the University of California, Berkeley and its contributors''
+.\" in the documentation or other materials provided with the distribution
+.\" and in all advertising materials mentioning features or use of this
+.\" software. Neither the name of the University nor the names of its
+.\" contributors may be used to endorse or promote products derived
+.\" from this software without specific prior written permission.
+.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
+.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.

 .\"
 .\"

-.TH RECV 2 ""
+.\"    @(#)recv.2      6.8 (Berkeley) 5/30/90
+.\"
+.TH RECV 2 "May 30, 1990"

 .UC 5
 .SH NAME
 recv, recvfrom, recvmsg \- receive a message from a socket
 .UC 5
 .SH NAME
 recv, recvfrom, recvmsg \- receive a message from a socket


@@ -31,27 +44,15 @@ int *fromlen;
 .ft B
 cc = recvmsg(s, msg, flags)
 int cc, s;
 .ft B
 cc = recvmsg(s, msg, flags)
 int cc, s;

-struct msghdr msg[];
+struct msghdr *msg;

 int flags;
 .ft R
 .SH DESCRIPTION
 int flags;
 .ft R
 .SH DESCRIPTION

-.IR Recv ,
-.IR recvfrom ,
+.IR Recvfrom ,

 and
 .IR recvmsg
 and
 .IR recvmsg

-are used to receive messages from a socket.
-.PP
-The 
-.I recv
-call may be used only on a 
-.I connected
-socket (see
-.IR connect (2)),
-while 
-.I recvfrom
-and 
-.I recvmsg
-may be used to receive data on a socket whether
+are used to receive messages from a socket,
+and may be used to receive data on a socket whether

 it is in a connected state or not.
 .PP
 If
 it is in a connected state or not.
 .PP
 If


@@ -63,12 +64,26 @@ the buffer associated with
 .IR from ,
 and modified on return to indicate the actual size of the
 address stored there.
 .IR from ,
 and modified on return to indicate the actual size of the
 address stored there.

+.PP
+The 
+.I recv
+call is normally used only on a 
+.I connected
+socket (see
+.IR connect (2))
+and is identitical to
+.I recfrom
+with a zero-valued
+.I fromlen
+parameter.
+As it is redundant, it may not be supported in future releases.
+.PP

 The length of the message is returned in
 .IR cc .
 If a message is too long to fit in the supplied buffer,
 excess bytes may be discarded depending on the type of socket
 The length of the message is returned in
 .IR cc .
 If a message is too long to fit in the supplied buffer,
 excess bytes may be discarded depending on the type of socket

-the message is received from; see
-.IR socket (2).
+the message is received from (see
+.IR socket (2)).

 .PP
 If no messages are available at the socket, the
 receive call waits for a message to arrive, unless
 .PP
 If no messages are available at the socket, the
 receive call waits for a message to arrive, unless


@@ -85,15 +100,19 @@ call may be used to determine when more data arrives.
 .PP
 The
 .I flags
 .PP
 The
 .I flags

-argument to a send call is formed by 
+argument to a recv call is formed by 

 .IR or 'ing
 one or more of the values,
 .PP
 .nf
 .RS
 .IR or 'ing
 one or more of the values,
 .PP
 .nf
 .RS

-.DT
+.ta \w'#define\ \ 'u +\w'MSG_DONTROUTE\ \ \ 'u +\w'0x\0\0\0\ \ 'u

 #define        MSG_OOB 0x1     /* process out-of-band data */
 #define        MSG_PEEK        0x2     /* peek at incoming message */
 #define        MSG_OOB 0x1     /* process out-of-band data */
 #define        MSG_PEEK        0x2     /* peek at incoming message */

+#define        MSG_DONTROUTE   0x4     /* send without using routing tables */
+#define        MSG_EOR 0x8     /* data completes record */
+#define        MSG_TRUNC       0x10    /* data discarded before delivery */
+#define        MSG_CTRUNC      0x20    /* control data lost before delivery */

 .RE
 .fi
 .PP
 .RE
 .fi
 .PP


@@ -106,17 +125,16 @@ This structure has the following form, as defined in
 .IR <sys/socket.h> :
 .PP
 .nf
 .IR <sys/socket.h> :
 .PP
 .nf

-.RS
-.DT
+.ta \w'struct  'u +\w'caddr_t   'u +\w'msg_controllen    'u

 struct msghdr {
 struct msghdr {

-       caddr_t msg_name;               /* optional address */
-       int     msg_namelen;            /* size of address */
-       struct  iovec *msg_iov;         /* scatter/gather array */
-       int     msg_iovlen;             /* # elements in msg_iov */
-       caddr_t msg_accrights;          /* access rights sent/received */
-       int     msg_accrightslen;
+       caddr_t msg_name;       /* optional address */
+       u_int   msg_namelen;    /* size of address */
+       struct  iovec *msg_iov; /* scatter/gather array */
+       u_int   msg_iovlen;     /* # elements in msg_iov */
+       caddr_t msg_control;    /* ancillary data, see below */
+       u_int   msg_controllen; /* ancillary data buffer len */
+       int     msg_flags;              /* flags on received message */

 };
 };

-.RE

 .fi
 .PP
 Here
 .fi
 .PP
 Here


@@ -126,18 +144,50 @@ and
 specify the destination address if the socket is unconnected;
 .I msg_name
 may be given as a null pointer if no names are desired or required.
 specify the destination address if the socket is unconnected;
 .I msg_name
 may be given as a null pointer if no names are desired or required.

-The 
+The

 .I msg_iov
 and
 .I msg_iovlen
 describe the scatter gather locations, as described in
 .IR read (2).
 .I msg_iov
 and
 .I msg_iovlen
 describe the scatter gather locations, as described in
 .IR read (2).

-Access rights to be sent along with the message are specified
-in 
-.IR msg_accrights ,
+.IR msg_control ,

 which has length
 which has length

-.IR msg_accrightslen .
-.SH "RETURN VALUE
+.IR msg_controllen .
+This is a buffer for other protocol control related messages
+or other miscellaneous ancillary data.
+The messages are of the form:
+.PP
+.nf
+.ta \w'struct  'u +\w'u_char   'u +\w'msg_controllen    'u
+struct cmsghdr {
+       u_int   cmsg_len;       /* data byte count, including hdr */
+       int     cmsg_level;     /* originating protocol */
+       int     cmsg_type;      /* protocol-specific type */
+/* followed by
+       u_char  cmsg_data[]; */
+};
+.fi
+.RE
+As an example, one could use this to learn of changes in the data-stream
+in XNS/SPP, or in ISO, to obtain user-connection-request data by requesting
+a recvmsg with no uio provided immediately after an
+.IR accept (),
+thought of here in the sense of get-next-connection-request without
+an implicit connection confirmation.
+.PP
+Open file descriptors are now passed as ancillary data for AF_UNIX
+domain sockets, with cmsg_level being SOL_SOCKET and  cmsg_type being
+SCM_RIGHTS.
+.PP
+.I msg_flags
+is set on return in a way that may include some of the same values specified
+for the flags parameter to a recv system call.
+The returned values MSG_EOR indicates end-of-record, MSG_TRUNC indicates that
+some trailing datagram data was discarded, MSG_CTRUNC indicates that some
+control data was discarded due to lack of space.
+MSG_OOB is returned to indicate that expedited data was received.
+.PP
+.SH "RETURN VALUE"

 These calls return the number of bytes received, or \-1
 if an error occurred.
 .SH ERRORS
 These calls return the number of bytes received, or \-1
 if an error occurred.
 .SH ERRORS


@@ -161,4 +211,4 @@ any data was available for the receive.
 The data was specified to be received into a non-existent
 or protected part of the process address space.
 .SH SEE ALSO
 The data was specified to be received into a non-existent
 or protected part of the process address space.
 .SH SEE ALSO

-read(2), send(2), socket(2)
+fcntl(2), read(2), send(2), select(2), getsockopt(2), socket(2)