![[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] / 43BSDTahoe / man / man2|
Return to recv.2 CVS log | Up to [CSRG BSD Unix] / 43BSDTahoe / man / man2 |
1.1 root 1: .\" Copyright (c) 1983 Regents of the University of California.
2: .\" All rights reserved. The Berkeley software License Agreement
3: .\" specifies the terms and conditions for redistribution.
4: .\"
5: .\" @(#)recv.2 6.5 (Berkeley) 7/21/87
6: .\"
7: .TH RECV 2 "July 21, 1987"
8: .UC 5
9: .SH NAME
10: recv, recvfrom, recvmsg \- receive a message from a socket
11: .SH SYNOPSIS
12: .nf
13: .ft B
14: #include <sys/types.h>
15: #include <sys/socket.h>
16: .PP
17: .ft B
18: cc = recv(s, buf, len, flags)
19: int cc, s;
20: char *buf;
21: int len, flags;
22: .PP
23: .ft B
24: cc = recvfrom(s, buf, len, flags, from, fromlen)
25: int cc, s;
26: char *buf;
27: int len, flags;
28: struct sockaddr *from;
29: int *fromlen;
30: .PP
31: .ft B
32: cc = recvmsg(s, msg, flags)
33: int cc, s;
34: struct msghdr *msg;
35: int flags;
36: .ft R
37: .SH DESCRIPTION
38: .IR Recv ,
39: .IR recvfrom ,
40: and
41: .IR recvmsg
42: are used to receive messages from a socket.
43: .PP
44: The
45: .I recv
46: call is normally used only on a
47: .I connected
48: socket (see
49: .IR connect (2)),
50: while
51: .I recvfrom
52: and
53: .I recvmsg
54: may be used to receive data on a socket whether
55: it is in a connected state or not.
56: .PP
57: If
58: .I from
59: is non-zero, the source address of the message is filled in.
60: .I Fromlen
61: is a value-result parameter, initialized to the size of
62: the buffer associated with
63: .IR from ,
64: and modified on return to indicate the actual size of the
65: address stored there.
66: The length of the message is returned in
67: .IR cc .
68: If a message is too long to fit in the supplied buffer,
69: excess bytes may be discarded depending on the type of socket
70: the message is received from (see
71: .IR socket (2)).
72: .PP
73: If no messages are available at the socket, the
74: receive call waits for a message to arrive, unless
75: the socket is nonblocking (see
76: .IR ioctl (2))
77: in which case a
78: .I cc
79: of \-1 is returned with the external variable errno
80: set to EWOULDBLOCK.
81: .PP
82: The
83: .IR select (2)
84: call may be used to determine when more data arrives.
85: .PP
86: The
87: .I flags
88: argument to a recv call is formed by
89: .IR or 'ing
90: one or more of the values,
91: .PP
92: .nf
93: .RS
94: .ta \w'#define\ \ 'u +\w'MSG_DONTROUTE\ \ \ 'u +\w'0x\0\0\0\ \ 'u
95: #define MSG_OOB 0x1 /* process out-of-band data */
96: #define MSG_PEEK 0x2 /* peek at incoming message */
97: .RE
98: .fi
99: .PP
100: The
101: .I recvmsg
102: call uses a
103: .I msghdr
104: structure to minimize the number of directly supplied parameters.
105: This structure has the following form, as defined in
106: .IR <sys/socket.h> :
107: .PP
108: .nf
109: .RS
110: .DT
111: struct msghdr {
112: caddr_t msg_name; /* optional address */
113: int msg_namelen; /* size of address */
114: struct iovec *msg_iov; /* scatter/gather array */
115: int msg_iovlen; /* # elements in msg_iov */
116: caddr_t msg_accrights; /* access rights sent/received */
117: int msg_accrightslen;
118: };
119: .RE
120: .fi
121: .PP
122: Here
123: .I msg_name
124: and
125: .I msg_namelen
126: specify the destination address if the socket is unconnected;
127: .I msg_name
128: may be given as a null pointer if no names are desired or required.
129: The
130: .I msg_iov
131: and
132: .I msg_iovlen
133: describe the scatter gather locations, as described in
134: .IR read (2).
135: A buffer to receive any access rights sent along with the message is specified
136: in
137: .IR msg_accrights ,
138: which has length
139: .IR msg_accrightslen .
140: Access rights are currently limited to file descriptors,
141: which each occupy the size of an
142: .BR int .
143: If access rights are not being transferred, the
144: .I msg_accrights
145: field should be set to NULL.
146: .SH "RETURN VALUE
147: These calls return the number of bytes received, or \-1
148: if an error occurred.
149: .SH ERRORS
150: The calls fail if:
151: .TP 20
152: [EBADF]
153: The argument \fIs\fP is an invalid descriptor.
154: .TP 20
155: [ENOTSOCK]
156: The argument \fIs\fP is not a socket.
157: .TP 20
158: [EWOULDBLOCK]
159: The socket is marked non-blocking and the receive operation
160: would block.
161: .TP 20
162: [EINTR]
163: The receive was interrupted by delivery of a signal before
164: any data was available for the receive.
165: .TP 20
166: [EFAULT]
167: The data was specified to be received into a non-existent
168: or protected part of the process address space.
169: .SH SEE ALSO
170: 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.