![[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 [Power 6/32 Unix Tahoe 4.2BSD] / cci / usr / src / man / man2|
Return to recv.2 CVS log | Up to [Power 6/32 Unix Tahoe 4.2BSD] / cci / usr / src / man / man2 |
1.1 root 1: .TH RECV 2 "7 July 1983"
2: .UC 4
3: .SH NAME
4: recv, recvfrom, recvmsg \- receive a message from a socket
5: .SH SYNOPSIS
6: .nf
7: .ft B
8: #include <sys/types.h>
9: #include <sys/socket.h>
10: .PP
11: .ft B
12: cc = recv(s, buf, len, flags)
13: int cc, s;
14: char *buf;
15: int len, flags;
16: .PP
17: .ft B
18: cc = recvfrom(s, buf, len, flags, from, fromlen)
19: int cc, s;
20: char *buf;
21: int len, flags;
22: struct sockaddr *from;
23: int *fromlen;
24: .PP
25: .ft B
26: cc = recvmsg(s, msg, flags)
27: int cc, s;
28: struct msghdr msg[];
29: int flags;
30: .ft R
31: .SH DESCRIPTION
32: .IR Recv ,
33: .IR recvfrom ,
34: and
35: .IR recvmsg
36: are used to receive messages from a socket.
37: .PP
38: The
39: .I recv
40: call may be used only on a
41: .I connected
42: socket (see
43: .IR connect (2)),
44: while
45: .I recvfrom
46: and
47: .I recvmsg
48: may be used to receive data on a socket whether
49: it is in a connected state or not.
50: .PP
51: If
52: .I from
53: is non-zero, the source address of the message is filled in.
54: .I Fromlen
55: is a value-result parameter, initialized to the size of
56: the buffer associated with
57: .IR from ,
58: and modified on return to indicate the actual size of the
59: address stored there.
60: The length of the message is returned in
61: .IR cc .
62: If a message is too long to fit in the supplied buffer,
63: excess bytes may be discarded depending on the type of socket
64: the message is received from; see
65: .IR socket (2).
66: .PP
67: If no messages are available at the socket, the
68: receive call waits for a message to arrive, unless
69: the socket is nonblocking (see
70: .IR ioctl (2))
71: in which case a
72: .I cc
73: of \-1 is returned with the external variable errno
74: set to EWOULDBLOCK.
75: .PP
76: The
77: .IR select (2)
78: call may be used to determine when more data arrives.
79: .PP
80: The
81: .I flags
82: argument to a receive call is formed by
83: .IR or 'ing
84: one or more of the values,
85: .PP
86: .nf
87: .RS
88: .DT
89: #define MSG_PEEK 0x1 /* peek at incoming message */
90: #define MSG_OOB 0x2 /* process out-of-band data */
91: .RE
92: .fi
93: .PP
94: The
95: .I recvmsg
96: call uses a
97: .I msghdr
98: structure to minimize the number of directly supplied parameters,
99: and to receive file descriptors from another process (Unix domain only).
100: This structure has the following form, as defined in
101: .IR <sys/socket.h> :
102: .PP
103: .nf
104: .RS
105: .DT
106: struct msghdr {
107: caddr_t msg_name; /* optional address */
108: int msg_namelen; /* size of address */
109: struct iov *msg_iov; /* scatter/gather array */
110: int msg_iovlen; /* # elements in msg_iov */
111: caddr_t msg_accrights; /* access rights sent/received */
112: int msg_accrightslen;
113: };
114: .RE
115: .fi
116: .PP
117: Here
118: .I msg_name
119: and
120: .I msg_namelen
121: specify the destination address if the socket is unconnected;
122: .I msg_name
123: may be given as a null pointer if no names are desired or required.
124: The
125: .I msg_iov
126: and
127: .I msg_iovlen
128: describe the scatter gather locations, as described in
129: .IR read (2).
130: Access rights to be sent along with the message are specified
131: in
132: .IR msg_accrights ,
133: which has length
134: .IR msg_accrightslen .
135: .LP
136: .I RECEIVING OUT-OF-BAND DATA IN INTERNET DOMAIN
137: .LP
138: When out-of-band data arrives at a socket, the system could signal
139: a group of processes, or a specific process, or no process at all.
140: .RS
141:
142: - If the socket's process group id is
143: .I positive,
144: the system signals all process in that process group.
145:
146: - If the socket's process group id is
147: .I negative,
148: the system only signals the process whose process id is the absolute
149: value of the socket's process group id.
150:
151: - If the socket's process group id is 0 (the default value),
152: the system does not signal any process.
153:
154: .RE
155: To assign a socket process group id, use the
156: .I ioctl(2)
157: system call with the command
158: .I SIOCSPGRP.
159: .LP
160: .I RECEIVING FILE DESCRIPTORS IN UNIX DOMAIN
161: .LP
162: In Unix domain, process
163: .I A
164: can open a set of files, then send these file descriptors to process
165: .I B.
166: Process
167: .I B
168: then can read or write those files which were already opened (and
169: perhaps accessible only) by
170: .I A.
171: .LP
172: The active process stores the file descriptors
173: in the field
174: .I msg_accrights
175: of the structure
176: .I msghdr,
177: and use the system call
178: .I sendmsg(2)
179: to send the descriptors. The passive process then can receive the
180: descriptors via the system call
181: .I recvmsg(2);
182: the descriptors are returned in the field
183: .I msg_accrights
184: of
185: .I msghdr.
186: .SH "RETURN VALUE
187: These calls return the number of bytes received, or \-1
188: if an error occurred.
189: .SH ERRORS
190: The calls fail if:
191: .TP 20
192: [EBADF]
193: The argument \fIs\fP is an invalid descriptor.
194: .TP 20
195: [ENOTSOCK]
196: The argument \fIs\fP is not a socket.
197: .TP 20
198: [EWOULDBLOCK]
199: The socket is marked non-blocking and the receive operation
200: would block.
201: .TP 20
202: [EINTR]
203: The receive was interrupted by delivery of a signal before
204: any data was available for the receive.
205: .TP 20
206: [EFAULT]
207: The data was specified to be received into a non-existent
208: or protected part of the process address space.
209: .SH SEE ALSO
210: read(2), send(2), socket(2). See also bind(2) for address formats
211: in different communication domains.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.