![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to recv.2 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / lib / libc / sys|
Return to recv.2 CVS log | Up to [CSRG BSD Unix] / 43BSDReno / lib / libc / sys |
1.1 root 1: .\" Copyright (c) 1983, 1990 The Regents of the University of California.
2: .\" All rights reserved.
3: .\"
4: .\" Redistribution and use in source and binary forms are permitted
5: .\" provided that: (1) source distributions retain this entire copyright
6: .\" notice and comment, and (2) distributions including binaries display
7: .\" the following acknowledgement: ``This product includes software
8: .\" developed by the University of California, Berkeley and its contributors''
9: .\" in the documentation or other materials provided with the distribution
10: .\" and in all advertising materials mentioning features or use of this
11: .\" software. Neither the name of the University nor the names of its
12: .\" contributors may be used to endorse or promote products derived
13: .\" from this software without specific prior written permission.
14: .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
15: .\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
16: .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
17: .\"
18: .\" @(#)recv.2 6.8 (Berkeley) 5/30/90
19: .\"
20: .TH RECV 2 "May 30, 1990"
21: .UC 5
22: .SH NAME
23: recv, recvfrom, recvmsg \- receive a message from a socket
24: .SH SYNOPSIS
25: .nf
26: .ft B
27: #include <sys/types.h>
28: #include <sys/socket.h>
29: .PP
30: .ft B
31: cc = recv(s, buf, len, flags)
32: int cc, s;
33: char *buf;
34: int len, flags;
35: .PP
36: .ft B
37: cc = recvfrom(s, buf, len, flags, from, fromlen)
38: int cc, s;
39: char *buf;
40: int len, flags;
41: struct sockaddr *from;
42: int *fromlen;
43: .PP
44: .ft B
45: cc = recvmsg(s, msg, flags)
46: int cc, s;
47: struct msghdr *msg;
48: int flags;
49: .ft R
50: .SH DESCRIPTION
51: .IR Recvfrom ,
52: and
53: .IR recvmsg
54: are used to receive messages from a socket,
55: and may be used to receive data on a socket whether
56: it is in a connected state or not.
57: .PP
58: If
59: .I from
60: is non-zero, the source address of the message is filled in.
61: .I Fromlen
62: is a value-result parameter, initialized to the size of
63: the buffer associated with
64: .IR from ,
65: and modified on return to indicate the actual size of the
66: address stored there.
67: .PP
68: The
69: .I recv
70: call is normally used only on a
71: .I connected
72: socket (see
73: .IR connect (2))
74: and is identitical to
75: .I recfrom
76: with a zero-valued
77: .I fromlen
78: parameter.
79: As it is redundant, it may not be supported in future releases.
80: .PP
81: The length of the message is returned in
82: .IR cc .
83: If a message is too long to fit in the supplied buffer,
84: excess bytes may be discarded depending on the type of socket
85: the message is received from (see
86: .IR socket (2)).
87: .PP
88: If no messages are available at the socket, the
89: receive call waits for a message to arrive, unless
90: the socket is nonblocking (see
91: .IR ioctl (2))
92: in which case a
93: .I cc
94: of \-1 is returned with the external variable errno
95: set to EWOULDBLOCK.
96: .PP
97: The
98: .IR select (2)
99: call may be used to determine when more data arrives.
100: .PP
101: The
102: .I flags
103: argument to a recv call is formed by
104: .IR or 'ing
105: one or more of the values,
106: .PP
107: .nf
108: .RS
109: .ta \w'#define\ \ 'u +\w'MSG_DONTROUTE\ \ \ 'u +\w'0x\0\0\0\ \ 'u
110: #define MSG_OOB 0x1 /* process out-of-band data */
111: #define MSG_PEEK 0x2 /* peek at incoming message */
112: #define MSG_DONTROUTE 0x4 /* send without using routing tables */
113: #define MSG_EOR 0x8 /* data completes record */
114: #define MSG_TRUNC 0x10 /* data discarded before delivery */
115: #define MSG_CTRUNC 0x20 /* control data lost before delivery */
116: .RE
117: .fi
118: .PP
119: The
120: .I recvmsg
121: call uses a
122: .I msghdr
123: structure to minimize the number of directly supplied parameters.
124: This structure has the following form, as defined in
125: .IR <sys/socket.h> :
126: .PP
127: .nf
128: .ta \w'struct 'u +\w'caddr_t 'u +\w'msg_controllen 'u
129: struct msghdr {
130: caddr_t msg_name; /* optional address */
131: u_int msg_namelen; /* size of address */
132: struct iovec *msg_iov; /* scatter/gather array */
133: u_int msg_iovlen; /* # elements in msg_iov */
134: caddr_t msg_control; /* ancillary data, see below */
135: u_int msg_controllen; /* ancillary data buffer len */
136: int msg_flags; /* flags on received message */
137: };
138: .fi
139: .PP
140: Here
141: .I msg_name
142: and
143: .I msg_namelen
144: specify the destination address if the socket is unconnected;
145: .I msg_name
146: may be given as a null pointer if no names are desired or required.
147: The
148: .I msg_iov
149: and
150: .I msg_iovlen
151: describe the scatter gather locations, as described in
152: .IR read (2).
153: .IR msg_control ,
154: which has length
155: .IR msg_controllen .
156: This is a buffer for other protocol control related messages
157: or other miscellaneous ancillary data.
158: The messages are of the form:
159: .PP
160: .nf
161: .ta \w'struct 'u +\w'u_char 'u +\w'msg_controllen 'u
162: struct cmsghdr {
163: u_int cmsg_len; /* data byte count, including hdr */
164: int cmsg_level; /* originating protocol */
165: int cmsg_type; /* protocol-specific type */
166: /* followed by
167: u_char cmsg_data[]; */
168: };
169: .fi
170: .RE
171: As an example, one could use this to learn of changes in the data-stream
172: in XNS/SPP, or in ISO, to obtain user-connection-request data by requesting
173: a recvmsg with no uio provided immediately after an
174: .IR accept (),
175: thought of here in the sense of get-next-connection-request without
176: an implicit connection confirmation.
177: .PP
178: Open file descriptors are now passed as ancillary data for AF_UNIX
179: domain sockets, with cmsg_level being SOL_SOCKET and cmsg_type being
180: SCM_RIGHTS.
181: .PP
182: .I msg_flags
183: is set on return in a way that may include some of the same values specified
184: for the flags parameter to a recv system call.
185: The returned values MSG_EOR indicates end-of-record, MSG_TRUNC indicates that
186: some trailing datagram data was discarded, MSG_CTRUNC indicates that some
187: control data was discarded due to lack of space.
188: MSG_OOB is returned to indicate that expedited data was received.
189: .PP
190: .SH "RETURN VALUE"
191: These calls return the number of bytes received, or \-1
192: if an error occurred.
193: .SH ERRORS
194: The calls fail if:
195: .TP 20
196: [EBADF]
197: The argument \fIs\fP is an invalid descriptor.
198: .TP 20
199: [ENOTSOCK]
200: The argument \fIs\fP is not a socket.
201: .TP 20
202: [EWOULDBLOCK]
203: The socket is marked non-blocking and the receive operation
204: would block.
205: .TP 20
206: [EINTR]
207: The receive was interrupted by delivery of a signal before
208: any data was available for the receive.
209: .TP 20
210: [EFAULT]
211: The data was specified to be received into a non-existent
212: or protected part of the process address space.
213: .SH SEE ALSO
214: fcntl(2), read(2), send(2), select(2), getsockopt(2), socket(2)
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.