1 # SOME DESCRIPTIVE TITLE
2 # Copyright (C) YEAR Free Software Foundation, Inc.
3 # This file is distributed under the same license as the PACKAGE package.
4 # FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
9 "Project-Id-Version: PACKAGE VERSION\n"
10 "POT-Creation-Date: 2015-01-04 23:49+0900\n"
11 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
12 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
13 "Language-Team: LANGUAGE <LL@li.org>\n"
16 "Content-Type: text/plain; charset=UTF-8\n"
17 "Content-Transfer-Encoding: 8bit\n"
20 #: build/C/man2/accept.2:41
26 #: build/C/man2/accept.2:41
32 #: build/C/man2/accept.2:41 build/C/man2/bind.2:68 build/C/man2/connect.2:67 build/C/man2/getsockname.2:40 build/C/man2/getsockopt.2:44 build/C/man2/listen.2:45 build/C/man2/recv.2:41 build/C/man2/recvmmsg.2:31 build/C/man2/select.2:38 build/C/man2/select_tut.2:32 build/C/man2/send.2:40 build/C/man2/sendmmsg.2:28 build/C/man3/sockatmark.3:25 build/C/man2/socket.2:43 build/C/man7/socket.7:58 build/C/man2/socketcall.2:25 build/C/man2/socketpair.2:42
38 #: build/C/man2/accept.2:41 build/C/man2/bind.2:68 build/C/man3/bindresvport.3:30 build/C/man2/connect.2:67 build/C/man3/getifaddrs.3:36 build/C/man2/getsockname.2:40 build/C/man2/getsockopt.2:44 build/C/man3/if_nameindex.3:26 build/C/man3/if_nametoindex.3:25 build/C/man2/listen.2:45 build/C/man2/recv.2:41 build/C/man2/recvmmsg.2:31 build/C/man2/select.2:38 build/C/man2/select_tut.2:32 build/C/man2/send.2:40 build/C/man2/sendmmsg.2:28 build/C/man3/sockatmark.3:25 build/C/man2/socket.2:43 build/C/man7/socket.7:58 build/C/man2/socketcall.2:25 build/C/man2/socketpair.2:42
40 msgid "Linux Programmer's Manual"
44 #: build/C/man2/accept.2:42 build/C/man2/bind.2:69 build/C/man3/bindresvport.3:31 build/C/man2/connect.2:68 build/C/man3/getifaddrs.3:37 build/C/man2/getsockname.2:41 build/C/man2/getsockopt.2:45 build/C/man3/if_nameindex.3:27 build/C/man3/if_nametoindex.3:26 build/C/man2/listen.2:46 build/C/man2/recv.2:42 build/C/man2/recvmmsg.2:32 build/C/man2/select.2:39 build/C/man2/select_tut.2:33 build/C/man2/send.2:41 build/C/man2/sendmmsg.2:29 build/C/man3/sockatmark.3:26 build/C/man2/socket.2:44 build/C/man7/socket.7:59 build/C/man2/socketcall.2:26 build/C/man2/socketpair.2:43
50 #: build/C/man2/accept.2:44
51 msgid "accept, accept4 - accept a connection on a socket"
55 #: build/C/man2/accept.2:44 build/C/man2/bind.2:71 build/C/man3/bindresvport.3:33 build/C/man2/connect.2:70 build/C/man3/getifaddrs.3:39 build/C/man2/getsockname.2:43 build/C/man2/getsockopt.2:47 build/C/man3/if_nameindex.3:29 build/C/man3/if_nametoindex.3:29 build/C/man2/listen.2:48 build/C/man2/recv.2:44 build/C/man2/recvmmsg.2:34 build/C/man2/select.2:42 build/C/man2/select_tut.2:36 build/C/man2/send.2:43 build/C/man2/sendmmsg.2:31 build/C/man3/sockatmark.3:28 build/C/man2/socket.2:46 build/C/man7/socket.7:61 build/C/man2/socketcall.2:28 build/C/man2/socketpair.2:45
61 #: build/C/man2/accept.2:48 build/C/man2/bind.2:75
64 "B<#include E<lt>sys/types.hE<gt>> /* See NOTES */\n"
65 "B<#include E<lt>sys/socket.hE<gt>>\n"
69 #: build/C/man2/accept.2:50
72 "B<int accept(int >I<sockfd>B<, struct sockaddr *>I<addr>B<, socklen_t "
77 #: build/C/man2/accept.2:53
80 "B<#define _GNU_SOURCE> /* See feature_test_macros(7) */\n"
81 "B<#include E<lt>sys/socket.hE<gt>>\n"
85 #: build/C/man2/accept.2:56
88 "B<int accept4(int >I<sockfd>B<, struct sockaddr *>I<addr>B<,>\n"
89 "B< socklen_t *>I<addrlen>B<, int >I<flags>B<);>\n"
93 #: build/C/man2/accept.2:57 build/C/man2/bind.2:79 build/C/man3/bindresvport.3:40 build/C/man2/connect.2:79 build/C/man3/getifaddrs.3:48 build/C/man2/getsockname.2:50 build/C/man2/getsockopt.2:58 build/C/man3/if_nameindex.3:36 build/C/man3/if_nametoindex.3:37 build/C/man2/listen.2:56 build/C/man2/recv.2:59 build/C/man2/recvmmsg.2:44 build/C/man2/select.2:81 build/C/man2/select_tut.2:75 build/C/man2/send.2:58 build/C/man2/sendmmsg.2:40 build/C/man3/sockatmark.3:42 build/C/man2/socket.2:52 build/C/man7/socket.7:65 build/C/man2/socketcall.2:30 build/C/man2/socketpair.2:52
99 #: build/C/man2/accept.2:72
101 "The B<accept>() system call is used with connection-based socket types "
102 "(B<SOCK_STREAM>, B<SOCK_SEQPACKET>). It extracts the first connection "
103 "request on the queue of pending connections for the listening socket, "
104 "I<sockfd>, creates a new connected socket, and returns a new file descriptor "
105 "referring to that socket. The newly created socket is not in the listening "
106 "state. The original socket I<sockfd> is unaffected by this call."
110 #: build/C/man2/accept.2:81
112 "The argument I<sockfd> is a socket that has been created with B<socket>(2), "
113 "bound to a local address with B<bind>(2), and is listening for connections "
114 "after a B<listen>(2)."
118 #: build/C/man2/accept.2:99
120 "The argument I<addr> is a pointer to a I<sockaddr> structure. This "
121 "structure is filled in with the address of the peer socket, as known to the "
122 "communications layer. The exact format of the address returned I<addr> is "
123 "determined by the socket's address family (see B<socket>(2) and the "
124 "respective protocol man pages). When I<addr> is NULL, nothing is filled in; "
125 "in this case, I<addrlen> is not used, and should also be NULL."
129 #: build/C/man2/accept.2:107
131 "The I<addrlen> argument is a value-result argument: the caller must "
132 "initialize it to contain the size (in bytes) of the structure pointed to by "
133 "I<addr>; on return it will contain the actual size of the peer address."
137 #: build/C/man2/accept.2:112 build/C/man2/getsockname.2:67
139 "The returned address is truncated if the buffer provided is too small; in "
140 "this case, I<addrlen> will return a value greater than was supplied to the "
145 #: build/C/man2/accept.2:125
147 "If no pending connections are present on the queue, and the socket is not "
148 "marked as nonblocking, B<accept>() blocks the caller until a connection is "
149 "present. If the socket is marked nonblocking and no pending connections are "
150 "present on the queue, B<accept>() fails with the error B<EAGAIN> or "
155 #: build/C/man2/accept.2:139
157 "In order to be notified of incoming connections on a socket, you can use "
158 "B<select>(2) or B<poll>(2). A readable event will be delivered when a new "
159 "connection is attempted and you may then call B<accept>() to get a socket "
160 "for that connection. Alternatively, you can set the socket to deliver "
161 "B<SIGIO> when activity occurs on a socket; see B<socket>(7) for details."
165 #: build/C/man2/accept.2:152
167 "For certain protocols which require an explicit confirmation, such as "
168 "DECNet, B<accept>() can be thought of as merely dequeuing the next "
169 "connection request and not implying confirmation. Confirmation can be "
170 "implied by a normal read or write on the new file descriptor, and rejection "
171 "can be implied by closing the new socket. Currently only DECNet has these "
172 "semantics on Linux."
176 #: build/C/man2/accept.2:162
178 "If I<flags> is 0, then B<accept4>() is the same as B<accept>(). The "
179 "following values can be bitwise ORed in I<flags> to obtain different "
184 #: build/C/man2/accept.2:162 build/C/man2/socket.2:160
186 msgid "B<SOCK_NONBLOCK>"
190 #: build/C/man2/accept.2:170 build/C/man2/socket.2:168
192 "Set the B<O_NONBLOCK> file status flag on the new open file description. "
193 "Using this flag saves extra calls to B<fcntl>(2) to achieve the same "
198 #: build/C/man2/accept.2:170 build/C/man2/socket.2:168
200 msgid "B<SOCK_CLOEXEC>"
204 #: build/C/man2/accept.2:180 build/C/man2/socket.2:178
206 "Set the close-on-exec (B<FD_CLOEXEC>) flag on the new file descriptor. See "
207 "the description of the B<O_CLOEXEC> flag in B<open>(2) for reasons why this "
212 #: build/C/man2/accept.2:180 build/C/man2/bind.2:152 build/C/man3/bindresvport.3:67 build/C/man2/connect.2:127 build/C/man3/getifaddrs.3:142 build/C/man2/getsockname.2:67 build/C/man2/getsockopt.2:131 build/C/man3/if_nameindex.3:71 build/C/man3/if_nametoindex.3:54 build/C/man2/listen.2:82 build/C/man2/recv.2:408 build/C/man2/recvmmsg.2:148 build/C/man2/select.2:300 build/C/man2/select_tut.2:485 build/C/man2/send.2:294 build/C/man2/sendmmsg.2:119 build/C/man3/sockatmark.3:51 build/C/man2/socket.2:310 build/C/man2/socketpair.2:69
218 #: build/C/man2/accept.2:187
220 "On success, these system calls return a nonnegative integer that is a "
221 "descriptor for the accepted socket. On error, -1 is returned, and I<errno> "
222 "is set appropriately."
226 #: build/C/man2/accept.2:187
228 msgid "Error handling"
232 #: build/C/man2/accept.2:214
234 "Linux B<accept>() (and B<accept4>()) passes already-pending network errors "
235 "on the new socket as an error code from B<accept>(). This behavior differs "
236 "from other BSD socket implementations. For reliable operation the "
237 "application should detect the network errors defined for the protocol after "
238 "B<accept>() and treat them like B<EAGAIN> by retrying. In the case of "
239 "TCP/IP, these are B<ENETDOWN>, B<EPROTO>, B<ENOPROTOOPT>, B<EHOSTDOWN>, "
240 "B<ENONET>, B<EHOSTUNREACH>, B<EOPNOTSUPP>, and B<ENETUNREACH>."
244 #: build/C/man2/accept.2:214 build/C/man2/bind.2:157 build/C/man3/bindresvport.3:72 build/C/man2/connect.2:132 build/C/man3/getifaddrs.3:149 build/C/man2/getsockname.2:72 build/C/man2/getsockopt.2:136 build/C/man3/if_nameindex.3:78 build/C/man3/if_nametoindex.3:69 build/C/man2/listen.2:87 build/C/man2/recv.2:424 build/C/man2/recvmmsg.2:156 build/C/man2/select.2:318 build/C/man2/send.2:299 build/C/man2/sendmmsg.2:133 build/C/man3/sockatmark.3:58 build/C/man2/socket.2:315 build/C/man2/socketpair.2:74
250 #: build/C/man2/accept.2:215 build/C/man2/recv.2:429 build/C/man2/send.2:315
252 msgid "B<EAGAIN> or B<EWOULDBLOCK>"
255 #. Actually EAGAIN on Linux
257 #: build/C/man2/accept.2:223
259 "The socket is marked nonblocking and no connections are present to be "
260 "accepted. POSIX.1-2001 allows either error to be returned for this case, "
261 "and does not require these constants to have the same value, so a portable "
262 "application should check for both possibilities."
266 #: build/C/man2/accept.2:223 build/C/man2/bind.2:176 build/C/man2/connect.2:176 build/C/man2/getsockname.2:73 build/C/man2/getsockopt.2:137 build/C/man2/listen.2:104 build/C/man2/recv.2:438 build/C/man2/select.2:319 build/C/man2/send.2:336 build/C/man3/sockatmark.3:59
272 #: build/C/man2/accept.2:226
273 msgid "The descriptor is invalid."
277 #: build/C/man2/accept.2:226
279 msgid "B<ECONNABORTED>"
283 #: build/C/man2/accept.2:229
284 msgid "A connection has been aborted."
288 #: build/C/man2/accept.2:229 build/C/man2/bind.2:208 build/C/man2/connect.2:182 build/C/man2/getsockname.2:78 build/C/man2/getsockopt.2:142 build/C/man2/recv.2:447 build/C/man2/send.2:345 build/C/man2/socketpair.2:78
294 #: build/C/man2/accept.2:234
295 msgid "The I<addr> argument is not in a writable part of the user address space."
299 #: build/C/man2/accept.2:234 build/C/man2/connect.2:210 build/C/man2/recv.2:451 build/C/man2/select.2:324 build/C/man2/send.2:348
305 #: build/C/man2/accept.2:239
307 "The system call was interrupted by a signal that was caught before a valid "
308 "connection arrived; see B<signal>(7)."
312 #: build/C/man2/accept.2:239 build/C/man2/accept.2:244 build/C/man2/bind.2:180 build/C/man2/bind.2:185 build/C/man2/getsockname.2:84 build/C/man2/getsockopt.2:152 build/C/man2/recv.2:456 build/C/man2/recvmmsg.2:160 build/C/man2/select.2:328 build/C/man2/send.2:352 build/C/man3/sockatmark.3:63 build/C/man2/socket.2:323 build/C/man2/socket.2:326
318 #: build/C/man2/accept.2:244
320 "Socket is not listening for connections, or I<addrlen> is invalid (e.g., is "
325 #: build/C/man2/accept.2:249
326 msgid "(B<accept4>()) invalid value in I<flags>."
330 #: build/C/man2/accept.2:249 build/C/man2/socket.2:331 build/C/man2/socketpair.2:83
336 #: build/C/man2/accept.2:252
337 msgid "The per-process limit of open file descriptors has been reached."
341 #: build/C/man2/accept.2:252 build/C/man2/socket.2:334 build/C/man2/socketpair.2:86
347 #: build/C/man2/accept.2:255 build/C/man2/socket.2:337 build/C/man2/socketpair.2:89
348 msgid "The system limit on the total number of open files has been reached."
352 #: build/C/man2/accept.2:255
354 msgid "B<ENOBUFS>, B<ENOMEM>"
358 #: build/C/man2/accept.2:260
360 "Not enough free memory. This often means that the memory allocation is "
361 "limited by the socket buffer limits, not by the system memory."
365 #: build/C/man2/accept.2:260 build/C/man2/bind.2:191 build/C/man2/connect.2:222 build/C/man2/getsockname.2:92 build/C/man2/getsockopt.2:166 build/C/man2/listen.2:109 build/C/man2/recv.2:471 build/C/man2/send.2:381
371 #: build/C/man2/accept.2:263
372 msgid "The descriptor references a file, not a socket."
376 #: build/C/man2/accept.2:263 build/C/man2/listen.2:114 build/C/man2/send.2:386 build/C/man2/socketpair.2:89
378 msgid "B<EOPNOTSUPP>"
382 #: build/C/man2/accept.2:267
383 msgid "The referenced socket is not of type B<SOCK_STREAM>."
387 #: build/C/man2/accept.2:267
393 #: build/C/man2/accept.2:270
394 msgid "Protocol error."
398 #: build/C/man2/accept.2:274
399 msgid "In addition, Linux B<accept>() may fail if:"
403 #: build/C/man2/accept.2:274
409 #: build/C/man2/accept.2:277
410 msgid "Firewall rules forbid connection."
414 #: build/C/man2/accept.2:289
416 "In addition, network errors for the new socket and as defined for the "
417 "protocol may be returned. Various Linux kernels can return other errors "
418 "such as B<ENOSR>, B<ESOCKTNOSUPPORT>, B<EPROTONOSUPPORT>, B<ETIMEDOUT>. The "
419 "value B<ERESTARTSYS> may be seen during a trace."
423 #: build/C/man2/accept.2:289 build/C/man3/getifaddrs.3:162 build/C/man3/if_nameindex.3:97 build/C/man2/recvmmsg.2:164 build/C/man2/select.2:337 build/C/man2/sendmmsg.2:145 build/C/man3/sockatmark.3:70 build/C/man7/socket.7:915
429 #: build/C/man2/accept.2:294
431 "The B<accept4>() system call is available starting with Linux 2.6.28; "
432 "support in glibc is available starting with version 2.10."
436 #: build/C/man2/accept.2:294 build/C/man2/bind.2:232 build/C/man3/bindresvport.3:104 build/C/man2/connect.2:237 build/C/man3/getifaddrs.3:170 build/C/man2/getsockname.2:97 build/C/man2/getsockopt.2:171 build/C/man3/if_nameindex.3:104 build/C/man3/if_nametoindex.3:92 build/C/man2/listen.2:119 build/C/man2/recv.2:476 build/C/man2/recvmmsg.2:169 build/C/man2/select.2:343 build/C/man2/send.2:400 build/C/man2/sendmmsg.2:150 build/C/man3/sockatmark.3:78 build/C/man2/socket.2:348 build/C/man2/socketcall.2:42 build/C/man2/socketpair.2:95
438 msgid "CONFORMING TO"
441 #. The BSD man page documents five possible error returns
442 #. (EBADF, ENOTSOCK, EOPNOTSUPP, EWOULDBLOCK, EFAULT).
443 #. POSIX.1-2001 documents errors
444 #. EAGAIN, EBADF, ECONNABORTED, EINTR, EINVAL, EMFILE,
445 #. ENFILE, ENOBUFS, ENOMEM, ENOTSOCK, EOPNOTSUPP, EPROTO, EWOULDBLOCK.
446 #. In addition, SUSv2 documents EFAULT and ENOSR.
448 #: build/C/man2/accept.2:306
450 "B<accept>(): POSIX.1-2001, SVr4, 4.4BSD, (B<accept>() first appeared in "
455 #: build/C/man2/accept.2:309
456 msgid "B<accept4>() is a nonstandard Linux extension."
459 #. Some testing seems to show that Tru64 5.1 and HP-UX 11 also
460 #. do not inherit file status flags -- MTK Jun 05
462 #: build/C/man2/accept.2:324
464 "On Linux, the new socket returned by B<accept>() does I<not> inherit file "
465 "status flags such as B<O_NONBLOCK> and B<O_ASYNC> from the listening "
466 "socket. This behavior differs from the canonical BSD sockets "
467 "implementation. Portable programs should not rely on inheritance or "
468 "noninheritance of file status flags and always explicitly set all required "
469 "flags on the socket returned from B<accept>()."
473 #: build/C/man2/accept.2:324 build/C/man2/bind.2:244 build/C/man3/bindresvport.3:107 build/C/man2/connect.2:253 build/C/man3/getifaddrs.3:190 build/C/man2/getsockname.2:103 build/C/man2/getsockopt.2:178 build/C/man2/listen.2:124 build/C/man2/recv.2:486 build/C/man2/select.2:358 build/C/man2/select_tut.2:503 build/C/man2/send.2:414 build/C/man2/sendmmsg.2:153 build/C/man3/sockatmark.3:80 build/C/man2/socket.2:362 build/C/man7/socket.7:929 build/C/man2/socketcall.2:45 build/C/man2/socketpair.2:103
479 #: build/C/man2/accept.2:330 build/C/man2/bind.2:250 build/C/man2/connect.2:259 build/C/man2/getsockopt.2:184 build/C/man2/listen.2:150 build/C/man2/socket.2:368 build/C/man2/socketpair.2:124
481 "POSIX.1-2001 does not require the inclusion of I<E<lt>sys/types.hE<gt>>, and "
482 "this header file is not required on Linux. However, some historical (BSD) "
483 "implementations required this header file, and portable applications are "
484 "probably wise to include it."
488 #: build/C/man2/accept.2:351
490 "There may not always be a connection waiting after a B<SIGIO> is delivered "
491 "or B<select>(2) or B<poll>(2) return a readability event because the "
492 "connection might have been removed by an asynchronous network error or "
493 "another thread before B<accept>() is called. If this happens, then the "
494 "call will block waiting for the next connection to arrive. To ensure that "
495 "B<accept>() never blocks, the passed socket I<sockfd> needs to have the "
496 "B<O_NONBLOCK> flag set (see B<socket>(7))."
500 #: build/C/man2/accept.2:351
502 msgid "The socklen_t type"
506 #: build/C/man2/accept.2:361
508 "The third argument of B<accept>() was originally declared as an I<int *> "
509 "(and is that under libc4 and libc5 and on many other systems like 4.x BSD, "
510 "SunOS 4, SGI); a POSIX.1g draft standard wanted to change it into a I<size_t "
511 "*>, and that is what it is for SunOS 5. Later POSIX drafts have I<socklen_t "
512 "*>, and so do the Single UNIX Specification and glibc2. Quoting Linus "
516 #. .I fails: only italicizes a single line
518 #: build/C/man2/accept.2:378
520 "\"_Any_ sane library _must_ have \"socklen_t\" be the same size as int. "
521 "Anything else breaks any BSD socket layer stuff. POSIX initially I<did> "
522 "make it a size_t, and I (and hopefully others, but obviously not too many) "
523 "complained to them very loudly indeed. Making it a size_t is completely "
524 "broken, exactly because size_t very seldom is the same size as \"int\" on "
525 "64-bit architectures, for example. And it I<has> to be the same size as "
526 "\"int\" because that's what the BSD socket interface is. Anyway, the POSIX "
527 "people eventually got a clue, and created \"socklen_t\". They shouldn't "
528 "have touched it in the first place, but once they did they felt it had to "
529 "have a named type for some unfathomable reason (probably somebody didn't "
530 "like losing face over having done the original stupid thing, so they "
531 "silently just renamed their blunder).\""
535 #: build/C/man2/accept.2:378 build/C/man2/bind.2:264 build/C/man2/connect.2:276 build/C/man3/getifaddrs.3:207 build/C/man3/if_nameindex.3:108 build/C/man2/listen.2:179 build/C/man2/recv.2:511 build/C/man2/recvmmsg.2:172 build/C/man2/select.2:549 build/C/man2/select_tut.2:529 build/C/man2/send.2:438 build/C/man2/sendmmsg.2:168 build/C/man3/sockatmark.3:104 build/C/man2/socket.2:381
541 #: build/C/man2/accept.2:381 build/C/man2/listen.2:182
542 msgid "See B<bind>(2)."
546 #: build/C/man2/accept.2:381 build/C/man2/bind.2:329 build/C/man3/bindresvport.3:113 build/C/man2/connect.2:281 build/C/man3/getifaddrs.3:309 build/C/man2/getsockname.2:114 build/C/man2/getsockopt.2:202 build/C/man3/if_nameindex.3:147 build/C/man3/if_nametoindex.3:96 build/C/man2/listen.2:182 build/C/man2/recv.2:516 build/C/man2/recvmmsg.2:278 build/C/man2/select.2:586 build/C/man2/select_tut.2:821 build/C/man2/send.2:443 build/C/man2/sendmmsg.2:236 build/C/man3/sockatmark.3:139 build/C/man2/socket.2:386 build/C/man7/socket.7:960 build/C/man2/socketcall.2:53 build/C/man2/socketpair.2:124
552 #: build/C/man2/accept.2:388
554 "B<bind>(2), B<connect>(2), B<listen>(2), B<select>(2), B<socket>(2), "
559 #: build/C/man2/accept.2:388 build/C/man2/bind.2:342 build/C/man3/bindresvport.3:116 build/C/man2/connect.2:288 build/C/man3/getifaddrs.3:315 build/C/man2/getsockname.2:121 build/C/man2/getsockopt.2:213 build/C/man3/if_nameindex.3:154 build/C/man3/if_nametoindex.3:100 build/C/man2/listen.2:188 build/C/man2/recv.2:527 build/C/man2/recvmmsg.2:285 build/C/man2/select.2:601 build/C/man2/select_tut.2:840 build/C/man2/send.2:458 build/C/man2/sendmmsg.2:241 build/C/man3/sockatmark.3:144 build/C/man2/socket.2:415 build/C/man7/socket.7:972 build/C/man2/socketcall.2:71 build/C/man2/socketpair.2:131
565 #: build/C/man2/accept.2:396 build/C/man2/bind.2:350 build/C/man3/bindresvport.3:124 build/C/man2/connect.2:296 build/C/man3/getifaddrs.3:323 build/C/man2/getsockname.2:129 build/C/man2/getsockopt.2:221 build/C/man3/if_nameindex.3:162 build/C/man3/if_nametoindex.3:108 build/C/man2/listen.2:196 build/C/man2/recv.2:535 build/C/man2/recvmmsg.2:293 build/C/man2/select.2:609 build/C/man2/select_tut.2:848 build/C/man2/send.2:466 build/C/man2/sendmmsg.2:249 build/C/man3/sockatmark.3:152 build/C/man2/socket.2:423 build/C/man7/socket.7:980 build/C/man2/socketcall.2:79 build/C/man2/socketpair.2:139
567 "This page is part of release 3.76 of the Linux I<man-pages> project. A "
568 "description of the project, information about reporting bugs, and the latest "
569 "version of this page, can be found at "
570 "\\%http://www.kernel.org/doc/man-pages/."
574 #: build/C/man2/bind.2:68
580 #: build/C/man2/bind.2:68 build/C/man2/recv.2:41 build/C/man2/send.2:40
586 #: build/C/man2/bind.2:71
587 msgid "bind - bind a name to a socket"
591 #: build/C/man2/bind.2:78
594 "B<int bind(int >I<sockfd>B<, const struct sockaddr *>I<addr>B<,>\n"
595 "B< socklen_t >I<addrlen>B<);>\n"
599 #: build/C/man2/bind.2:92
601 "When a socket is created with B<socket>(2), it exists in a name space "
602 "(address family) but has no address assigned to it. B<bind>() assigns the "
603 "address specified by I<addr> to the socket referred to by the file "
604 "descriptor I<sockfd>. I<addrlen> specifies the size, in bytes, of the "
605 "address structure pointed to by I<addr>. Traditionally, this operation is "
606 "called \\(lqassigning a name to a socket\\(rq."
610 #: build/C/man2/bind.2:99
612 "It is normally necessary to assign a local address using B<bind>() before a "
613 "B<SOCK_STREAM> socket may receive connections (see B<accept>(2))."
617 #: build/C/man2/bind.2:130
619 "The rules used in name binding vary between address families. Consult the "
620 "manual entries in Section 7 for detailed information. For B<AF_INET> see "
621 "B<ip>(7), for B<AF_INET6> see B<ipv6>(7), for B<AF_UNIX> see B<unix>(7), for "
622 "B<AF_APPLETALK> see B<ddp>(7), for B<AF_PACKET> see B<packet>(7), for "
623 "B<AF_X25> see B<x25>(7) and for B<AF_NETLINK> see B<netlink>(7)."
627 #: build/C/man2/bind.2:137
629 "The actual structure passed for the I<addr> argument will depend on the "
630 "address family. The I<sockaddr> structure is defined as something like:"
634 #: build/C/man2/bind.2:144
637 "struct sockaddr {\n"
638 " sa_family_t sa_family;\n"
639 " char sa_data[14];\n"
644 #: build/C/man2/bind.2:152
646 "The only purpose of this structure is to cast the structure pointer passed "
647 "in I<addr> in order to avoid compiler warnings. See EXAMPLE below."
651 #: build/C/man2/bind.2:157 build/C/man2/getsockname.2:72 build/C/man2/getsockopt.2:136 build/C/man2/listen.2:87 build/C/man2/socketpair.2:74
653 "On success, zero is returned. On error, -1 is returned, and I<errno> is set "
658 #: build/C/man2/bind.2:158 build/C/man2/bind.2:199 build/C/man3/bindresvport.3:77 build/C/man2/connect.2:135 build/C/man2/send.2:304 build/C/man2/socket.2:316
663 #. e.g., privileged port in AF_INET domain
665 #: build/C/man2/bind.2:162
666 msgid "The address is protected, and the user is not the superuser."
670 #: build/C/man2/bind.2:162 build/C/man2/bind.2:165 build/C/man3/bindresvport.3:82 build/C/man2/connect.2:148 build/C/man2/listen.2:88 build/C/man2/listen.2:91
672 msgid "B<EADDRINUSE>"
676 #: build/C/man2/bind.2:165
677 msgid "The given address is already in use."
681 #: build/C/man2/bind.2:175
683 "(Internet domain sockets) The port number was specified as zero in the "
684 "socket address structure, but, upon attempting to bind to an ephemeral port, "
685 "it was determined that all port numbers in the ephemeral port range are "
686 "currently in use. See the discussion of "
687 "I</proc/sys/net/ipv4/ip_local_port_range> B<ip>(7)."
691 #: build/C/man2/bind.2:180
692 msgid "I<sockfd> is not a valid descriptor."
695 #. This may change in the future: see
696 #. .I linux/unix/sock.c for details.
698 #: build/C/man2/bind.2:185
699 msgid "The socket is already bound to an address."
703 #: build/C/man2/bind.2:191
705 "I<addrlen> is wrong, or I<addr> is not a valid address for this socket's "
710 #: build/C/man2/bind.2:195
711 msgid "I<sockfd> is a descriptor for a file, not a socket."
715 #: build/C/man2/bind.2:199
716 msgid "The following errors are specific to UNIX domain (B<AF_UNIX>) sockets:"
720 #: build/C/man2/bind.2:204
722 "Search permission is denied on a component of the path prefix. (See also "
723 "B<path_resolution>(7).)"
727 #: build/C/man2/bind.2:204 build/C/man2/connect.2:151
729 msgid "B<EADDRNOTAVAIL>"
733 #: build/C/man2/bind.2:208
735 "A nonexistent interface was requested or the requested address was not "
740 #: build/C/man2/bind.2:212
741 msgid "I<addr> points outside the user's accessible address space."
745 #: build/C/man2/bind.2:212
751 #: build/C/man2/bind.2:216
752 msgid "Too many symbolic links were encountered in resolving I<addr>."
756 #: build/C/man2/bind.2:216
758 msgid "B<ENAMETOOLONG>"
762 #: build/C/man2/bind.2:220
763 msgid "I<addr> is too long."
767 #: build/C/man2/bind.2:220
773 #: build/C/man2/bind.2:223
774 msgid "The file does not exist."
778 #: build/C/man2/bind.2:223 build/C/man2/recv.2:460 build/C/man2/select.2:334 build/C/man2/send.2:375
784 #: build/C/man2/bind.2:226
785 msgid "Insufficient kernel memory was available."
789 #: build/C/man2/bind.2:226
795 #: build/C/man2/bind.2:229
796 msgid "A component of the path prefix is not a directory."
800 #: build/C/man2/bind.2:229
806 #: build/C/man2/bind.2:232
807 msgid "The socket inode would reside on a read-only filesystem."
810 #. SVr4 documents an additional
812 #. general error condition, and
817 #. UNIX-domain error conditions.
819 #: build/C/man2/bind.2:244
820 msgid "SVr4, 4.4BSD, POSIX.1-2001 (B<bind>() first appeared in 4.2BSD)."
824 #: build/C/man2/bind.2:261
826 "The third argument of B<bind>() is in reality an I<int> (and this is what "
827 "4.x BSD and libc4 and libc5 have). Some POSIX confusion resulted in the "
828 "present I<socklen_t>, also used by glibc. See also B<accept>(2)."
832 #: build/C/man2/bind.2:261 build/C/man2/getsockopt.2:199 build/C/man2/recvmmsg.2:267 build/C/man2/select.2:486 build/C/man2/send.2:433 build/C/man3/sockatmark.3:100 build/C/man7/socket.7:947
837 #. FIXME Document transparent proxy options
839 #: build/C/man2/bind.2:264
840 msgid "The transparent proxy options are not described."
844 #: build/C/man2/bind.2:269
846 "An example of the use of B<bind>() with Internet domain sockets can be "
847 "found in B<getaddrinfo>(3)."
850 #. listen.7 refers to this example.
851 #. accept.7 refers to this example.
852 #. unix.7 refers to this example.
854 #: build/C/man2/bind.2:276
856 "The following example shows how to bind a stream socket in the UNIX "
857 "(B<AF_UNIX>) domain, and accept connections:"
861 #: build/C/man2/bind.2:283
864 "#include E<lt>sys/socket.hE<gt>\n"
865 "#include E<lt>sys/un.hE<gt>\n"
866 "#include E<lt>stdlib.hE<gt>\n"
867 "#include E<lt>stdio.hE<gt>\n"
868 "#include E<lt>string.hE<gt>\n"
872 #: build/C/man2/bind.2:286
875 "#define MY_SOCK_PATH \"/somepath\"\n"
876 "#define LISTEN_BACKLOG 50\n"
880 #: build/C/man2/bind.2:289
883 "#define handle_error(msg) \\e\n"
884 " do { perror(msg); exit(EXIT_FAILURE); } while (0)\n"
888 #: build/C/man2/bind.2:296
892 "main(int argc, char *argv[])\n"
895 " struct sockaddr_un my_addr, peer_addr;\n"
896 " socklen_t peer_addr_size;\n"
900 #: build/C/man2/bind.2:300
903 " sfd = socket(AF_UNIX, SOCK_STREAM, 0);\n"
905 " handle_error(\"socket\");\n"
909 #: build/C/man2/bind.2:306
912 " memset(&my_addr, 0, sizeof(struct sockaddr_un));\n"
913 " /* Clear structure */\n"
914 " my_addr.sun_family = AF_UNIX;\n"
915 " strncpy(my_addr.sun_path, MY_SOCK_PATH,\n"
916 " sizeof(my_addr.sun_path) - 1);\n"
920 #: build/C/man2/bind.2:310
923 " if (bind(sfd, (struct sockaddr *) &my_addr,\n"
924 " sizeof(struct sockaddr_un)) == -1)\n"
925 " handle_error(\"bind\");\n"
929 #: build/C/man2/bind.2:313
932 " if (listen(sfd, LISTEN_BACKLOG) == -1)\n"
933 " handle_error(\"listen\");\n"
937 #: build/C/man2/bind.2:316
940 " /* Now we can accept incoming connections one\n"
941 " at a time using accept(2) */\n"
945 #: build/C/man2/bind.2:322
948 " peer_addr_size = sizeof(struct sockaddr_un);\n"
949 " cfd = accept(sfd, (struct sockaddr *) &peer_addr,\n"
950 " &peer_addr_size);\n"
952 " handle_error(\"accept\");\n"
956 #: build/C/man2/bind.2:324
958 msgid " /* Code to deal with incoming connection(s)... */\n"
962 #: build/C/man2/bind.2:328
965 " /* When no longer required, the socket pathname, MY_SOCK_PATH\n"
966 " should be deleted using unlink(2) or remove(3) */\n"
971 #: build/C/man2/bind.2:342
973 "B<accept>(2), B<connect>(2), B<getsockname>(2), B<listen>(2), B<socket>(2), "
974 "B<getaddrinfo>(3), B<getifaddrs>(3), B<ip>(7), B<ipv6>(7), "
975 "B<path_resolution>(7), B<socket>(7), B<unix>(7)"
979 #: build/C/man3/bindresvport.3:30
985 #: build/C/man3/bindresvport.3:30
991 #: build/C/man3/bindresvport.3:33
992 msgid "bindresvport - bind a socket to a privileged IP port"
996 #: build/C/man3/bindresvport.3:37
999 "B<#include E<lt>sys/types.hE<gt>>\n"
1000 "B<#include E<lt>netinet/in.hE<gt>>\n"
1004 #: build/C/man3/bindresvport.3:39
1006 msgid "B<int bindresvport(int >I<sockfd>B<, struct sockaddr_in *>I<sin>B<);>\n"
1009 #. Glibc actually starts searching with a port # in the range 600 to 1023
1011 #: build/C/man3/bindresvport.3:46
1013 "B<bindresvport>() is used to bind a socket descriptor to a privileged "
1014 "anonymous IP port, that is, a port number arbitrarily selected from the "
1015 "range 512 to 1023."
1019 #: build/C/man3/bindresvport.3:56
1021 "If the B<bind>(2) performed by B<bindresvport>() is successful, and I<sin> "
1022 "is not NULL, then I<sin-E<gt>sin_port> returns the port number actually "
1027 #: build/C/man3/bindresvport.3:67
1029 "I<sin> can be NULL, in which case I<sin-E<gt>sin_family> is implicitly taken "
1030 "to be B<AF_INET>. However, in this case, B<bindresvport>() has no way to "
1031 "return the port number actually allocated. (This information can later be "
1032 "obtained using B<getsockname>(2).)"
1036 #: build/C/man3/bindresvport.3:72
1038 "B<bindresvport>() returns 0 on success; otherwise -1 is returned and "
1039 "I<errno> set to indicate the cause of the error."
1043 #: build/C/man3/bindresvport.3:77
1045 "B<bindresvport>() can fail for any of the same reasons as B<bind>(2). In "
1046 "addition, the following errors may occur:"
1050 #: build/C/man3/bindresvport.3:82
1052 "The caller did not have superuser privilege (to be precise: the "
1053 "B<CAP_NET_BIND_SERVICE> capability is required)."
1057 #: build/C/man3/bindresvport.3:85
1058 msgid "All privileged ports are in use."
1062 #: build/C/man3/bindresvport.3:85
1064 msgid "B<EAFNOSUPPORT> (B<EPFNOSUPPORT> in glibc 2.7 and earlier)"
1068 #: build/C/man3/bindresvport.3:92
1069 msgid "I<sin> is not NULL and I<sin-E<gt>sin_family> is not B<AF_INET>."
1073 #: build/C/man3/bindresvport.3:92 build/C/man3/if_nametoindex.3:85 build/C/man3/sockatmark.3:73
1079 #: build/C/man3/bindresvport.3:93 build/C/man3/if_nametoindex.3:86 build/C/man3/sockatmark.3:74
1081 msgid "Multithreading (see pthreads(7))"
1085 #: build/C/man3/bindresvport.3:98
1087 "Before glibc 2.17, the B<bindresvport>() function uses a static variable "
1088 "that is not protected, so it is not thread-safe."
1091 #. commit f6da27e53695ad1cc0e2a9490358decbbfdff5e5
1093 #: build/C/man3/bindresvport.3:104
1095 "Since glibc 2.17, the B<bindresvport>() function uses a lock to protect the "
1096 "static variable, so it is thread-safe."
1100 #: build/C/man3/bindresvport.3:107
1101 msgid "Not in POSIX.1-2001. Present on the BSDs, Solaris, and many other systems."
1105 #: build/C/man3/bindresvport.3:113
1107 "Unlike some B<bindresvport>() implementations, the glibc implementation "
1108 "ignores any value that the caller supplies in I<sin-E<gt>sin_port>."
1112 #: build/C/man3/bindresvport.3:116
1113 msgid "B<bind>(2), B<getsockname>(2)"
1117 #: build/C/man2/connect.2:67
1123 #: build/C/man2/connect.2:67
1129 #: build/C/man2/connect.2:70
1130 msgid "connect - initiate a connection on a socket"
1134 #: build/C/man2/connect.2:73 build/C/man2/getsockopt.2:50 build/C/man2/listen.2:51
1136 msgid "B<#include E<lt>sys/types.hE<gt>> /* See NOTES */\n"
1140 #: build/C/man2/connect.2:75 build/C/man2/getsockname.2:46 build/C/man2/getsockopt.2:52 build/C/man2/listen.2:53 build/C/man2/recv.2:51
1142 msgid "B<#include E<lt>sys/socket.hE<gt>>\n"
1146 #: build/C/man2/connect.2:78
1149 "B<int connect(int >I<sockfd>B<, const struct sockaddr *>I<addr>B<,>\n"
1150 "B< socklen_t >I<addrlen>B<);>\n"
1154 #: build/C/man2/connect.2:97
1156 "The B<connect>() system call connects the socket referred to by the file "
1157 "descriptor I<sockfd> to the address specified by I<addr>. The I<addrlen> "
1158 "argument specifies the size of I<addr>. The format of the address in "
1159 "I<addr> is determined by the address space of the socket I<sockfd>; see "
1160 "B<socket>(2) for further details."
1164 #: build/C/man2/connect.2:113
1166 "If the socket I<sockfd> is of type B<SOCK_DGRAM>, then I<addr> is the "
1167 "address to which datagrams are sent by default, and the only address from "
1168 "which datagrams are received. If the socket is of type B<SOCK_STREAM> or "
1169 "B<SOCK_SEQPACKET>, this call attempts to make a connection to the socket "
1170 "that is bound to the address specified by I<addr>."
1174 #: build/C/man2/connect.2:127
1176 "Generally, connection-based protocol sockets may successfully B<connect>() "
1177 "only once; connectionless protocol sockets may use B<connect>() multiple "
1178 "times to change their association. Connectionless sockets may dissolve the "
1179 "association by connecting to an address with the I<sa_family> member of "
1180 "I<sockaddr> set to B<AF_UNSPEC> (supported on Linux since kernel 2.2)."
1184 #: build/C/man2/connect.2:132
1186 "If the connection or binding succeeds, zero is returned. On error, -1 is "
1187 "returned, and I<errno> is set appropriately."
1191 #: build/C/man2/connect.2:135
1193 "The following are general socket errors only. There may be other "
1194 "domain-specific error codes."
1198 #: build/C/man2/connect.2:143
1200 "For UNIX domain sockets, which are identified by pathname: Write permission "
1201 "is denied on the socket file, or search permission is denied for one of the "
1202 "directories in the path prefix. (See also B<path_resolution>(7).)"
1206 #: build/C/man2/connect.2:143
1208 msgid "B<EACCES>, B<EPERM>"
1212 #: build/C/man2/connect.2:148
1214 "The user tried to connect to a broadcast address without having the socket "
1215 "broadcast flag enabled or the connection request failed because of a local "
1220 #: build/C/man2/connect.2:151
1221 msgid "Local address is already in use."
1225 #: build/C/man2/connect.2:164 build/C/man2/listen.2:104
1227 "(Internet domain sockets) The socket referred to by I<sockfd> had not "
1228 "previously been bound to an address and, upon attempting to bind it to an "
1229 "ephemeral port, it was determined that all port numbers in the ephemeral "
1230 "port range are currently in use. See the discussion of "
1231 "I</proc/sys/net/ipv4/ip_local_port_range> in B<ip>(7)."
1235 #: build/C/man2/connect.2:164 build/C/man2/socket.2:320 build/C/man2/socketpair.2:75
1237 msgid "B<EAFNOSUPPORT>"
1241 #: build/C/man2/connect.2:169
1243 "The passed address didn't have the correct address family in its "
1244 "I<sa_family> field."
1248 #: build/C/man2/connect.2:169 build/C/man2/send.2:323
1254 #: build/C/man2/connect.2:172
1255 msgid "Insufficient entries in the routing cache."
1259 #: build/C/man2/connect.2:172
1265 #: build/C/man2/connect.2:176
1267 "The socket is nonblocking and a previous connection attempt has not yet been "
1272 #: build/C/man2/connect.2:179
1273 msgid "The file descriptor is not a valid index in the descriptor table."
1277 #: build/C/man2/connect.2:179 build/C/man2/recv.2:443
1279 msgid "B<ECONNREFUSED>"
1283 #: build/C/man2/connect.2:182
1284 msgid "No-one listening on the remote address."
1288 #: build/C/man2/connect.2:185
1289 msgid "The socket structure address is outside the user's address space."
1293 #: build/C/man2/connect.2:185
1295 msgid "B<EINPROGRESS>"
1299 #: build/C/man2/connect.2:210
1301 "The socket is nonblocking and the connection cannot be completed "
1302 "immediately. It is possible to B<select>(2) or B<poll>(2) for completion "
1303 "by selecting the socket for writing. After B<select>(2) indicates "
1304 "writability, use B<getsockopt>(2) to read the B<SO_ERROR> option at level "
1305 "B<SOL_SOCKET> to determine whether B<connect>() completed successfully "
1306 "(B<SO_ERROR> is zero) or unsuccessfully (B<SO_ERROR> is one of the usual "
1307 "error codes listed here, explaining the reason for the failure)."
1310 #. For TCP, the connection will complete asynchronously.
1311 #. See http://lkml.org/lkml/2005/7/12/254
1313 #: build/C/man2/connect.2:216
1315 "The system call was interrupted by a signal that was caught; see "
1320 #: build/C/man2/connect.2:216 build/C/man2/send.2:355
1326 #: build/C/man2/connect.2:219
1327 msgid "The socket is already connected."
1331 #: build/C/man2/connect.2:219
1333 msgid "B<ENETUNREACH>"
1337 #: build/C/man2/connect.2:222
1338 msgid "Network is unreachable."
1342 #: build/C/man2/connect.2:225
1343 msgid "The file descriptor is not associated with a socket."
1347 #: build/C/man2/connect.2:225
1349 msgid "B<EPROTOTYPE>"
1353 #: build/C/man2/connect.2:230
1355 "The socket type does not support the requested communications protocol. "
1356 "This error can occur, for example, on an attempt to connect a UNIX domain "
1357 "datagram socket to a stream socket."
1361 #: build/C/man2/connect.2:230
1363 msgid "B<ETIMEDOUT>"
1367 #: build/C/man2/connect.2:237
1369 "Timeout while attempting connection. The server may be too busy to accept "
1370 "new connections. Note that for IP sockets the timeout may be very long when "
1371 "syncookies are enabled on the server."
1374 #. SVr4 documents the additional
1375 #. general error codes
1376 #. .BR EADDRNOTAVAIL ,
1378 #. .BR EAFNOSUPPORT ,
1385 #. documents many additional error conditions not described here.
1387 #: build/C/man2/connect.2:253
1389 "SVr4, 4.4BSD, (the B<connect>() function first appeared in 4.2BSD), "
1394 #: build/C/man2/connect.2:270
1396 "The third argument of B<connect>() is in reality an I<int> (and this is "
1397 "what 4.x BSD and libc4 and libc5 have). Some POSIX confusion resulted in "
1398 "the present I<socklen_t>, also used by glibc. See also B<accept>(2)."
1402 #: build/C/man2/connect.2:276
1404 "If B<connect()> fails, consider the state of the socket as unspecified. "
1405 "Portable applications should close the socket and create a new one for "
1410 #: build/C/man2/connect.2:281
1411 msgid "An example of the use of B<connect>() is shown in B<getaddrinfo>(3)."
1415 #: build/C/man2/connect.2:288
1417 "B<accept>(2), B<bind>(2), B<getsockname>(2), B<listen>(2), B<socket>(2), "
1418 "B<path_resolution>(7)"
1422 #: build/C/man3/getifaddrs.3:36
1428 #: build/C/man3/getifaddrs.3:36
1434 #: build/C/man3/getifaddrs.3:36 build/C/man3/if_nameindex.3:26 build/C/man3/if_nametoindex.3:25
1440 #: build/C/man3/getifaddrs.3:39
1441 msgid "getifaddrs, freeifaddrs - get interface addresses"
1445 #: build/C/man3/getifaddrs.3:43
1448 "B<#include E<lt>sys/types.hE<gt>>\n"
1449 "B<#include E<lt>ifaddrs.hE<gt>>\n"
1453 #: build/C/man3/getifaddrs.3:45
1455 msgid "B<int getifaddrs(struct ifaddrs **>I<ifap>B<);>\n"
1459 #: build/C/man3/getifaddrs.3:47
1461 msgid "B<void freeifaddrs(struct ifaddrs *>I<ifa>B<);>\n"
1465 #: build/C/man3/getifaddrs.3:58
1467 "The B<getifaddrs>() function creates a linked list of structures describing "
1468 "the network interfaces of the local system, and stores the address of the "
1469 "first item of the list in I<*ifap>. The list consists of I<ifaddrs> "
1470 "structures, defined as follows:"
1474 #: build/C/man3/getifaddrs.3:77
1477 "struct ifaddrs {\n"
1478 " struct ifaddrs *ifa_next; /* Next item in list */\n"
1479 " char *ifa_name; /* Name of interface */\n"
1480 " unsigned int ifa_flags; /* Flags from SIOCGIFFLAGS */\n"
1481 " struct sockaddr *ifa_addr; /* Address of interface */\n"
1482 " struct sockaddr *ifa_netmask; /* Netmask of interface */\n"
1484 " struct sockaddr *ifu_broadaddr;\n"
1485 " /* Broadcast address of interface */\n"
1486 " struct sockaddr *ifu_dstaddr;\n"
1487 " /* Point-to-point destination address */\n"
1489 "#define ifa_broadaddr ifa_ifu.ifu_broadaddr\n"
1490 "#define ifa_dstaddr ifa_ifu.ifu_dstaddr\n"
1491 " void *ifa_data; /* Address-specific data */\n"
1496 #: build/C/man3/getifaddrs.3:84
1498 "The I<ifa_next> field contains a pointer to the next structure on the list, "
1499 "or NULL if this is the last item of the list."
1504 #. indicates the maximum length of this field.
1506 #: build/C/man3/getifaddrs.3:91
1507 msgid "The I<ifa_name> points to the null-terminated interface name."
1511 #: build/C/man3/getifaddrs.3:100
1513 "The I<ifa_flags> field contains the interface flags, as returned by the "
1514 "B<SIOCGIFFLAGS> B<ioctl>(2) operation (see B<netdevice>(7) for a list of "
1519 #: build/C/man3/getifaddrs.3:109
1521 "The I<ifa_addr> field points to a structure containing the interface "
1522 "address. (The I<sa_family> subfield should be consulted to determine the "
1523 "format of the address structure.) This field may contain a null pointer."
1527 #: build/C/man3/getifaddrs.3:116
1529 "The I<ifa_netmask> field points to a structure containing the netmask "
1530 "associated with I<ifa_addr>, if applicable for the address family. This "
1531 "field may contain a null pointer."
1535 #: build/C/man3/getifaddrs.3:131
1537 "Depending on whether the bit B<IFF_BROADCAST> or B<IFF_POINTOPOINT> is set "
1538 "in I<ifa_flags> (only one can be set at a time), either I<ifa_broadaddr> "
1539 "will contain the broadcast address associated with I<ifa_addr> (if "
1540 "applicable for the address family) or I<ifa_dstaddr> will contain the "
1541 "destination address of the point-to-point interface."
1545 #: build/C/man3/getifaddrs.3:136
1547 "The I<ifa_data> field points to a buffer containing address-family-specific "
1548 "data; this field may be NULL if there is no such data for this interface."
1552 #: build/C/man3/getifaddrs.3:142
1554 "The data returned by B<getifaddrs>() is dynamically allocated and should be "
1555 "freed using B<freeifaddrs>() when no longer needed."
1559 #: build/C/man3/getifaddrs.3:149
1561 "On success, B<getifaddrs>() returns zero; on error, -1 is returned, and "
1562 "I<errno> is set appropriately."
1566 #: build/C/man3/getifaddrs.3:162
1568 "B<getifaddrs>() may fail and set I<errno> for any of the errors specified "
1569 "for B<socket>(2), B<bind>(2), B<getsockname>(2), B<recvmsg>(2), "
1570 "B<sendto>(2), B<malloc>(3), or B<realloc>(3)."
1574 #: build/C/man3/getifaddrs.3:170
1576 "The B<getifaddrs>() function first appeared in glibc 2.3, but before glibc "
1577 "2.3.3, the implementation supported only IPv4 addresses; IPv6 support was "
1578 "added in glibc 2.3.3. Support of address families other than IPv4 is "
1579 "available only on kernels that support netlink."
1582 #. , but the BSD-derived documentation generally
1583 #. appears to be confused and obsolete on this point.
1584 #. i.e., commonly it still says one of them will be NULL, even if
1585 #. the ifa_ifu union is already present
1587 #: build/C/man3/getifaddrs.3:190
1589 "Not in POSIX.1-2001. This function first appeared in BSDi and is present on "
1590 "the BSD systems, but with slightly different semantics "
1591 "documented\\(emreturning one entry per interface, not per address. This "
1592 "means I<ifa_addr> and other fields can actually be NULL if the interface has "
1593 "no address, and no link-level address is returned if the interface has an IP "
1594 "address assigned. Also, the way of choosing either I<ifa_broadaddr> or "
1595 "I<ifa_dstaddr> differs on various systems."
1599 #: build/C/man3/getifaddrs.3:207
1601 "The addresses returned on Linux will usually be the IPv4 and IPv6 addresses "
1602 "assigned to the interface, but also one B<AF_PACKET> address per interface "
1603 "containing lower-level details about the interface and its physical layer. "
1604 "In this case, the I<ifa_data> field may contain a pointer to a I<struct "
1605 "rtnl_link_stats>, defined in I<E<lt>linux/if_link.hE<gt>> (in Linux 2.4 and "
1606 "earlier, I<struct net_device_stats>, defined in "
1607 "I<E<lt>linux/netdevice.hE<gt>>), which contains various interface attributes "
1612 #: build/C/man3/getifaddrs.3:214
1614 "The program below demonstrates the use of B<getifaddrs>(), B<freeifaddrs>(), "
1615 "and B<getnameinfo>(3). Here is what we see when running this program on one "
1620 #: build/C/man3/getifaddrs.3:235
1624 "lo AF_PACKET (17)\n"
1625 " tx_packets = 524; rx_packets = 524\n"
1626 " tx_bytes = 38788; rx_bytes = 38788\n"
1627 "wlp3s0 AF_PACKET (17)\n"
1628 " tx_packets = 108391; rx_packets = 130245\n"
1629 " tx_bytes = 30420659; rx_bytes = 94230014\n"
1630 "em1 AF_PACKET (17)\n"
1631 " tx_packets = 0; rx_packets = 0\n"
1632 " tx_bytes = 0; rx_bytes = 0\n"
1634 " address: E<lt>127.0.0.1E<gt>\n"
1635 "wlp3s0 AF_INET (2)\n"
1636 " address: E<lt>192.168.235.137E<gt>\n"
1637 "lo AF_INET6 (10)\n"
1638 " address: E<lt>::1E<gt>\n"
1639 "wlp3s0 AF_INET6 (10)\n"
1640 " address: E<lt>fe80::7ee9:d3ff:fef5:1a91%wlp3s0E<gt>\n"
1644 #: build/C/man3/getifaddrs.3:237 build/C/man3/if_nameindex.3:121 build/C/man2/recvmmsg.2:205
1646 msgid "Program source"
1650 #: build/C/man3/getifaddrs.3:249
1653 "#define _GNU_SOURCE /* To get defns of NI_MAXSERV and NI_MAXHOST */\n"
1654 "#include E<lt>arpa/inet.hE<gt>\n"
1655 "#include E<lt>sys/socket.hE<gt>\n"
1656 "#include E<lt>netdb.hE<gt>\n"
1657 "#include E<lt>ifaddrs.hE<gt>\n"
1658 "#include E<lt>stdio.hE<gt>\n"
1659 "#include E<lt>stdlib.hE<gt>\n"
1660 "#include E<lt>unistd.hE<gt>\n"
1661 "#include E<lt>linux/if_link.hE<gt>\n"
1665 #: build/C/man3/getifaddrs.3:255
1668 "int main(int argc, char *argv[])\n"
1670 " struct ifaddrs *ifaddr, *ifa;\n"
1671 " int family, s, n;\n"
1672 " char host[NI_MAXHOST];\n"
1676 #: build/C/man3/getifaddrs.3:260
1679 " if (getifaddrs(&ifaddr) == -1) {\n"
1680 " perror(\"getifaddrs\");\n"
1681 " exit(EXIT_FAILURE);\n"
1686 #: build/C/man3/getifaddrs.3:263
1689 " /* Walk through linked list, maintaining head pointer so we\n"
1690 " can free list later */\n"
1694 #: build/C/man3/getifaddrs.3:267
1697 " for (ifa = ifaddr, n = 0; ifa != NULL; ifa = ifa-E<gt>ifa_next, n++) {\n"
1698 " if (ifa-E<gt>ifa_addr == NULL)\n"
1703 #: build/C/man3/getifaddrs.3:269
1705 msgid " family = ifa-E<gt>ifa_addr-E<gt>sa_family;\n"
1709 #: build/C/man3/getifaddrs.3:272
1712 " /* Display interface name and family (including symbolic\n"
1713 " form of the latter for the common families) */\n"
1717 #: build/C/man3/getifaddrs.3:279
1720 " printf(\"%-8s %s (%d)\\en\",\n"
1721 " ifa-E<gt>ifa_name,\n"
1722 " (family == AF_PACKET) ? \"AF_PACKET\" :\n"
1723 " (family == AF_INET) ? \"AF_INET\" :\n"
1724 " (family == AF_INET6) ? \"AF_INET6\" : \"???\",\n"
1729 #: build/C/man3/getifaddrs.3:281
1731 msgid " /* For an AF_INET* interface address, display the address */\n"
1735 #: build/C/man3/getifaddrs.3:292
1738 " if (family == AF_INET || family == AF_INET6) {\n"
1739 " s = getnameinfo(ifa-E<gt>ifa_addr,\n"
1740 " (family == AF_INET) ? sizeof(struct sockaddr_in) :\n"
1741 " sizeof(struct sockaddr_in6),\n"
1742 " host, NI_MAXHOST,\n"
1743 " NULL, 0, NI_NUMERICHOST);\n"
1745 " printf(\"getnameinfo() failed: %s\\en\", gai_strerror(s));\n"
1746 " exit(EXIT_FAILURE);\n"
1751 #: build/C/man3/getifaddrs.3:294
1753 msgid " printf(\"\\et\\etaddress: E<lt>%sE<gt>\\en\", host);\n"
1757 #: build/C/man3/getifaddrs.3:297
1760 " } else if (family == AF_PACKET && ifa-E<gt>ifa_data != NULL) {\n"
1761 " struct rtnl_link_stats *stats = ifa-E<gt>ifa_data;\n"
1765 #: build/C/man3/getifaddrs.3:304
1768 " printf(\"\\et\\ettx_packets = %10u; rx_packets = %10u\\en\"\n"
1769 " \"\\et\\ettx_bytes = %10u; rx_bytes = %10u\\en\",\n"
1770 " stats-E<gt>tx_packets, stats-E<gt>rx_packets,\n"
1771 " stats-E<gt>tx_bytes, stats-E<gt>rx_bytes);\n"
1777 #: build/C/man3/getifaddrs.3:308
1780 " freeifaddrs(ifaddr);\n"
1781 " exit(EXIT_SUCCESS);\n"
1786 #: build/C/man3/getifaddrs.3:315
1787 msgid "B<bind>(2), B<getsockname>(2), B<socket>(2), B<packet>(7), B<ifconfig>(8)"
1791 #: build/C/man2/getsockname.2:40
1797 #: build/C/man2/getsockname.2:40
1803 #: build/C/man2/getsockname.2:43
1804 msgid "getsockname - get socket name"
1808 #: build/C/man2/getsockname.2:49
1811 "B<int getsockname(int >I<sockfd>B<, struct sockaddr *>I<addr>B<, socklen_t "
1812 "*>I<addrlen>B<);>\n"
1816 #: build/C/man2/getsockname.2:62
1818 "B<getsockname>() returns the current address to which the socket I<sockfd> "
1819 "is bound, in the buffer pointed to by I<addr>. The I<addrlen> argument "
1820 "should be initialized to indicate the amount of space (in bytes) pointed to "
1821 "by I<addr>. On return it contains the actual size of the socket address."
1825 #: build/C/man2/getsockname.2:78 build/C/man2/getsockopt.2:142 build/C/man2/listen.2:109
1826 msgid "The argument I<sockfd> is not a valid descriptor."
1830 #: build/C/man2/getsockname.2:84
1832 "The I<addr> argument points to memory not in a valid part of the process "
1837 #: build/C/man2/getsockname.2:88
1838 msgid "I<addrlen> is invalid (e.g., is negative)."
1842 #: build/C/man2/getsockname.2:88 build/C/man3/if_nameindex.3:83 build/C/man2/send.2:367
1848 #: build/C/man2/getsockname.2:92
1850 "Insufficient resources were available in the system to perform the "
1855 #: build/C/man2/getsockname.2:97 build/C/man2/getsockopt.2:171
1856 msgid "The argument I<sockfd> is a file, not a socket."
1859 #. SVr4 documents additional ENOMEM
1860 #. and ENOSR error codes.
1862 #: build/C/man2/getsockname.2:103
1864 "SVr4, 4.4BSD (the B<getsockname>() function call appeared in 4.2BSD), "
1869 #: build/C/man2/getsockname.2:114
1871 "The third argument of B<getsockname>() is in reality an I<int\\ *> (and "
1872 "this is what 4.x BSD and libc4 and libc5 have). Some POSIX confusion "
1873 "resulted in the present I<socklen_t>, also used by glibc. See also "
1878 #: build/C/man2/getsockname.2:121
1880 "B<bind>(2), B<socket>(2), B<getifaddrs>(3), B<ip>(7), B<socket>(7), "
1885 #: build/C/man2/getsockopt.2:44
1891 #: build/C/man2/getsockopt.2:44
1897 #: build/C/man2/getsockopt.2:47
1898 msgid "getsockopt, setsockopt - get and set options on sockets"
1902 #: build/C/man2/getsockopt.2:57
1905 "B<int getsockopt(int >I<sockfd>B<, int >I<level>B<, int >I<optname>B<,>\n"
1906 "B< void *>I<optval>B<, socklen_t *>I<optlen>B<);>\n"
1907 "B<int setsockopt(int >I<sockfd>B<, int >I<level>B<, int >I<optname>B<,>\n"
1908 "B< const void *>I<optval>B<, socklen_t >I<optlen>B<);>\n"
1912 #: build/C/man2/getsockopt.2:67
1914 "B<getsockopt>() and B<setsockopt>() manipulate options for the socket "
1915 "referred to by the file descriptor I<sockfd>. Options may exist at multiple "
1916 "protocol levels; they are always present at the uppermost socket level."
1920 #: build/C/man2/getsockopt.2:86
1922 "When manipulating socket options, the level at which the option resides and "
1923 "the name of the option must be specified. To manipulate options at the "
1924 "sockets API level, I<level> is specified as B<SOL_SOCKET>. To manipulate "
1925 "options at any other level the protocol number of the appropriate protocol "
1926 "controlling the option is supplied. For example, to indicate that an option "
1927 "is to be interpreted by the B<TCP> protocol, I<level> should be set to the "
1928 "protocol number of B<TCP>; see B<getprotoent>(3)."
1932 #: build/C/man2/getsockopt.2:108
1934 "The arguments I<optval> and I<optlen> are used to access option values for "
1935 "B<setsockopt>(). For B<getsockopt>() they identify a buffer in which the "
1936 "value for the requested option(s) are to be returned. For B<getsockopt>(), "
1937 "I<optlen> is a value-result argument, initially containing the size of the "
1938 "buffer pointed to by I<optval>, and modified on return to indicate the "
1939 "actual size of the value returned. If no option value is to be supplied or "
1940 "returned, I<optval> may be NULL."
1944 #: build/C/man2/getsockopt.2:118
1946 "I<Optname> and any specified options are passed uninterpreted to the "
1947 "appropriate protocol module for interpretation. The include file "
1948 "I<E<lt>sys/socket.hE<gt>> contains definitions for socket level options, "
1949 "described below. Options at other protocol levels vary in format and name; "
1950 "consult the appropriate entries in section 4 of the manual."
1954 #: build/C/man2/getsockopt.2:127
1956 "Most socket-level options utilize an I<int> argument for I<optval>. For "
1957 "B<setsockopt>(), the argument should be nonzero to enable a boolean option, "
1958 "or zero if the option is to be disabled."
1962 #: build/C/man2/getsockopt.2:131
1964 "For a description of the available socket options see B<socket>(7) and the "
1965 "appropriate protocol man pages."
1969 #: build/C/man2/getsockopt.2:152
1971 "The address pointed to by I<optval> is not in a valid part of the process "
1972 "address space. For B<getsockopt>(), this error may also be returned if "
1973 "I<optlen> is not in a valid part of the process address space."
1977 #: build/C/man2/getsockopt.2:163
1979 "I<optlen> invalid in B<setsockopt>(). In some cases this error can also "
1980 "occur for an invalid value in I<optval> (e.g., for the B<IP_ADD_MEMBERSHIP> "
1981 "option described in B<ip>(7))."
1985 #: build/C/man2/getsockopt.2:163
1987 msgid "B<ENOPROTOOPT>"
1991 #: build/C/man2/getsockopt.2:166
1992 msgid "The option is unknown at the level indicated."
1995 #. SVr4 documents additional ENOMEM and ENOSR error codes, but does
1997 #. .BR SO_SNDLOWAT ", " SO_RCVLOWAT ", " SO_SNDTIMEO ", " SO_RCVTIMEO
2000 #: build/C/man2/getsockopt.2:178
2001 msgid "SVr4, 4.4BSD (these system calls first appeared in 4.2BSD), POSIX.1-2001."
2005 #: build/C/man2/getsockopt.2:199
2007 "The I<optlen> argument of B<getsockopt>() and B<setsockopt>() is in "
2008 "reality an I<int [*]> (and this is what 4.x BSD and libc4 and libc5 have). "
2009 "Some POSIX confusion resulted in the present I<socklen_t>, also used by "
2010 "glibc. See also B<accept>(2)."
2014 #: build/C/man2/getsockopt.2:202
2016 "Several of the socket options should be handled at lower levels of the "
2021 #: build/C/man2/getsockopt.2:213
2023 "B<ioctl>(2), B<socket>(2), B<getprotoent>(3), B<protocols>(5), B<ip>(7), "
2024 "B<packet>(7), B<socket>(7), B<tcp>(7), B<udp>(7), B<unix>(7)"
2028 #: build/C/man3/if_nameindex.3:26
2030 msgid "IF_NAMEINDEX"
2034 #: build/C/man3/if_nameindex.3:26
2040 #: build/C/man3/if_nameindex.3:29
2041 msgid "if_nameindex, if_freenameindex - get network interface names and indexes"
2045 #: build/C/man3/if_nameindex.3:32 build/C/man3/if_nametoindex.3:32
2047 msgid "B<#include E<lt>net/if.hE<gt>>\n"
2051 #: build/C/man3/if_nameindex.3:35
2054 "B<struct if_nameindex *if_nameindex(void);>\n"
2055 "B<void if_freenameindex(struct if_nameindex *>I<ptr>B<);>\n"
2059 #: build/C/man3/if_nameindex.3:46
2061 "The B<if_nameindex>() function returns an array of I<if_nameindex> "
2062 "structures, each containing information about one of the network interfaces "
2063 "on the local system. The I<if_nameindex> structure contains at least the "
2064 "following entries:"
2068 #: build/C/man3/if_nameindex.3:51
2071 " unsigned int if_index; /* Index of interface (1, 2, ...) */\n"
2072 " char *if_name; /* Null-terminated name (\"eth0\", etc.) */\n"
2076 #: build/C/man3/if_nameindex.3:65
2078 "The I<if_index> field contains the interface index. The I<ifa_name> field "
2079 "points to the null-terminated interface name. The end of the array is "
2080 "indicated by entry with I<if_index> set to zero and I<ifa_name> set to NULL."
2084 #: build/C/man3/if_nameindex.3:71
2086 "The data structure returned by B<if_nameindex>() is dynamically allocated "
2087 "and should be freed using B<if_freenameindex>() when no longer needed."
2091 #: build/C/man3/if_nameindex.3:78
2093 "On success, B<if_nameindex>() returns pointer to the array; on error, NULL "
2094 "is returned, and I<errno> is set appropriately."
2098 #: build/C/man3/if_nameindex.3:83
2099 msgid "B<if_nameindex>() may fail and set I<errno> if:"
2103 #: build/C/man3/if_nameindex.3:86
2104 msgid "Insufficient resources available."
2108 #: build/C/man3/if_nameindex.3:97
2110 "B<if_nameindex>() may also fail for any of the errors specified for "
2111 "B<socket>(2), B<bind>(2), B<ioctl>(2), B<getsockname>(2), B<recvmsg>(2), "
2112 "B<sendto>(2), or B<malloc>(3)."
2116 #: build/C/man3/if_nameindex.3:104
2118 "The B<if_nameindex>() function first appeared in glibc 2.1, but before "
2119 "glibc 2.3.4, the implementation supported only interfaces with IPv4 "
2120 "addresses. Support of interfaces that don't have IPv4 addresses is "
2121 "available only on kernels that support netlink."
2125 #: build/C/man3/if_nameindex.3:106 build/C/man3/if_nametoindex.3:94
2126 msgid "RFC\\ 3493, POSIX.1-2001."
2130 #: build/C/man3/if_nameindex.3:108 build/C/man3/if_nametoindex.3:96
2131 msgid "This function first appeared in BSDi."
2135 #: build/C/man3/if_nameindex.3:112
2137 "The program below demonstrates the use of the functions described on this "
2138 "page. An example of the output this program might produce is the following:"
2142 #: build/C/man3/if_nameindex.3:119
2152 #: build/C/man3/if_nameindex.3:127
2155 "#include E<lt>net/if.hE<gt>\n"
2156 "#include E<lt>stdio.hE<gt>\n"
2157 "#include E<lt>stdlib.hE<gt>\n"
2158 "#include E<lt>unistd.hE<gt>\n"
2162 #: build/C/man3/if_nameindex.3:132
2166 "main(int argc, char *argv[])\n"
2168 " struct if_nameindex *if_ni, *i;\n"
2172 #: build/C/man3/if_nameindex.3:138
2175 " if_ni = if_nameindex();\n"
2176 " if (if_ni == NULL) {\n"
2177 " perror(\"if_nameindex\");\n"
2178 " exit(EXIT_FAILURE);\n"
2183 #: build/C/man3/if_nameindex.3:141
2186 " for (i = if_ni; ! (i-E<gt>if_index == 0 && i-E<gt>if_name == NULL); "
2188 " printf(\"%u: %s\\en\", i-E<gt>if_index, i-E<gt>if_name);\n"
2192 #: build/C/man3/if_nameindex.3:143
2194 msgid " if_freenameindex(if_ni);\n"
2198 #: build/C/man3/if_nameindex.3:146 build/C/man2/select.2:585
2201 " exit(EXIT_SUCCESS);\n"
2206 #: build/C/man3/if_nameindex.3:154
2208 "B<getsockopt>(2), B<setsockopt>(2), B<getifaddrs>(3), B<if_indextoname>(3), "
2209 "B<if_nametoindex>(3), B<ifconfig>(8)"
2213 #: build/C/man3/if_nametoindex.3:25
2215 msgid "IF_NAMETOINDEX"
2219 #: build/C/man3/if_nametoindex.3:25
2225 #: build/C/man3/if_nametoindex.3:29
2227 "if_nametoindex, if_indextoname - mappings between network interface names "
2232 #: build/C/man3/if_nametoindex.3:34
2234 msgid "B<unsigned int if_nametoindex(const char *>I<ifname>B<);>\n"
2238 #: build/C/man3/if_nametoindex.3:36
2240 msgid "B<char *if_indextoname(unsigned int ifindex, char *>I<ifname>B<);>\n"
2244 #: build/C/man3/if_nametoindex.3:43
2246 "The B<if_nametoindex>() function returns the index of the network interface "
2247 "corresponding to the name I<ifname>."
2251 #: build/C/man3/if_nametoindex.3:54
2253 "The B<if_indextoname>() function returns the name of the network interface "
2254 "corresponding to the interface index I<ifindex>. The name is placed in the "
2255 "buffer pointed to by I<ifname>. The buffer must allow for the storage of at "
2256 "least B<IF_NAMESIZE> bytes."
2260 #: build/C/man3/if_nametoindex.3:61
2262 "On success, B<if_nametoindex>() returns the index number of the network "
2263 "interface; on error, 0 is returned and I<errno> is set appropriately."
2267 #: build/C/man3/if_nametoindex.3:69
2269 "On success, B<if_indextoname>() returns I<ifname>; on error, NULL is "
2270 "returned and I<errno> is set appropriately."
2274 #: build/C/man3/if_nametoindex.3:74
2275 msgid "B<if_indextoname>() may fail and set I<errno> if:"
2279 #: build/C/man3/if_nametoindex.3:74
2285 #: build/C/man3/if_nametoindex.3:77
2286 msgid "No interface found for the index."
2290 #: build/C/man3/if_nametoindex.3:85
2292 "B<if_nametoindex>() and B<if_indextoname>() may also fail for any of the "
2293 "errors specified for B<socket>(2) or B<ioctl>(2)."
2297 #: build/C/man3/if_nametoindex.3:92
2298 msgid "The B<if_nametoindex>() and B<if_indextoname>() functions are thread-safe."
2302 #: build/C/man3/if_nametoindex.3:100
2303 msgid "B<getifaddrs>(3), B<if_nameindex>(3), B<ifconfig>(8)"
2307 #: build/C/man2/listen.2:45
2313 #: build/C/man2/listen.2:45
2319 #: build/C/man2/listen.2:48
2320 msgid "listen - listen for connections on a socket"
2324 #: build/C/man2/listen.2:55
2326 msgid "B<int listen(int >I<sockfd>B<, int >I<backlog>B<);>\n"
2330 #: build/C/man2/listen.2:63
2332 "B<listen>() marks the socket referred to by I<sockfd> as a passive socket, "
2333 "that is, as a socket that will be used to accept incoming connection "
2334 "requests using B<accept>(2)."
2338 #: build/C/man2/listen.2:70
2340 "The I<sockfd> argument is a file descriptor that refers to a socket of type "
2341 "B<SOCK_STREAM> or B<SOCK_SEQPACKET>."
2345 #: build/C/man2/listen.2:82
2347 "The I<backlog> argument defines the maximum length to which the queue of "
2348 "pending connections for I<sockfd> may grow. If a connection request arrives "
2349 "when the queue is full, the client may receive an error with an indication "
2350 "of B<ECONNREFUSED> or, if the underlying protocol supports retransmission, "
2351 "the request may be ignored so that a later reattempt at connection succeeds."
2355 #: build/C/man2/listen.2:91
2356 msgid "Another socket is already listening on the same port."
2360 #: build/C/man2/listen.2:114 build/C/man2/send.2:386
2361 msgid "The argument I<sockfd> is not a socket."
2365 #: build/C/man2/listen.2:119
2366 msgid "The socket is not of a type that supports the B<listen>() operation."
2370 #: build/C/man2/listen.2:124
2372 "4.4BSD, POSIX.1-2001. The B<listen>() function call first appeared in "
2377 #: build/C/man2/listen.2:126
2378 msgid "To accept connections, the following steps are performed:"
2382 #: build/C/man2/listen.2:127 build/C/man2/select_tut.2:347
2388 #: build/C/man2/listen.2:130
2389 msgid "A socket is created with B<socket>(2)."
2393 #: build/C/man2/listen.2:130 build/C/man2/select_tut.2:356
2399 #: build/C/man2/listen.2:136
2401 "The socket is bound to a local address using B<bind>(2), so that other "
2402 "sockets may be B<connect>(2)ed to it."
2406 #: build/C/man2/listen.2:136 build/C/man2/select_tut.2:360
2412 #: build/C/man2/listen.2:140
2414 "A willingness to accept incoming connections and a queue limit for incoming "
2415 "connections are specified with B<listen>()."
2419 #: build/C/man2/listen.2:140 build/C/man2/select_tut.2:367
2425 #: build/C/man2/listen.2:143
2426 msgid "Connections are accepted with B<accept>(2)."
2430 #: build/C/man2/listen.2:166
2432 "The behavior of the I<backlog> argument on TCP sockets changed with Linux "
2433 "2.2. Now it specifies the queue length for I<completely> established "
2434 "sockets waiting to be accepted, instead of the number of incomplete "
2435 "connection requests. The maximum length of the queue for incomplete sockets "
2436 "can be set using I</proc/sys/net/ipv4/tcp_max_syn_backlog>. When syncookies "
2437 "are enabled there is no logical maximum length and this setting is ignored. "
2438 "See B<tcp>(7) for more information."
2441 #. The following is now rather historic information (MTK, Jun 05)
2442 #. Don't rely on this value in portable applications since BSD
2443 #. (and some BSD-derived systems) limit the backlog to 5.
2445 #: build/C/man2/listen.2:179
2447 "If the I<backlog> argument is greater than the value in "
2448 "I</proc/sys/net/core/somaxconn>, then it is silently truncated to that "
2449 "value; the default value in this file is 128. In kernels before 2.4.25, "
2450 "this limit was a hard coded value, B<SOMAXCONN>, with the value 128."
2454 #: build/C/man2/listen.2:188
2455 msgid "B<accept>(2), B<bind>(2), B<connect>(2), B<socket>(2), B<socket>(7)"
2459 #: build/C/man2/recv.2:41
2465 #: build/C/man2/recv.2:44
2466 msgid "recv, recvfrom, recvmsg - receive a message from a socket"
2470 #: build/C/man2/recv.2:49 build/C/man2/select.2:53 build/C/man2/select_tut.2:47
2472 msgid "B<#include E<lt>sys/types.hE<gt>>\n"
2476 #: build/C/man2/recv.2:53
2479 "B<ssize_t recv(int >I<sockfd>B<, void *>I<buf>B<, size_t >I<len>B<, int "
2484 #: build/C/man2/recv.2:56
2487 "B<ssize_t recvfrom(int >I<sockfd>B<, void *>I<buf>B<, size_t >I<len>B<, int "
2489 "B< struct sockaddr *>I<src_addr>B<, socklen_t "
2490 "*>I<addrlen>B<);>\n"
2494 #: build/C/man2/recv.2:58
2497 "B<ssize_t recvmsg(int >I<sockfd>B<, struct msghdr *>I<msg>B<, int "
2502 #: build/C/man2/recv.2:70
2504 "The B<recv>(), B<recvfrom>(), and B<recvmsg>() calls are used to receive "
2505 "messages from a socket. They may be used to receive data on both "
2506 "connectionless and connection-oriented sockets. This page first describes "
2507 "common features of all three system calls, and then describes the "
2508 "differences between the calls."
2512 #: build/C/man2/recv.2:76
2514 "All three calls return the length of the message on successful completion. "
2515 "If a message is too long to fit in the supplied buffer, excess bytes may be "
2516 "discarded depending on the type of socket the message is received from."
2520 #: build/C/man2/recv.2:86
2522 "If no messages are available at the socket, the receive calls wait for a "
2523 "message to arrive, unless the socket is nonblocking (see B<fcntl>(2)), in "
2524 "which case the value -1 is returned and the external variable I<errno> is "
2525 "set to B<EAGAIN> or B<EWOULDBLOCK>. The receive calls normally return any "
2526 "data available, up to the requested amount, rather than waiting for receipt "
2527 "of the full amount requested."
2531 #: build/C/man2/recv.2:93
2533 "An application can use B<select>(2), B<poll>(2), or B<epoll>(7) to "
2534 "determine when more data arrives on a socket."
2538 #: build/C/man2/recv.2:93 build/C/man2/send.2:160
2540 msgid "The flags argument"
2544 #: build/C/man2/recv.2:97
2546 "The I<flags> argument is formed by ORing one or more of the following "
2551 #: build/C/man2/recv.2:97
2553 msgid "B<MSG_CMSG_CLOEXEC> (B<recvmsg>() only; since Linux 2.6.23)"
2557 #: build/C/man2/recv.2:108
2559 "Set the close-on-exec flag for the file descriptor received via a UNIX "
2560 "domain file descriptor using the B<SCM_RIGHTS> operation (described in "
2561 "B<unix>(7)). This flag is useful for the same reasons as the B<O_CLOEXEC> "
2562 "flag of B<open>(2)."
2566 #: build/C/man2/recv.2:108 build/C/man2/send.2:188
2568 msgid "B<MSG_DONTWAIT> (since Linux 2.2)"
2572 #: build/C/man2/recv.2:118
2574 "Enables nonblocking operation; if the operation would block, the call fails "
2575 "with the error B<EAGAIN> or B<EWOULDBLOCK> (this can also be enabled using "
2576 "the B<O_NONBLOCK> flag with the B<F_SETFL> B<fcntl>(2))."
2580 #: build/C/man2/recv.2:118
2582 msgid "B<MSG_ERRQUEUE> (since Linux 2.2)"
2586 #: build/C/man2/recv.2:137
2588 "This flag specifies that queued errors should be received from the socket "
2589 "error queue. The error is passed in an ancillary message with a type "
2590 "dependent on the protocol (for IPv4 B<IP_RECVERR>). The user should supply "
2591 "a buffer of sufficient size. See B<cmsg>(3) and B<ip>(7) for more "
2592 "information. The payload of the original packet that caused the error is "
2593 "passed as normal data via I<msg_iovec>. The original destination address of "
2594 "the datagram that caused the error is supplied via I<msg_name>."
2598 #: build/C/man2/recv.2:149 build/C/man2/recv.2:212
2600 "For local errors, no address is passed (this can be checked with the "
2601 "I<cmsg_len> member of the I<cmsghdr>). For error receives, the "
2602 "B<MSG_ERRQUEUE> is set in the I<msghdr>. After an error has been passed, "
2603 "the pending socket error is regenerated based on the next queued error and "
2604 "will be passed on the next socket operation."
2608 #: build/C/man2/recv.2:153
2609 msgid "The error is supplied in a I<sock_extended_err> structure:"
2613 #: build/C/man2/recv.2:160
2616 "#define SO_EE_ORIGIN_NONE 0\n"
2617 "#define SO_EE_ORIGIN_LOCAL 1\n"
2618 "#define SO_EE_ORIGIN_ICMP 2\n"
2619 "#define SO_EE_ORIGIN_ICMP6 3\n"
2623 #: build/C/man2/recv.2:172
2626 "struct sock_extended_err\n"
2628 " uint32_t ee_errno; /* error number */\n"
2629 " uint8_t ee_origin; /* where the error originated */\n"
2630 " uint8_t ee_type; /* type */\n"
2631 " uint8_t ee_code; /* code */\n"
2632 " uint8_t ee_pad; /* padding */\n"
2633 " uint32_t ee_info; /* additional information */\n"
2634 " uint32_t ee_data; /* other data */\n"
2635 " /* More data may follow */\n"
2640 #: build/C/man2/recv.2:174
2642 msgid "struct sockaddr *SO_EE_OFFENDER(struct sock_extended_err *);\n"
2646 #: build/C/man2/recv.2:198
2648 "I<ee_errno> contains the I<errno> number of the queued error. I<ee_origin> "
2649 "is the origin code of where the error originated. The other fields are "
2650 "protocol-specific. The macro B<SOCK_EE_OFFENDER> returns a pointer to the "
2651 "address of the network object where the error originated from given a "
2652 "pointer to the ancillary message. If this address is not known, the "
2653 "I<sa_family> member of the I<sockaddr> contains B<AF_UNSPEC> and the other "
2654 "fields of the I<sockaddr> are undefined. The payload of the packet that "
2655 "caused the error is passed as normal data."
2659 #: build/C/man2/recv.2:212 build/C/man2/recv.2:401 build/C/man2/send.2:230
2665 #: build/C/man2/recv.2:219
2667 "This flag requests receipt of out-of-band data that would not be received in "
2668 "the normal data stream. Some protocols place expedited data at the head of "
2669 "the normal data queue, and thus this flag cannot be used with such "
2674 #: build/C/man2/recv.2:219
2680 #: build/C/man2/recv.2:226
2682 "This flag causes the receive operation to return data from the beginning of "
2683 "the receive queue without removing that data from the queue. Thus, a "
2684 "subsequent receive call will return the same data."
2688 #: build/C/man2/recv.2:226
2690 msgid "B<MSG_TRUNC> (since Linux 2.2)"
2694 #: build/C/man2/recv.2:234
2696 "For raw (B<AF_PACKET>), Internet datagram (since Linux 2.4.27/2.6.8), "
2697 "netlink (since Linux 2.6.22), and UNIX datagram (since Linux 3.4) sockets: "
2698 "return the real length of the packet or datagram, even when it was longer "
2699 "than the passed buffer."
2703 #: build/C/man2/recv.2:237
2704 msgid "For use with Internet stream sockets, see B<tcp>(7)."
2708 #: build/C/man2/recv.2:237
2710 msgid "B<MSG_WAITALL> (since Linux 2.2)"
2714 #: build/C/man2/recv.2:245
2716 "This flag requests that the operation block until the full request is "
2717 "satisfied. However, the call may still return less data than requested if a "
2718 "signal is caught, an error or disconnect occurs, or the next data to be "
2719 "received is of a different type than that returned."
2723 #: build/C/man2/recv.2:245
2729 #: build/C/man2/recv.2:251
2731 "B<recvfrom>() places the received message into the buffer I<buf>. The "
2732 "caller must specify the size of the buffer in I<len>."
2735 #. (Note: for datagram sockets in both the UNIX and Internet domains,
2739 #. is also filled in for stream sockets in the UNIX domain, but is not
2740 #. filled in for stream sockets in the Internet domain.)
2741 #. [The above notes on AF_UNIX and AF_INET sockets apply as at
2742 #. Kernel 2.4.18. (MTK, 22 Jul 02)]
2744 #: build/C/man2/recv.2:279
2746 "If I<src_addr> is not NULL, and the underlying protocol provides the source "
2747 "address of the message, that source address is placed in the buffer pointed "
2748 "to by I<src_addr>. In this case, I<addrlen> is a value-result argument. "
2749 "Before the call, it should be initialized to the size of the buffer "
2750 "associated with I<src_addr>. Upon return, I<addrlen> is updated to contain "
2751 "the actual size of the source address. The returned address is truncated if "
2752 "the buffer provided is too small; in this case, I<addrlen> will return a "
2753 "value greater than was supplied to the call."
2757 #: build/C/man2/recv.2:286
2759 "If the caller is not interested in the source address, I<src_addr> and "
2760 "I<addrlen> should be specified as NULL."
2764 #: build/C/man2/recv.2:286
2770 #: build/C/man2/recv.2:294
2772 "The B<recv>() call is normally used only on a I<connected> socket (see "
2773 "B<connect>(2)). It is equivalent to the call:"
2777 #: build/C/man2/recv.2:297
2779 msgid " recvfrom(fd, buf, len, flags, NULL, 0));\n"
2783 #: build/C/man2/recv.2:297
2789 #: build/C/man2/recv.2:305
2791 "The B<recvmsg>() call uses a I<msghdr> structure to minimize the number of "
2792 "directly supplied arguments. This structure is defined as follows in "
2793 "I<E<lt>sys/socket.hE<gt>>:"
2797 #: build/C/man2/recv.2:312
2800 "struct iovec { /* Scatter/gather array items */\n"
2801 " void *iov_base; /* Starting address */\n"
2802 " size_t iov_len; /* Number of bytes to transfer */\n"
2807 #: build/C/man2/recv.2:322
2811 " void *msg_name; /* optional address */\n"
2812 " socklen_t msg_namelen; /* size of address */\n"
2813 " struct iovec *msg_iov; /* scatter/gather array */\n"
2814 " size_t msg_iovlen; /* # elements in msg_iov */\n"
2815 " void *msg_control; /* ancillary data, see below */\n"
2816 " size_t msg_controllen; /* ancillary data buffer len */\n"
2817 " int msg_flags; /* flags on received message */\n"
2822 #: build/C/man2/recv.2:338
2824 "The I<msg_name> field points to a caller-allocated buffer that is used to "
2825 "return the source address if the socket is unconnected. The caller should "
2826 "set I<msg_namelen> to the size of this buffer before this call; upon return "
2827 "from a successful call, I<msg_namelen> will contain the length of the "
2828 "returned address. If the application does not need to know the source "
2829 "address, I<msg_name> can be specified as NULL."
2833 #: build/C/man2/recv.2:345
2835 "The fields I<msg_iov> and I<msg_iovlen> describe scatter-gather locations, "
2836 "as discussed in B<readv>(2)."
2840 #: build/C/man2/recv.2:360
2842 "The field I<msg_control>, which has length I<msg_controllen>, points to a "
2843 "buffer for other protocol control-related messages or miscellaneous "
2844 "ancillary data. When B<recvmsg>() is called, I<msg_controllen> should "
2845 "contain the length of the available buffer in I<msg_control>; upon return "
2846 "from a successful call it will contain the length of the control message "
2851 #: build/C/man2/recv.2:362
2852 msgid "The messages are of the form:"
2856 #: build/C/man2/recv.2:372
2859 "struct cmsghdr {\n"
2860 " socklen_t cmsg_len; /* data byte count, including hdr */\n"
2861 " int cmsg_level; /* originating protocol */\n"
2862 " int cmsg_type; /* protocol-specific type */\n"
2864 " unsigned char cmsg_data[]; */\n"
2869 #: build/C/man2/recv.2:377
2870 msgid "Ancillary data should be accessed only by the macros defined in B<cmsg>(3)."
2874 #: build/C/man2/recv.2:380
2876 "As an example, Linux uses this ancillary data mechanism to pass extended "
2877 "errors, IP options, or file descriptors over UNIX domain sockets."
2881 #: build/C/man2/recv.2:388
2883 "The I<msg_flags> field in the I<msghdr> is set on return of B<recvmsg>(). "
2884 "It can contain several flags:"
2888 #: build/C/man2/recv.2:388
2894 #: build/C/man2/recv.2:393
2896 "indicates end-of-record; the data returned completed a record (generally "
2897 "used with sockets of type B<SOCK_SEQPACKET>)."
2901 #: build/C/man2/recv.2:393
2903 msgid "B<MSG_TRUNC>"
2907 #: build/C/man2/recv.2:397
2909 "indicates that the trailing portion of a datagram was discarded because the "
2910 "datagram was larger than the buffer supplied."
2914 #: build/C/man2/recv.2:397
2916 msgid "B<MSG_CTRUNC>"
2920 #: build/C/man2/recv.2:401
2922 "indicates that some control data were discarded due to lack of space in the "
2923 "buffer for ancillary data."
2927 #: build/C/man2/recv.2:404
2928 msgid "is returned to indicate that expedited or out-of-band data were received."
2932 #: build/C/man2/recv.2:404
2934 msgid "B<MSG_ERRQUEUE>"
2938 #: build/C/man2/recv.2:408
2940 "indicates that no data was received but an extended error from the socket "
2945 #: build/C/man2/recv.2:414
2947 "These calls return the number of bytes received, or -1 if an error "
2948 "occurred. In the event of an error, I<errno> is set to indicate the error."
2952 #: build/C/man2/recv.2:417
2954 "When a stream socket peer has performed an orderly shutdown, the return "
2955 "value will be 0 (the traditional \"end-of-file\" return)."
2959 #: build/C/man2/recv.2:421
2961 "Datagram sockets in various domains (e.g., the UNIX and Internet domains) "
2962 "permit zero-length datagrams. When such a datagram is received, the return "
2967 #: build/C/man2/recv.2:424
2969 "The value 0 may also be returned if the requested number of bytes to receive "
2970 "from a stream socket was 0."
2974 #: build/C/man2/recv.2:429
2976 "These are some standard errors generated by the socket layer. Additional "
2977 "errors may be generated and returned from the underlying protocol modules; "
2978 "see their manual pages."
2981 #. Actually EAGAIN on Linux
2983 #: build/C/man2/recv.2:438
2985 "The socket is marked nonblocking and the receive operation would block, or a "
2986 "receive timeout had been set and the timeout expired before data was "
2987 "received. POSIX.1-2001 allows either error to be returned for this case, "
2988 "and does not require these constants to have the same value, so a portable "
2989 "application should check for both possibilities."
2993 #: build/C/man2/recv.2:443
2994 msgid "The argument I<sockfd> is an invalid descriptor."
2998 #: build/C/man2/recv.2:447
3000 "A remote host refused to allow the network connection (typically because it "
3001 "is not running the requested service)."
3005 #: build/C/man2/recv.2:451
3006 msgid "The receive buffer pointer(s) point outside the process's address space."
3010 #: build/C/man2/recv.2:456
3012 "The receive was interrupted by delivery of a signal before any data were "
3013 "available; see B<signal>(7)."
3017 #: build/C/man2/recv.2:460 build/C/man2/send.2:355
3018 msgid "Invalid argument passed."
3022 #: build/C/man2/recv.2:464
3023 msgid "Could not allocate memory for B<recvmsg>()."
3027 #: build/C/man2/recv.2:464 build/C/man2/send.2:378
3033 #: build/C/man2/recv.2:471
3035 "The socket is associated with a connection-oriented protocol and has not "
3036 "been connected (see B<connect>(2) and B<accept>(2))."
3040 #: build/C/man2/recv.2:476
3041 msgid "The argument I<sockfd> does not refer to a socket."
3045 #: build/C/man2/recv.2:479
3046 msgid "4.4BSD (these function calls first appeared in 4.2BSD), POSIX.1-2001."
3050 #: build/C/man2/recv.2:486
3052 "POSIX.1-2001 describes only the B<MSG_OOB>, B<MSG_PEEK>, and B<MSG_WAITALL> "
3057 #: build/C/man2/recv.2:492
3058 msgid "The I<socklen_t> type was invented by POSIX. See also B<accept>(2)."
3061 #. glibc bug raised 12 Mar 2006
3062 #. http://sourceware.org/bugzilla/show_bug.cgi?id=2448
3063 #. The problem is an underlying kernel issue: the size of the
3064 #. __kernel_size_t type used to type this field varies
3065 #. across architectures, but socklen_t is always 32 bits.
3067 #: build/C/man2/recv.2:506 build/C/man2/send.2:428
3069 "According to POSIX.1-2001, the I<msg_controllen> field of the I<msghdr> "
3070 "structure should be typed as I<socklen_t>, but glibc currently types it as "
3075 #: build/C/man2/recv.2:511
3077 "See B<recvmmsg>(2) for information about a Linux-specific system call that "
3078 "can be used to receive multiple datagrams in a single call."
3082 #: build/C/man2/recv.2:516
3083 msgid "An example of the use of B<recvfrom>() is shown in B<getaddrinfo>(3)."
3087 #: build/C/man2/recv.2:527
3089 "B<fcntl>(2), B<getsockopt>(2), B<read>(2), B<recvmmsg>(2), B<select>(2), "
3090 "B<shutdown>(2), B<socket>(2), B<cmsg>(3), B<sockatmark>(3), B<socket>(7)"
3094 #: build/C/man2/recvmmsg.2:31
3100 #: build/C/man2/recvmmsg.2:31
3106 #: build/C/man2/recvmmsg.2:34
3107 msgid "recvmmsg - receive multiple messages on a socket"
3111 #: build/C/man2/recvmmsg.2:38 build/C/man2/sendmmsg.2:35
3114 "B<#define _GNU_SOURCE /* See feature_test_macros(7) */>\n"
3115 "B<#include E<lt>sys/socket.hE<gt>>\n"
3119 #: build/C/man2/recvmmsg.2:41
3122 "B<int recvmmsg(int >I<sockfd>B<, struct mmsghdr *>I<msgvec>B<, unsigned int "
3127 #: build/C/man2/recvmmsg.2:43
3129 msgid "B< unsigned int >I<flags>B<, struct timespec *>I<timeout>B<);>\n"
3133 #: build/C/man2/recvmmsg.2:55
3135 "The B<recvmmsg>() system call is an extension of B<recvmsg>(2) that allows "
3136 "the caller to receive multiple messages from a socket using a single system "
3137 "call. (This has performance benefits for some applications.) A further "
3138 "extension over B<recvmsg>(2) is support for a timeout on the receive "
3143 #: build/C/man2/recvmmsg.2:59
3145 "The I<sockfd> argument is the file descriptor of the socket to receive data "
3150 #: build/C/man2/recvmmsg.2:67 build/C/man2/sendmmsg.2:62
3152 "The I<msgvec> argument is a pointer to an array of I<mmsghdr> structures. "
3153 "The size of this array is specified in I<vlen>."
3157 #: build/C/man2/recvmmsg.2:73 build/C/man2/sendmmsg.2:68
3158 msgid "The I<mmsghdr> structure is defined in I<E<lt>sys/socket.hE<gt>> as:"
3162 #: build/C/man2/recvmmsg.2:80
3165 "struct mmsghdr {\n"
3166 " struct msghdr msg_hdr; /* Message header */\n"
3167 " unsigned int msg_len; /* Number of received bytes for header */\n"
3172 #: build/C/man2/recvmmsg.2:95
3174 "The I<msg_hdr> field is a I<msghdr> structure, as described in "
3175 "B<recvmsg>(2). The I<msg_len> field is the number of bytes returned for the "
3176 "message in the entry. This field has the same value as the return value of "
3177 "a single B<recvmsg>(2) on the header."
3181 #: build/C/man2/recvmmsg.2:102
3183 "The I<flags> argument contains flags ORed together. The flags are the same "
3184 "as documented for B<recvmsg>(2), with the following addition:"
3188 #: build/C/man2/recvmmsg.2:102
3190 msgid "B<MSG_WAITFORONE> (since Linux 2.6.34)"
3194 #: build/C/man2/recvmmsg.2:107
3195 msgid "Turns on B<MSG_DONTWAIT> after the first message has been received."
3199 #: build/C/man2/recvmmsg.2:122
3201 "The I<timeout> argument points to a I<struct timespec> (see "
3202 "B<clock_gettime>(2)) defining a timeout (seconds plus nanoseconds) for the "
3203 "receive operation (I<but see BUGS!>). (This interval will be rounded up to "
3204 "the system clock granularity, and kernel scheduling delays mean that the "
3205 "blocking interval may overrun by a small amount.) If I<timeout> is NULL, "
3206 "then the operation blocks indefinitely."
3210 #: build/C/man2/recvmmsg.2:133
3212 "A blocking B<recvmmsg>() call blocks until I<vlen> messages have been "
3213 "received or until the timeout expires. A nonblocking call reads as many "
3214 "messages as are available (up to the limit specified by I<vlen>) and "
3215 "returns immediately."
3219 #: build/C/man2/recvmmsg.2:148
3221 "On return from B<recvmmsg>(), successive elements of I<msgvec> are updated "
3222 "to contain information about each received message: I<msg_len> contains the "
3223 "size of the received message; the subfields of I<msg_hdr> are updated as "
3224 "described in B<recvmsg>(2). The return value of the call indicates the "
3225 "number of elements of I<msgvec> that have been updated."
3229 #: build/C/man2/recvmmsg.2:156
3231 "On success, B<recvmmsg>() returns the number of messages received in "
3232 "I<msgvec>; on error, -1 is returned, and I<errno> is set to indicate the "
3237 #: build/C/man2/recvmmsg.2:160
3239 "Errors are as for B<recvmsg>(2). In addition, the following error can "
3244 #: build/C/man2/recvmmsg.2:164
3245 msgid "I<timeout> is invalid."
3249 #: build/C/man2/recvmmsg.2:169
3251 "The B<recvmmsg>() system call was added in Linux 2.6.33. Support in glibc "
3252 "was added in version 2.12."
3256 #: build/C/man2/recvmmsg.2:172
3257 msgid "B<recvmmsg>() is Linux-specific."
3261 #: build/C/man2/recvmmsg.2:180
3263 "The following program uses B<recvmmsg>() to receive multiple messages on a "
3264 "socket and stores them in multiple buffers. The call returns if all buffers "
3265 "are filled or if the timeout specified has expired."
3269 #: build/C/man2/recvmmsg.2:183
3271 "The following snippet periodically generates UDP datagrams containing a "
3276 #: build/C/man2/recvmmsg.2:188
3279 "$B< while true; do echo $RANDOM E<gt> /dev/udp/127.0.0.1/1234; >\n"
3280 "B<sleep 0.25; done>\n"
3284 #: build/C/man2/recvmmsg.2:193
3286 "These datagrams are read by the example application, which can give the "
3291 #: build/C/man2/recvmmsg.2:203
3295 "5 messages received\n"
3304 #: build/C/man2/recvmmsg.2:214
3307 "#define _GNU_SOURCE\n"
3308 "#include E<lt>netinet/ip.hE<gt>\n"
3309 "#include E<lt>stdio.hE<gt>\n"
3310 "#include E<lt>stdlib.hE<gt>\n"
3311 "#include E<lt>string.hE<gt>\n"
3312 "#include E<lt>sys/socket.hE<gt>\n"
3316 #: build/C/man2/recvmmsg.2:227
3323 "#define BUFSIZE 200\n"
3324 "#define TIMEOUT 1\n"
3325 " int sockfd, retval, i;\n"
3326 " struct sockaddr_in sa;\n"
3327 " struct mmsghdr msgs[VLEN];\n"
3328 " struct iovec iovecs[VLEN];\n"
3329 " char bufs[VLEN][BUFSIZE+1];\n"
3330 " struct timespec timeout;\n"
3334 #: build/C/man2/recvmmsg.2:233 build/C/man2/sendmmsg.2:201
3337 " sockfd = socket(AF_INET, SOCK_DGRAM, 0);\n"
3338 " if (sockfd == -1) {\n"
3339 " perror(\"socket()\");\n"
3340 " exit(EXIT_FAILURE);\n"
3345 #: build/C/man2/recvmmsg.2:241
3348 " sa.sin_family = AF_INET;\n"
3349 " sa.sin_addr.s_addr = htonl(INADDR_LOOPBACK);\n"
3350 " sa.sin_port = htons(1234);\n"
3351 " if (bind(sockfd, (struct sockaddr *) &sa, sizeof(sa)) == -1) {\n"
3352 " perror(\"bind()\");\n"
3353 " exit(EXIT_FAILURE);\n"
3358 #: build/C/man2/recvmmsg.2:249
3361 " memset(msgs, 0, sizeof(msgs));\n"
3362 " for (i = 0; i E<lt> VLEN; i++) {\n"
3363 " iovecs[i].iov_base = bufs[i];\n"
3364 " iovecs[i].iov_len = BUFSIZE;\n"
3365 " msgs[i].msg_hdr.msg_iov = &iovecs[i];\n"
3366 " msgs[i].msg_hdr.msg_iovlen = 1;\n"
3371 #: build/C/man2/recvmmsg.2:252
3374 " timeout.tv_sec = TIMEOUT;\n"
3375 " timeout.tv_nsec = 0;\n"
3379 #: build/C/man2/recvmmsg.2:258
3382 " retval = recvmmsg(sockfd, msgs, VLEN, 0, &timeout);\n"
3383 " if (retval == -1) {\n"
3384 " perror(\"recvmmsg()\");\n"
3385 " exit(EXIT_FAILURE);\n"
3390 #: build/C/man2/recvmmsg.2:266
3393 " printf(\"%d messages received\\en\", retval);\n"
3394 " for (i = 0; i E<lt> retval; i++) {\n"
3395 " bufs[i][msgs[i].msg_len] = 0;\n"
3396 " printf(\"%d %s\", i+1, bufs[i]);\n"
3398 " exit(EXIT_SUCCESS);\n"
3402 #. FIXME . https://bugzilla.kernel.org/show_bug.cgi?id=75371
3403 #. http://thread.gmane.org/gmane.linux.man/5677
3405 #: build/C/man2/recvmmsg.2:278
3407 "The I<timeout> argument does not work as intended. The timeout is checked "
3408 "only after the receipt of each datagram, so that if up to I<vlen-1> "
3409 "datagrams are received before the timeout expires, but then no further "
3410 "datagrams are received, the call will block forever."
3414 #: build/C/man2/recvmmsg.2:285
3416 "B<clock_gettime>(2), B<recvmsg>(2), B<sendmmsg>(2), B<sendmsg>(2), "
3417 "B<socket>(2), B<socket>(7)"
3421 #: build/C/man2/select.2:38
3427 #: build/C/man2/select.2:38
3433 #: build/C/man2/select.2:42 build/C/man2/select_tut.2:36
3435 "select, pselect, FD_CLR, FD_ISSET, FD_SET, FD_ZERO - synchronous I/O "
3440 #: build/C/man2/select.2:45 build/C/man2/select_tut.2:39
3442 msgid "/* According to POSIX.1-2001 */\n"
3446 #: build/C/man2/select.2:47 build/C/man2/select.2:68 build/C/man2/select_tut.2:41 build/C/man2/select_tut.2:62
3448 msgid "B<#include E<lt>sys/select.hE<gt>>\n"
3452 #: build/C/man2/select.2:49 build/C/man2/select_tut.2:43
3454 msgid "/* According to earlier standards */\n"
3458 #: build/C/man2/select.2:51 build/C/man2/select_tut.2:45
3460 msgid "B<#include E<lt>sys/time.hE<gt>>\n"
3464 #: build/C/man2/select.2:55 build/C/man2/select_tut.2:49
3466 msgid "B<#include E<lt>unistd.hE<gt>>\n"
3470 #: build/C/man2/select.2:58
3473 "B<int select(int >I<nfds>B<, fd_set *>I<readfds>B<, fd_set "
3474 "*>I<writefds>B<,>\n"
3475 "B< fd_set *>I<exceptfds>B<, struct timeval *>I<timeout>B<);>\n"
3479 #: build/C/man2/select.2:60 build/C/man2/select_tut.2:54
3481 msgid "B<void FD_CLR(int >I<fd>B<, fd_set *>I<set>B<);>\n"
3485 #: build/C/man2/select.2:62 build/C/man2/select_tut.2:56
3487 msgid "B<int FD_ISSET(int >I<fd>B<, fd_set *>I<set>B<);>\n"
3491 #: build/C/man2/select.2:64 build/C/man2/select_tut.2:58
3493 msgid "B<void FD_SET(int >I<fd>B<, fd_set *>I<set>B<);>\n"
3497 #: build/C/man2/select.2:66 build/C/man2/select_tut.2:60
3499 msgid "B<void FD_ZERO(fd_set *>I<set>B<);>\n"
3503 #: build/C/man2/select.2:72
3506 "B<int pselect(int >I<nfds>B<, fd_set *>I<readfds>B<, fd_set "
3507 "*>I<writefds>B<,>\n"
3508 "B< fd_set *>I<exceptfds>B<, const struct timespec "
3509 "*>I<timeout>B<,>\n"
3510 "B< const sigset_t *>I<sigmask>B<);>\n"
3514 #: build/C/man2/select.2:77 build/C/man2/select_tut.2:71 build/C/man3/sockatmark.3:36
3515 msgid "Feature Test Macro Requirements for glibc (see B<feature_test_macros>(7)):"
3519 #: build/C/man2/select.2:81 build/C/man2/select_tut.2:75
3521 "B<pselect>(): _POSIX_C_SOURCE\\ E<gt>=\\ 200112L || _XOPEN_SOURCE\\ E<gt>=\\ "
3526 #: build/C/man2/select.2:93
3528 "B<select>() and B<pselect>() allow a program to monitor multiple file "
3529 "descriptors, waiting until one or more of the file descriptors become "
3530 "\"ready\" for some class of I/O operation (e.g., input possible). A file "
3531 "descriptor is considered ready if it is possible to perform a corresponding "
3532 "I/O operation (e.g., B<read>(2) without blocking, or a sufficiently small "
3537 #: build/C/man2/select.2:99
3539 "The operation of B<select>() and B<pselect>() is identical, other than "
3540 "these three differences:"
3544 #: build/C/man2/select.2:99
3550 #: build/C/man2/select.2:109
3552 "B<select>() uses a timeout that is a I<struct timeval> (with seconds and "
3553 "microseconds), while B<pselect>() uses a I<struct timespec> (with seconds "
3558 #: build/C/man2/select.2:109
3564 #: build/C/man2/select.2:117
3566 "B<select>() may update the I<timeout> argument to indicate how much time "
3567 "was left. B<pselect>() does not change this argument."
3571 #: build/C/man2/select.2:117
3577 #: build/C/man2/select.2:126
3579 "B<select>() has no I<sigmask> argument, and behaves as B<pselect>() called "
3580 "with NULL I<sigmask>."
3584 #: build/C/man2/select.2:144
3586 "Three independent sets of file descriptors are watched. Those listed in "
3587 "I<readfds> will be watched to see if characters become available for reading "
3588 "(more precisely, to see if a read will not block; in particular, a file "
3589 "descriptor is also ready on end-of-file), those in I<writefds> will be "
3590 "watched to see if space is available for write (though a large write may "
3591 "still block), and those in I<exceptfds> will be watched for exceptions. On "
3592 "exit, the sets are modified in place to indicate which file descriptors "
3593 "actually changed status. Each of the three file descriptor sets may be "
3594 "specified as NULL if no file descriptors are to be watched for the "
3595 "corresponding class of events."
3599 #: build/C/man2/select.2:157
3601 "Four macros are provided to manipulate the sets. B<FD_ZERO>() clears a "
3602 "set. B<FD_SET>() and B<FD_CLR>() respectively add and remove a given file "
3603 "descriptor from a set. B<FD_ISSET>() tests to see if a file descriptor is "
3604 "part of the set; this is useful after B<select>() returns."
3608 #: build/C/man2/select.2:160
3610 "I<nfds> is the highest-numbered file descriptor in any of the three sets, "
3615 #: build/C/man2/select.2:167
3617 "The I<timeout> argument specifies the interval that B<select>() should "
3618 "block waiting for a file descriptor to become ready. The call will block "
3623 #: build/C/man2/select.2:167 build/C/man2/select.2:169 build/C/man2/select.2:171
3629 #: build/C/man2/select.2:169
3630 msgid "a file descriptor becomes ready;"
3634 #: build/C/man2/select.2:171
3635 msgid "the call is interrupted by a signal handler; or"
3639 #: build/C/man2/select.2:173
3640 msgid "the timeout expires."
3644 #: build/C/man2/select.2:190
3646 "Note that the I<timeout> interval will be rounded up to the system clock "
3647 "granularity, and kernel scheduling delays mean that the blocking interval "
3648 "may overrun by a small amount. If both fields of the I<timeval> structure "
3649 "are zero, then B<select>() returns immediately. (This is useful for "
3650 "polling.) If I<timeout> is NULL (no timeout), B<select>() can block "
3655 #: build/C/man2/select.2:200
3657 "I<sigmask> is a pointer to a signal mask (see B<sigprocmask>(2)); if it is "
3658 "not NULL, then B<pselect>() first replaces the current signal mask by the "
3659 "one pointed to by I<sigmask>, then does the \"select\" function, and then "
3660 "restores the original signal mask."
3664 #: build/C/man2/select.2:206
3666 "Other than the difference in the precision of the I<timeout> argument, the "
3667 "following B<pselect>() call:"
3671 #: build/C/man2/select.2:210
3674 " ready = pselect(nfds, &readfds, &writefds, &exceptfds,\n"
3675 " timeout, &sigmask);\n"
3679 #: build/C/man2/select.2:215
3680 msgid "is equivalent to I<atomically> executing the following calls:"
3684 #: build/C/man2/select.2:218
3686 msgid " sigset_t origmask;\n"
3690 #: build/C/man2/select.2:222
3693 " pthread_sigmask(SIG_SETMASK, &sigmask, &origmask);\n"
3694 " ready = select(nfds, &readfds, &writefds, &exceptfds, timeout);\n"
3695 " pthread_sigmask(SIG_SETMASK, &origmask, NULL);\n"
3699 #: build/C/man2/select.2:243
3701 "The reason that B<pselect>() is needed is that if one wants to wait for "
3702 "either a signal or for a file descriptor to become ready, then an atomic "
3703 "test is needed to prevent race conditions. (Suppose the signal handler sets "
3704 "a global flag and returns. Then a test of this global flag followed by a "
3705 "call of B<select>() could hang indefinitely if the signal arrived just "
3706 "after the test but just before the call. By contrast, B<pselect>() allows "
3707 "one to first block signals, handle the signals that have come in, then call "
3708 "B<pselect>() with the desired I<sigmask>, avoiding the race.)"
3712 #: build/C/man2/select.2:243
3718 #: build/C/man2/select.2:247
3720 "The time structures involved are defined in I<E<lt>sys/time.hE<gt>> and look "
3725 #: build/C/man2/select.2:254
3728 "struct timeval {\n"
3729 " long tv_sec; /* seconds */\n"
3730 " long tv_usec; /* microseconds */\n"
3735 #: build/C/man2/select.2:258
3740 #: build/C/man2/select.2:265
3743 "struct timespec {\n"
3744 " long tv_sec; /* seconds */\n"
3745 " long tv_nsec; /* nanoseconds */\n"
3750 #: build/C/man2/select.2:269
3751 msgid "(However, see below on the POSIX.1-2001 versions.)"
3755 #: build/C/man2/select.2:277
3757 "Some code calls B<select>() with all three sets empty, I<nfds> zero, and a "
3758 "non-NULL I<timeout> as a fairly portable way to sleep with subsecond "
3762 #. .PP - it is rumored that:
3763 #. On BSD, when a timeout occurs, the file descriptor bits are not changed.
3764 #. - it is certainly true that:
3765 #. Linux follows SUSv2 and sets the bit masks to zero upon a timeout.
3767 #: build/C/man2/select.2:300
3769 "On Linux, B<select>() modifies I<timeout> to reflect the amount of time not "
3770 "slept; most other implementations do not do this. (POSIX.1-2001 permits "
3771 "either behavior.) This causes problems both when Linux code which reads "
3772 "I<timeout> is ported to other operating systems, and when code is ported to "
3773 "Linux that reuses a I<struct timeval> for multiple B<select>()s in a loop "
3774 "without reinitializing it. Consider I<timeout> to be undefined after "
3775 "B<select>() returns."
3779 #: build/C/man2/select.2:318
3781 "On success, B<select>() and B<pselect>() return the number of file "
3782 "descriptors contained in the three returned descriptor sets (that is, the "
3783 "total number of bits that are set in I<readfds>, I<writefds>, I<exceptfds>) "
3784 "which may be zero if the timeout expires before anything interesting "
3785 "happens. On error, -1 is returned, and I<errno> is set to indicate the "
3786 "error; the file descriptor sets are unmodified, and I<timeout> becomes "
3791 #: build/C/man2/select.2:324
3793 "An invalid file descriptor was given in one of the sets. (Perhaps a file "
3794 "descriptor that was already closed, or one on which an error has occurred.)"
3798 #: build/C/man2/select.2:328
3799 msgid "A signal was caught; see B<signal>(7)."
3803 #: build/C/man2/select.2:334
3804 msgid "I<nfds> is negative or the value contained within I<timeout> is invalid."
3808 #: build/C/man2/select.2:337
3809 msgid "unable to allocate memory for internal tables."
3813 #: build/C/man2/select.2:343
3815 "B<pselect>() was added to Linux in kernel 2.6.16. Prior to this, "
3816 "B<pselect>() was emulated in glibc (but see BUGS)."
3820 #: build/C/man2/select.2:354
3822 "B<select>() conforms to POSIX.1-2001 and 4.4BSD (B<select>() first "
3823 "appeared in 4.2BSD). Generally portable to/from non-BSD systems supporting "
3824 "clones of the BSD socket layer (including System\\ V variants). However, "
3825 "note that the System\\ V variant typically sets the timeout variable before "
3826 "exit, but the BSD variant does not."
3830 #: build/C/man2/select.2:358
3831 msgid "B<pselect>() is defined in POSIX.1g, and in POSIX.1-2001."
3835 #: build/C/man2/select.2:375
3837 "An I<fd_set> is a fixed size buffer. Executing B<FD_CLR>() or B<FD_SET>() "
3838 "with a value of I<fd> that is negative or is equal to or larger than "
3839 "B<FD_SETSIZE> will result in undefined behavior. Moreover, POSIX requires "
3840 "I<fd> to be a valid file descriptor."
3844 #: build/C/man2/select.2:384
3846 "Concerning the types involved, the classical situation is that the two "
3847 "fields of a I<timeval> structure are typed as I<long> (as shown above), and "
3848 "the structure is defined in I<E<lt>sys/time.hE<gt>>. The POSIX.1-2001 "
3853 #: build/C/man2/select.2:391
3856 "struct timeval {\n"
3857 " time_t tv_sec; /* seconds */\n"
3858 " suseconds_t tv_usec; /* microseconds */\n"
3863 #: build/C/man2/select.2:402
3865 "where the structure is defined in I<E<lt>sys/select.hE<gt>> and the data "
3866 "types I<time_t> and I<suseconds_t> are defined in I<E<lt>sys/types.hE<gt>>."
3870 #: build/C/man2/select.2:414
3872 "Concerning prototypes, the classical situation is that one should include "
3873 "I<E<lt>time.hE<gt>> for B<select>(). The POSIX.1-2001 situation is that one "
3874 "should include I<E<lt>sys/select.hE<gt>> for B<select>() and B<pselect>()."
3878 #: build/C/man2/select.2:425
3880 "Under glibc 2.0, I<E<lt>sys/select.hE<gt>> gives the wrong prototype for "
3881 "B<pselect>(). Under glibc 2.1 to 2.2.1, it gives B<pselect>() when "
3882 "B<_GNU_SOURCE> is defined. Since glibc 2.2.2, the requirements are as shown "
3887 #: build/C/man2/select.2:425
3889 msgid "Multithreaded applications"
3893 #: build/C/man2/select.2:442
3895 "If a file descriptor being monitored by B<select>() is closed in another "
3896 "thread, the result is unspecified. On some UNIX systems, B<select>() "
3897 "unblocks and returns, with an indication that the file descriptor is ready "
3898 "(a subsequent I/O operation will likely fail with an error, unless another "
3899 "the file descriptor reopened between the time B<select>() returned and the "
3900 "I/O operations was performed). On Linux (and some other systems), closing "
3901 "the file descriptor in another thread has no effect on B<select>(). In "
3902 "summary, any application that relies on a particular behavior in this "
3903 "scenario must be considered buggy."
3907 #: build/C/man2/select.2:442
3909 msgid "C library/kernel ABI differences"
3913 #: build/C/man2/select.2:450
3915 "The B<pselect>() interface described in this page is implemented by glibc. "
3916 "The underlying Linux system call is named B<pselect6>(). This system call "
3917 "has somewhat different behavior from the glibc wrapper function."
3921 #: build/C/man2/select.2:465
3923 "The Linux B<pselect6>() system call modifies its I<timeout> argument. "
3924 "However, the glibc wrapper function hides this behavior by using a local "
3925 "variable for the timeout argument that is passed to the system call. Thus, "
3926 "the glibc B<pselect>() function does not modify its I<timeout> argument; "
3927 "this is the behavior required by POSIX.1-2001."
3931 #: build/C/man2/select.2:471
3933 "The final argument of the B<pselect6>() system call is not a I<sigset_t\\ "
3934 "*> pointer, but is instead a structure of the form:"
3938 #: build/C/man2/select.2:479
3942 " const sigset_t *ss; /* Pointer to signal set */\n"
3943 " size_t ss_len; /* Size (in bytes) of object pointed\n"
3949 #: build/C/man2/select.2:486
3951 "This allows the system call to obtain both a pointer to the signal set and "
3952 "its size, while allowing for the fact that most architectures support a "
3953 "maximum of 6 arguments to a system call."
3957 #: build/C/man2/select.2:492
3959 "Glibc 2.0 provided a version of B<pselect>() that did not take a I<sigmask> "
3964 #: build/C/man2/select.2:505
3966 "Starting with version 2.1, glibc provided an emulation of B<pselect>() that "
3967 "was implemented using B<sigprocmask>(2) and B<select>(). This "
3968 "implementation remained vulnerable to the very race condition that "
3969 "B<pselect>() was designed to prevent. Modern versions of glibc use the "
3970 "(race-free) B<pselect>() system call on kernels where it is provided."
3974 #: build/C/man2/select.2:518
3976 "On systems that lack B<pselect>(), reliable (and more portable) signal "
3977 "trapping can be achieved using the self-pipe trick. In this technique, a "
3978 "signal handler writes a byte to a pipe whose other end is monitored by "
3979 "B<select>() in the main program. (To avoid possibly blocking when writing "
3980 "to a pipe that may be full or reading from a pipe that may be empty, "
3981 "nonblocking I/O is used when reading from and writing to the pipe.)"
3984 #. Stevens discusses a case where accept can block after select
3985 #. returns successfully because of an intervening RST from the client.
3986 #. Maybe the kernel should have returned EIO in such a situation?
3988 #: build/C/man2/select.2:534
3990 "Under Linux, B<select>() may report a socket file descriptor as \"ready for "
3991 "reading\", while nevertheless a subsequent read blocks. This could for "
3992 "example happen when data has arrived but upon examination has wrong checksum "
3993 "and is discarded. There may be other circumstances in which a file "
3994 "descriptor is spuriously reported as ready. Thus it may be safer to use "
3995 "B<O_NONBLOCK> on sockets that should not block."
3999 #: build/C/man2/select.2:549
4001 "On Linux, B<select>() also modifies I<timeout> if the call is interrupted "
4002 "by a signal handler (i.e., the B<EINTR> error return). This is not "
4003 "permitted by POSIX.1-2001. The Linux B<pselect>() system call has the same "
4004 "behavior, but the glibc wrapper hides this behavior by internally copying "
4005 "the I<timeout> to a local variable and passing that variable to the system "
4010 #: build/C/man2/select.2:556
4013 "#include E<lt>stdio.hE<gt>\n"
4014 "#include E<lt>stdlib.hE<gt>\n"
4015 "#include E<lt>sys/time.hE<gt>\n"
4016 "#include E<lt>sys/types.hE<gt>\n"
4017 "#include E<lt>unistd.hE<gt>\n"
4021 #: build/C/man2/select.2:563
4028 " struct timeval tv;\n"
4033 #: build/C/man2/select.2:567
4036 " /* Watch stdin (fd 0) to see when it has input. */\n"
4037 " FD_ZERO(&rfds);\n"
4038 " FD_SET(0, &rfds);\n"
4042 #: build/C/man2/select.2:571
4045 " /* Wait up to five seconds. */\n"
4047 " tv.tv_usec = 0;\n"
4051 #: build/C/man2/select.2:574
4054 " retval = select(1, &rfds, NULL, NULL, &tv);\n"
4055 " /* Don't rely on the value of tv now! */\n"
4059 #: build/C/man2/select.2:582
4062 " if (retval == -1)\n"
4063 " perror(\"select()\");\n"
4064 " else if (retval)\n"
4065 " printf(\"Data is available now.\\en\");\n"
4066 " /* FD_ISSET(0, &rfds) will be true. */\n"
4068 " printf(\"No data within five seconds.\\en\");\n"
4072 #: build/C/man2/select.2:598
4074 "B<accept>(2), B<connect>(2), B<poll>(2), B<read>(2), B<recv>(2), "
4075 "B<restart_syscall>(2), B<send>(2), B<sigprocmask>(2), B<write>(2), "
4076 "B<epoll>(7), B<time>(7)"
4080 #: build/C/man2/select.2:601
4081 msgid "For a tutorial with discussion and examples, see B<select_tut>(2)."
4085 #: build/C/man2/select_tut.2:32
4091 #: build/C/man2/select_tut.2:32
4097 #: build/C/man2/select_tut.2:52
4100 "B<int select(int >I<nfds>B<, fd_set *>I<readfds>B<, fd_set "
4101 "*>I<writefds>B<,>\n"
4102 "B< fd_set *>I<exceptfds>B<, struct timeval *>I<utimeout>B<);>\n"
4106 #: build/C/man2/select_tut.2:66
4109 "B<int pselect(int >I<nfds>B<, fd_set *>I<readfds>B<, fd_set "
4110 "*>I<writefds>B<,>\n"
4111 "B< fd_set *>I<exceptfds>B<, const struct timespec "
4112 "*>I<ntimeout>B<,>\n"
4113 "B< const sigset_t *>I<sigmask>B<);>\n"
4117 #: build/C/man2/select_tut.2:83
4119 "B<select>() (or B<pselect>()) is used to efficiently monitor multiple file "
4120 "descriptors, to see if any of them is, or becomes, \"ready\"; that is, to "
4121 "see whether I/O becomes possible, or an \"exceptional condition\" has "
4122 "occurred on any of the descriptors."
4126 #: build/C/man2/select_tut.2:108
4128 "Its principal arguments are three \"sets\" of file descriptors: I<readfds>, "
4129 "I<writefds>, and I<exceptfds>. Each set is declared as type I<fd_set>, and "
4130 "its contents can be manipulated with the macros B<FD_CLR>(), B<FD_ISSET>(), "
4131 "B<FD_SET>(), and B<FD_ZERO>(). A newly declared set should first be cleared "
4132 "using B<FD_ZERO>(). B<select>() modifies the contents of the sets "
4133 "according to the rules described below; after calling B<select>() you can "
4134 "test if a file descriptor is still present in a set with the B<FD_ISSET>() "
4135 "macro. B<FD_ISSET>() returns nonzero if a specified file descriptor is "
4136 "present in a set and zero if it is not. B<FD_CLR>() removes a file "
4137 "descriptor from a set."
4141 #: build/C/man2/select_tut.2:108
4147 #: build/C/man2/select_tut.2:109
4153 #: build/C/man2/select_tut.2:118
4155 "This set is watched to see if data is available for reading from any of its "
4156 "file descriptors. After B<select>() has returned, I<readfds> will be "
4157 "cleared of all file descriptors except for those that are immediately "
4158 "available for reading."
4162 #: build/C/man2/select_tut.2:118
4168 #: build/C/man2/select_tut.2:127
4170 "This set is watched to see if there is space to write data to any of its "
4171 "file descriptors. After B<select>() has returned, I<writefds> will be "
4172 "cleared of all file descriptors except for those that are immediately "
4173 "available for writing."
4177 #: build/C/man2/select_tut.2:127
4179 msgid "I<exceptfds>"
4183 #: build/C/man2/select_tut.2:149
4185 "This set is watched for \"exceptional conditions\". In practice, only one "
4186 "such exceptional condition is common: the availability of I<out-of-band> "
4187 "(OOB) data for reading from a TCP socket. See B<recv>(2), B<send>(2), and "
4188 "B<tcp>(7) for more details about OOB data. (One other less common case "
4189 "where B<select>(2) indicates an exceptional condition occurs with "
4190 "pseudoterminals in packet mode; see B<tty_ioctl>(4).) After B<select>() "
4191 "has returned, I<exceptfds> will be cleared of all file descriptors except "
4192 "for those for which an exceptional condition has occurred."
4196 #: build/C/man2/select_tut.2:149
4202 #: build/C/man2/select_tut.2:156
4204 "This is an integer one more than the maximum of any file descriptor in any "
4205 "of the sets. In other words, while adding file descriptors to each of the "
4206 "sets, you must calculate the maximum integer value of all of them, then "
4207 "increment this value by one, and then pass this as I<nfds>."
4211 #: build/C/man2/select_tut.2:156
4217 #: build/C/man2/select_tut.2:169
4219 "This is the longest time B<select>() may wait before returning, even if "
4220 "nothing interesting happened. If this value is passed as NULL, then "
4221 "B<select>() blocks indefinitely waiting for a file descriptor to become "
4222 "ready. I<utimeout> can be set to zero seconds, which causes B<select>() to "
4223 "return immediately, with information about the readiness of file descriptors "
4224 "at the time of the call. The structure I<struct timeval> is defined as:"
4228 #: build/C/man2/select_tut.2:176
4231 "struct timeval {\n"
4232 " time_t tv_sec; /* seconds */\n"
4233 " long tv_usec; /* microseconds */\n"
4238 #: build/C/man2/select_tut.2:178
4244 #: build/C/man2/select_tut.2:187
4246 "This argument for B<pselect>() has the same meaning as I<utimeout>, but "
4247 "I<struct timespec> has nanosecond precision as follows:"
4251 #: build/C/man2/select_tut.2:194
4254 "struct timespec {\n"
4255 " long tv_sec; /* seconds */\n"
4256 " long tv_nsec; /* nanoseconds */\n"
4261 #: build/C/man2/select_tut.2:196
4267 #: build/C/man2/select_tut.2:213
4269 "This argument holds a set of signals that the kernel should unblock (i.e., "
4270 "remove from the signal mask of the calling thread), while the caller is "
4271 "blocked inside the B<pselect>() call (see B<sigaddset>(3) and "
4272 "B<sigprocmask>(2)). It may be NULL, in which case the call does not modify "
4273 "the signal mask on entry and exit to the function. In this case, "
4274 "B<pselect>() will then behave just like B<select>()."
4278 #: build/C/man2/select_tut.2:213
4280 msgid "Combining signal and data events"
4284 #: build/C/man2/select_tut.2:257
4286 "B<pselect>() is useful if you are waiting for a signal as well as for file "
4287 "descriptor(s) to become ready for I/O. Programs that receive signals "
4288 "normally use the signal handler only to raise a global flag. The global "
4289 "flag will indicate that the event must be processed in the main loop of the "
4290 "program. A signal will cause the B<select>() (or B<pselect>()) call to "
4291 "return with I<errno> set to B<EINTR>. This behavior is essential so that "
4292 "signals can be processed in the main loop of the program, otherwise "
4293 "B<select>() would block indefinitely. Now, somewhere in the main loop will "
4294 "be a conditional to check the global flag. So we must ask: what if a signal "
4295 "arrives after the conditional, but before the B<select>() call? The answer "
4296 "is that B<select>() would block indefinitely, even though an event is "
4297 "actually pending. This race condition is solved by the B<pselect>() call. "
4298 "This call can be used to set the signal mask to a set of signals that are "
4299 "only to be received within the B<pselect>() call. For instance, let us say "
4300 "that the event in question was the exit of a child process. Before the "
4301 "start of the main loop, we would block B<SIGCHLD> using B<sigprocmask>(2). "
4302 "Our B<pselect>() call would enable B<SIGCHLD> by using an empty signal "
4303 "mask. Our program would look like:"
4307 #: build/C/man2/select_tut.2:260
4309 msgid "static volatile sig_atomic_t got_SIGCHLD = 0;\n"
4313 #: build/C/man2/select_tut.2:266
4317 "child_sig_handler(int sig)\n"
4319 " got_SIGCHLD = 1;\n"
4324 #: build/C/man2/select_tut.2:274
4328 "main(int argc, char *argv[])\n"
4330 " sigset_t sigmask, empty_mask;\n"
4331 " struct sigaction sa;\n"
4332 " fd_set readfds, writefds, exceptfds;\n"
4337 #: build/C/man2/select_tut.2:281
4340 " sigemptyset(&sigmask);\n"
4341 " sigaddset(&sigmask, SIGCHLD);\n"
4342 " if (sigprocmask(SIG_BLOCK, &sigmask, NULL) == -1) {\n"
4343 " perror(\"sigprocmask\");\n"
4344 " exit(EXIT_FAILURE);\n"
4349 #: build/C/man2/select_tut.2:289
4352 " sa.sa_flags = 0;\n"
4353 " sa.sa_handler = child_sig_handler;\n"
4354 " sigemptyset(&sa.sa_mask);\n"
4355 " if (sigaction(SIGCHLD, &sa, NULL) == -1) {\n"
4356 " perror(\"sigaction\");\n"
4357 " exit(EXIT_FAILURE);\n"
4362 #: build/C/man2/select_tut.2:291
4364 msgid " sigemptyset(&empty_mask);\n"
4368 #: build/C/man2/select_tut.2:295
4371 " for (;;) { /* main loop */\n"
4372 " /* Initialize readfds, writefds, and exceptfds\n"
4373 " before the pselect() call. (Code omitted.) */\n"
4377 #: build/C/man2/select_tut.2:301
4380 " r = pselect(nfds, &readfds, &writefds, &exceptfds,\n"
4381 " NULL, &empty_mask);\n"
4382 " if (r == -1 && errno != EINTR) {\n"
4383 " /* Handle error */\n"
4388 #: build/C/man2/select_tut.2:304
4391 " if (got_SIGCHLD) {\n"
4392 " got_SIGCHLD = 0;\n"
4396 #: build/C/man2/select_tut.2:308
4399 " /* Handle signalled event here; e.g., wait() for all\n"
4400 " terminated children. (Code omitted.) */\n"
4405 #: build/C/man2/select_tut.2:312
4408 " /* main body of program */\n"
4414 #: build/C/man2/select_tut.2:313
4420 #: build/C/man2/select_tut.2:334
4422 "So what is the point of B<select>()? Can't I just read and write to my "
4423 "descriptors whenever I want? The point of B<select>() is that it watches "
4424 "multiple descriptors at the same time and properly puts the process to sleep "
4425 "if there is no activity. UNIX programmers often find themselves in a "
4426 "position where they have to handle I/O from more than one file descriptor "
4427 "where the data flow may be intermittent. If you were to merely create a "
4428 "sequence of B<read>(2) and B<write>(2) calls, you would find that one of "
4429 "your calls may block waiting for data from/to a file descriptor, while "
4430 "another file descriptor is unused though ready for I/O. B<select>() "
4431 "efficiently copes with this situation."
4435 #: build/C/man2/select_tut.2:334
4441 #: build/C/man2/select_tut.2:347
4443 "Many people who try to use B<select>() come across behavior that is "
4444 "difficult to understand and produces nonportable or borderline results. For "
4445 "instance, the above program is carefully written not to block at any point, "
4446 "even though it does not set its file descriptors to nonblocking mode. It is "
4447 "easy to introduce subtle errors that will remove the advantage of using "
4448 "B<select>(), so here is a list of essentials to watch for when using "
4453 #: build/C/man2/select_tut.2:356
4455 "You should always try to use B<select>() without a timeout. Your program "
4456 "should have nothing to do if there is no data available. Code that depends "
4457 "on timeouts is not usually portable and is difficult to debug."
4461 #: build/C/man2/select_tut.2:360
4463 "The value I<nfds> must be properly calculated for efficiency as explained "
4468 #: build/C/man2/select_tut.2:367
4470 "No file descriptor must be added to any set if you do not intend to check "
4471 "its result after the B<select>() call, and respond appropriately. See next "
4476 #: build/C/man2/select_tut.2:373
4478 "After B<select>() returns, all file descriptors in all sets should be "
4479 "checked to see if they are ready."
4483 #: build/C/man2/select_tut.2:373
4489 #: build/C/man2/select_tut.2:388
4491 "The functions B<read>(2), B<recv>(2), B<write>(2), and B<send>(2) do I<not> "
4492 "necessarily read/write the full amount of data that you have requested. If "
4493 "they do read/write the full amount, it's because you have a low traffic load "
4494 "and a fast stream. This is not always going to be the case. You should "
4495 "cope with the case of your functions managing to send or receive only a "
4500 #: build/C/man2/select_tut.2:388
4506 #: build/C/man2/select_tut.2:396
4508 "Never read/write only in single bytes at a time unless you are really sure "
4509 "that you have a small amount of data to process. It is extremely "
4510 "inefficient not to read/write as much data as you can buffer each time. The "
4511 "buffers in the example below are 1024 bytes although they could easily be "
4516 #: build/C/man2/select_tut.2:396
4521 #. Nonetheless, you should still cope with these errors for completeness.
4523 #: build/C/man2/select_tut.2:418
4525 "The functions B<read>(2), B<recv>(2), B<write>(2), and B<send>(2) as well "
4526 "as the B<select>() call can return -1 with I<errno> set to B<EINTR>, or "
4527 "with I<errno> set to B<EAGAIN> (B<EWOULDBLOCK>). These results must be "
4528 "properly managed (not done properly above). If your program is not going to "
4529 "receive any signals, then it is unlikely you will get B<EINTR>. If your "
4530 "program does not set nonblocking I/O, you will not get B<EAGAIN>."
4534 #: build/C/man2/select_tut.2:418
4540 #: build/C/man2/select_tut.2:427
4542 "Never call B<read>(2), B<recv>(2), B<write>(2), or B<send>(2) with a buffer "
4547 #: build/C/man2/select_tut.2:427
4553 #: build/C/man2/select_tut.2:443
4555 "If the functions B<read>(2), B<recv>(2), B<write>(2), and B<send>(2) fail "
4556 "with errors other than those listed in B<7.>, or one of the input functions "
4557 "returns 0, indicating end of file, then you should I<not> pass that "
4558 "descriptor to B<select>() again. In the example below, I close the "
4559 "descriptor immediately, and then set it to -1 to prevent it being included "
4564 #: build/C/man2/select_tut.2:443
4570 #: build/C/man2/select_tut.2:450
4572 "The timeout value must be initialized with each new call to B<select>(), "
4573 "since some operating systems modify the structure. B<pselect>() however "
4574 "does not modify its timeout structure."
4578 #: build/C/man2/select_tut.2:450
4583 #. "I have heard" does not fill me with confidence, and doesn't
4584 #. belong in a man page, so I've commented this point out.
4587 #. I have heard that the Windows socket layer does not cope with OOB data
4589 #. It also does not cope with
4591 #. calls when no file descriptors are set at all.
4592 #. Having no file descriptors set is a useful
4593 #. way to sleep the process with subsecond precision by using the timeout.
4594 #. (See further on.)
4596 #: build/C/man2/select_tut.2:469
4598 "Since B<select>() modifies its file descriptor sets, if the call is being "
4599 "used in a loop, then the sets must be reinitialized before each call."
4603 #: build/C/man2/select_tut.2:469
4605 msgid "Usleep emulation"
4609 #: build/C/man2/select_tut.2:476
4611 "On systems that do not have a B<usleep>(3) function, you can call "
4612 "B<select>() with a finite timeout and no file descriptors as follows:"
4616 #: build/C/man2/select_tut.2:482
4619 " struct timeval tv;\n"
4621 " tv.tv_usec = 200000; /* 0.2 seconds */\n"
4622 " select(0, NULL, NULL, NULL, &tv);\n"
4626 #: build/C/man2/select_tut.2:485
4627 msgid "This is guaranteed to work only on UNIX systems, however."
4631 #: build/C/man2/select_tut.2:490
4633 "On success, B<select>() returns the total number of file descriptors still "
4634 "present in the file descriptor sets."
4638 #: build/C/man2/select_tut.2:496
4640 "If B<select>() timed out, then the return value will be zero. The file "
4641 "descriptors set should be all empty (but may not be on some systems)."
4645 #: build/C/man2/select_tut.2:503
4647 "A return value of -1 indicates an error, with I<errno> being set "
4648 "appropriately. In the case of an error, the contents of the returned sets "
4649 "and the I<struct timeout> contents are undefined and should not be used. "
4650 "B<pselect>() however never modifies I<ntimeout>."
4654 #: build/C/man2/select_tut.2:512
4656 "Generally speaking, all operating systems that support sockets also support "
4657 "B<select>(). B<select>() can be used to solve many problems in a portable "
4658 "and efficient way that naive programmers try to solve in a more complicated "
4659 "manner using threads, forking, IPCs, signals, memory sharing, and so on."
4663 #: build/C/man2/select_tut.2:521
4665 "The B<poll>(2) system call has the same functionality as B<select>(), and "
4666 "is somewhat more efficient when monitoring sparse file descriptor sets. It "
4667 "is nowadays widely available, but historically was less portable than "
4672 #: build/C/man2/select_tut.2:529
4674 "The Linux-specific B<epoll>(7) API provides an interface that is more "
4675 "efficient than B<select>(2) and B<poll>(2) when monitoring large numbers "
4676 "of file descriptors."
4680 #: build/C/man2/select_tut.2:534
4682 "Here is an example that better demonstrates the true utility of "
4683 "B<select>(). The listing below is a TCP forwarding program that forwards "
4684 "from one TCP port to another."
4688 #: build/C/man2/select_tut.2:547
4691 "#include E<lt>stdlib.hE<gt>\n"
4692 "#include E<lt>stdio.hE<gt>\n"
4693 "#include E<lt>unistd.hE<gt>\n"
4694 "#include E<lt>sys/time.hE<gt>\n"
4695 "#include E<lt>sys/types.hE<gt>\n"
4696 "#include E<lt>string.hE<gt>\n"
4697 "#include E<lt>signal.hE<gt>\n"
4698 "#include E<lt>sys/socket.hE<gt>\n"
4699 "#include E<lt>netinet/in.hE<gt>\n"
4700 "#include E<lt>arpa/inet.hE<gt>\n"
4701 "#include E<lt>errno.hE<gt>\n"
4705 #: build/C/man2/select_tut.2:549
4707 msgid "static int forward_port;\n"
4711 #: build/C/man2/select_tut.2:552
4715 "#define max(x,y) ((x) E<gt> (y) ? (x) : (y))\n"
4719 #: build/C/man2/select_tut.2:559
4723 "listen_socket(int listen_port)\n"
4725 " struct sockaddr_in a;\n"
4731 #: build/C/man2/select_tut.2:584
4734 " s = socket(AF_INET, SOCK_STREAM, 0);\n"
4736 " perror(\"socket\");\n"
4740 " if (setsockopt(s, SOL_SOCKET, SO_REUSEADDR,\n"
4741 " &yes, sizeof(yes)) == -1) {\n"
4742 " perror(\"setsockopt\");\n"
4746 " memset(&a, 0, sizeof(a));\n"
4747 " a.sin_port = htons(listen_port);\n"
4748 " a.sin_family = AF_INET;\n"
4749 " if (bind(s, (struct sockaddr *) &a, sizeof(a)) == -1) {\n"
4750 " perror(\"bind\");\n"
4754 " printf(\"accepting connections on port %d\\en\", listen_port);\n"
4761 #: build/C/man2/select_tut.2:590
4765 "connect_socket(int connect_port, char *address)\n"
4767 " struct sockaddr_in a;\n"
4772 #: build/C/man2/select_tut.2:597
4775 " s = socket(AF_INET, SOCK_STREAM, 0);\n"
4777 " perror(\"socket\");\n"
4784 #: build/C/man2/select_tut.2:601
4787 " memset(&a, 0, sizeof(a));\n"
4788 " a.sin_port = htons(connect_port);\n"
4789 " a.sin_family = AF_INET;\n"
4793 #: build/C/man2/select_tut.2:607
4796 " if (!inet_aton(address, (struct in_addr *) &a.sin_addr.s_addr)) {\n"
4797 " perror(\"bad IP address format\");\n"
4804 #: build/C/man2/select_tut.2:616
4807 " if (connect(s, (struct sockaddr *) &a, sizeof(a)) == -1) {\n"
4808 " perror(\"connect()\");\n"
4809 " shutdown(s, SHUT_RDWR);\n"
4818 #: build/C/man2/select_tut.2:624
4821 "#define SHUT_FD1 do { \\e\n"
4822 " if (fd1 E<gt>= 0) { \\e\n"
4823 " shutdown(fd1, SHUT_RDWR); \\e\n"
4824 " close(fd1); \\e\n"
4831 #: build/C/man2/select_tut.2:632
4834 "#define SHUT_FD2 do { \\e\n"
4835 " if (fd2 E<gt>= 0) { \\e\n"
4836 " shutdown(fd2, SHUT_RDWR); \\e\n"
4837 " close(fd2); \\e\n"
4844 #: build/C/man2/select_tut.2:634
4846 msgid "#define BUF_SIZE 1024\n"
4850 #: build/C/man2/select_tut.2:643
4854 "main(int argc, char *argv[])\n"
4857 " int fd1 = -1, fd2 = -1;\n"
4858 " char buf1[BUF_SIZE], buf2[BUF_SIZE];\n"
4859 " int buf1_avail, buf1_written;\n"
4860 " int buf2_avail, buf2_written;\n"
4864 #: build/C/man2/select_tut.2:649
4867 " if (argc != 4) {\n"
4868 " fprintf(stderr, \"Usage\\en\\etfwd E<lt>listen-portE<gt> \"\n"
4869 " \"E<lt>forward-to-portE<gt> "
4870 "E<lt>forward-to-ip-addressE<gt>\\en\");\n"
4871 " exit(EXIT_FAILURE);\n"
4876 #: build/C/man2/select_tut.2:651
4878 msgid " signal(SIGPIPE, SIG_IGN);\n"
4882 #: build/C/man2/select_tut.2:653
4884 msgid " forward_port = atoi(argv[2]);\n"
4888 #: build/C/man2/select_tut.2:657
4891 " h = listen_socket(atoi(argv[1]));\n"
4893 " exit(EXIT_FAILURE);\n"
4897 #: build/C/man2/select_tut.2:661
4901 " int r, nfds = 0;\n"
4902 " fd_set rd, wr, er;\n"
4906 #: build/C/man2/select_tut.2:691
4912 " FD_SET(h, &rd);\n"
4913 " nfds = max(nfds, h);\n"
4914 " if (fd1 E<gt> 0 && buf1_avail E<lt> BUF_SIZE) {\n"
4915 " FD_SET(fd1, &rd);\n"
4916 " nfds = max(nfds, fd1);\n"
4918 " if (fd2 E<gt> 0 && buf2_avail E<lt> BUF_SIZE) {\n"
4919 " FD_SET(fd2, &rd);\n"
4920 " nfds = max(nfds, fd2);\n"
4922 " if (fd1 E<gt> 0 && buf2_avail - buf2_written E<gt> 0) {\n"
4923 " FD_SET(fd1, &wr);\n"
4924 " nfds = max(nfds, fd1);\n"
4926 " if (fd2 E<gt> 0 && buf1_avail - buf1_written E<gt> 0) {\n"
4927 " FD_SET(fd2, &wr);\n"
4928 " nfds = max(nfds, fd2);\n"
4930 " if (fd1 E<gt> 0) {\n"
4931 " FD_SET(fd1, &er);\n"
4932 " nfds = max(nfds, fd1);\n"
4934 " if (fd2 E<gt> 0) {\n"
4935 " FD_SET(fd2, &er);\n"
4936 " nfds = max(nfds, fd2);\n"
4941 #: build/C/man2/select_tut.2:693
4943 msgid " r = select(nfds + 1, &rd, &wr, &er, NULL);\n"
4947 #: build/C/man2/select_tut.2:696
4950 " if (r == -1 && errno == EINTR)\n"
4955 #: build/C/man2/select_tut.2:701
4959 " perror(\"select()\");\n"
4960 " exit(EXIT_FAILURE);\n"
4965 #: build/C/man2/select_tut.2:705
4968 " if (FD_ISSET(h, &rd)) {\n"
4969 " unsigned int l;\n"
4970 " struct sockaddr_in client_address;\n"
4974 #: build/C/man2/select_tut.2:724
4977 " memset(&client_address, 0, l = sizeof(client_address));\n"
4978 " r = accept(h, (struct sockaddr *) &client_address, &l);\n"
4980 " perror(\"accept()\");\n"
4984 " buf1_avail = buf1_written = 0;\n"
4985 " buf2_avail = buf2_written = 0;\n"
4987 " fd2 = connect_socket(forward_port, argv[3]);\n"
4991 " printf(\"connect from %s\\en\",\n"
4992 " inet_ntoa(client_address.sin_addr));\n"
4998 #: build/C/man2/select_tut.2:726
5000 msgid " /* NB: read oob data before normal reads */\n"
5004 #: build/C/man2/select_tut.2:730
5007 " if (fd1 E<gt> 0)\n"
5008 " if (FD_ISSET(fd1, &er)) {\n"
5013 #: build/C/man2/select_tut.2:740
5016 " r = recv(fd1, &c, 1, MSG_OOB);\n"
5020 " send(fd2, &c, 1, MSG_OOB);\n"
5022 " if (fd2 E<gt> 0)\n"
5023 " if (FD_ISSET(fd2, &er)) {\n"
5028 #: build/C/man2/select_tut.2:783
5031 " r = recv(fd2, &c, 1, MSG_OOB);\n"
5035 " send(fd1, &c, 1, MSG_OOB);\n"
5037 " if (fd1 E<gt> 0)\n"
5038 " if (FD_ISSET(fd1, &rd)) {\n"
5039 " r = read(fd1, buf1 + buf1_avail,\n"
5040 " BUF_SIZE - buf1_avail);\n"
5044 " buf1_avail += r;\n"
5046 " if (fd2 E<gt> 0)\n"
5047 " if (FD_ISSET(fd2, &rd)) {\n"
5048 " r = read(fd2, buf2 + buf2_avail,\n"
5049 " BUF_SIZE - buf2_avail);\n"
5053 " buf2_avail += r;\n"
5055 " if (fd1 E<gt> 0)\n"
5056 " if (FD_ISSET(fd1, &wr)) {\n"
5057 " r = write(fd1, buf2 + buf2_written,\n"
5058 " buf2_avail - buf2_written);\n"
5062 " buf2_written += r;\n"
5064 " if (fd2 E<gt> 0)\n"
5065 " if (FD_ISSET(fd2, &wr)) {\n"
5066 " r = write(fd2, buf1 + buf1_written,\n"
5067 " buf1_avail - buf1_written);\n"
5071 " buf1_written += r;\n"
5076 #: build/C/man2/select_tut.2:785
5078 msgid " /* check if write data has caught read data */\n"
5082 #: build/C/man2/select_tut.2:790
5085 " if (buf1_written == buf1_avail)\n"
5086 " buf1_written = buf1_avail = 0;\n"
5087 " if (buf2_written == buf2_avail)\n"
5088 " buf2_written = buf2_avail = 0;\n"
5092 #: build/C/man2/select_tut.2:793
5095 " /* one side has closed the connection, keep\n"
5096 " writing to the other side until empty */\n"
5100 #: build/C/man2/select_tut.2:801
5103 " if (fd1 E<lt> 0 && buf1_avail - buf1_written == 0)\n"
5105 " if (fd2 E<lt> 0 && buf2_avail - buf2_written == 0)\n"
5108 " exit(EXIT_SUCCESS);\n"
5113 #: build/C/man2/select_tut.2:815
5115 "The above program properly forwards most kinds of TCP connections including "
5116 "OOB signal data transmitted by B<telnet> servers. It handles the tricky "
5117 "problem of having data flow in both directions simultaneously. You might "
5118 "think it more efficient to use a B<fork>(2) call and devote a thread to "
5119 "each stream. This becomes more tricky than you might suspect. Another idea "
5120 "is to set nonblocking I/O using B<fcntl>(2). This also has its problems "
5121 "because you end up using inefficient timeouts."
5125 #: build/C/man2/select_tut.2:821
5127 "The program does not handle more than one simultaneous connection at a time, "
5128 "although it could easily be extended to do this with a linked list of "
5129 "buffers\\(emone for each connection. At the moment, new connections cause "
5130 "the current connection to be dropped."
5134 #. This man page was written by Paul Sheer.
5136 #: build/C/man2/select_tut.2:840
5138 "B<accept>(2), B<connect>(2), B<ioctl>(2), B<poll>(2), B<read>(2), "
5139 "B<recv>(2), B<select>(2), B<send>(2), B<sigprocmask>(2), B<write>(2), "
5140 "B<sigaddset>(3), B<sigdelset>(3), B<sigemptyset>(3), B<sigfillset>(3), "
5141 "B<sigismember>(3), B<epoll>(7)"
5145 #: build/C/man2/send.2:40
5151 #: build/C/man2/send.2:43
5152 msgid "send, sendto, sendmsg - send a message on a socket"
5156 #: build/C/man2/send.2:47
5159 "B<#include E<lt>sys/types.hE<gt>>\n"
5160 "B<#include E<lt>sys/socket.hE<gt>>\n"
5164 #: build/C/man2/send.2:50
5167 "B<ssize_t send(int >I<sockfd>B<, const void *>I<buf>B<, size_t >I<len>B<, "
5168 "int >I<flags>B<);>\n"
5172 #: build/C/man2/send.2:54
5175 "B<ssize_t sendto(int >I<sockfd>B<, const void *>I<buf>B<, size_t >I<len>B<, "
5176 "int >I<flags>B<,>\n"
5177 "B< const struct sockaddr *>I<dest_addr>B<, socklen_t "
5178 ">I<addrlen>B<);>\n"
5182 #: build/C/man2/send.2:57
5185 "B<ssize_t sendmsg(int >I<sockfd>B<, const struct msghdr *>I<msg>B<, int "
5190 #: build/C/man2/send.2:65
5192 "The system calls B<send>(), B<sendto>(), and B<sendmsg>() are used to "
5193 "transmit a message to another socket."
5197 #: build/C/man2/send.2:84
5199 "The B<send>() call may be used only when the socket is in a I<connected> "
5200 "state (so that the intended recipient is known). The only difference "
5201 "between B<send>() and B<write>(2) is the presence of I<flags>. With a "
5202 "zero I<flags> argument, B<send>() is equivalent to B<write>(2). Also, the "
5207 #: build/C/man2/send.2:86
5209 msgid " send(sockfd, buf, len, flags);\n"
5213 #: build/C/man2/send.2:88
5214 msgid "is equivalent to"
5218 #: build/C/man2/send.2:90
5220 msgid " sendto(sockfd, buf, len, flags, NULL, 0);\n"
5224 #: build/C/man2/send.2:94
5225 msgid "The argument I<sockfd> is the file descriptor of the sending socket."
5229 #: build/C/man2/send.2:122
5231 "If B<sendto>() is used on a connection-mode (B<SOCK_STREAM>, "
5232 "B<SOCK_SEQPACKET>) socket, the arguments I<dest_addr> and I<addrlen> are "
5233 "ignored (and the error B<EISCONN> may be returned when they are not NULL and "
5234 "0), and the error B<ENOTCONN> is returned when the socket was not actually "
5235 "connected. Otherwise, the address of the target is given by I<dest_addr> "
5236 "with I<addrlen> specifying its size. For B<sendmsg>(), the address of the "
5237 "target is given by I<msg.msg_name>, with I<msg.msg_namelen> specifying its "
5242 #: build/C/man2/send.2:138
5244 "For B<send>() and B<sendto>(), the message is found in I<buf> and has "
5245 "length I<len>. For B<sendmsg>(), the message is pointed to by the elements "
5246 "of the array I<msg.msg_iov>. The B<sendmsg>() call also allows sending "
5247 "ancillary data (also known as control information)."
5251 #: build/C/man2/send.2:143
5253 "If the message is too long to pass atomically through the underlying "
5254 "protocol, the error B<EMSGSIZE> is returned, and the message is not "
5259 #: build/C/man2/send.2:147
5261 "No indication of failure to deliver is implicit in a B<send>(). Locally "
5262 "detected errors are indicated by a return value of -1."
5266 #: build/C/man2/send.2:160
5268 "When the message does not fit into the send buffer of the socket, B<send>() "
5269 "normally blocks, unless the socket has been placed in nonblocking I/O mode. "
5270 "In nonblocking mode it would fail with the error B<EAGAIN> or B<EWOULDBLOCK> "
5271 "in this case. The B<select>(2) call may be used to determine when it is "
5272 "possible to send more data."
5275 #. FIXME . ? document MSG_PROXY (which went away in 2.3.15)
5277 #: build/C/man2/send.2:166
5279 "The I<flags> argument is the bitwise OR of zero or more of the following "
5284 #: build/C/man2/send.2:166
5286 msgid "B<MSG_CONFIRM> (since Linux 2.3.15)"
5290 #: build/C/man2/send.2:180
5292 "Tell the link layer that forward progress happened: you got a successful "
5293 "reply from the other side. If the link layer doesn't get this it will "
5294 "regularly reprobe the neighbor (e.g., via a unicast ARP). Only valid on "
5295 "B<SOCK_DGRAM> and B<SOCK_RAW> sockets and currently implemented only for "
5296 "IPv4 and IPv6. See B<arp>(7) for details."
5300 #: build/C/man2/send.2:180
5302 msgid "B<MSG_DONTROUTE>"
5306 #: build/C/man2/send.2:188
5308 "Don't use a gateway to send out the packet, send to hosts only on directly "
5309 "connected networks. This is usually used only by diagnostic or routing "
5310 "programs. This is defined only for protocol families that route; packet "
5315 #: build/C/man2/send.2:199
5317 "Enables nonblocking operation; if the operation would block, B<EAGAIN> or "
5318 "B<EWOULDBLOCK> is returned (this can also be enabled using the B<O_NONBLOCK> "
5319 "flag with the B<F_SETFL> B<fcntl>(2))."
5323 #: build/C/man2/send.2:199
5325 msgid "B<MSG_EOR> (since Linux 2.2)"
5329 #: build/C/man2/send.2:203
5331 "Terminates a record (when this notion is supported, as for sockets of type "
5332 "B<SOCK_SEQPACKET>)."
5336 #: build/C/man2/send.2:203
5338 msgid "B<MSG_MORE> (since Linux 2.4.4)"
5342 #: build/C/man2/send.2:212
5344 "The caller has more data to send. This flag is used with TCP sockets to "
5345 "obtain the same effect as the B<TCP_CORK> socket option (see B<tcp>(7)), "
5346 "with the difference that this flag can be set on a per-call basis."
5350 #: build/C/man2/send.2:221
5352 "Since Linux 2.6, this flag is also supported for UDP sockets, and informs "
5353 "the kernel to package all of the data sent in calls with this flag set into "
5354 "a single datagram which is transmitted only when a call is performed that "
5355 "does not specify this flag. (See also the B<UDP_CORK> socket option "
5356 "described in B<udp>(7).)"
5360 #: build/C/man2/send.2:221
5362 msgid "B<MSG_NOSIGNAL> (since Linux 2.2)"
5366 #: build/C/man2/send.2:230
5368 "Requests not to send B<SIGPIPE> on errors on stream oriented sockets when "
5369 "the other end breaks the connection. The B<EPIPE> error is still returned."
5373 #: build/C/man2/send.2:239
5375 "Sends I<out-of-band> data on sockets that support this notion (e.g., of type "
5376 "B<SOCK_STREAM>); the underlying protocol must also support I<out-of-band> "
5381 #: build/C/man2/send.2:239
5387 #: build/C/man2/send.2:245
5389 "The definition of the I<msghdr> structure employed by B<sendmsg>() is as "
5394 #: build/C/man2/send.2:257
5398 " void *msg_name; /* optional address */\n"
5399 " socklen_t msg_namelen; /* size of address */\n"
5400 " struct iovec *msg_iov; /* scatter/gather array */\n"
5401 " size_t msg_iovlen; /* # elements in msg_iov */\n"
5402 " void *msg_control; /* ancillary data, see below */\n"
5403 " size_t msg_controllen; /* ancillary data buffer len */\n"
5404 " int msg_flags; /* flags (unused) */\n"
5409 #: build/C/man2/send.2:269
5411 "The I<msg_name> field is used on an unconnected socket to specify the target "
5412 "address for a datagram. It points to a buffer containing the address; the "
5413 "I<msg_namelen> field should be set to the size of the address. For a "
5414 "connected socket, these fields should be specified as NULL and 0, "
5419 #: build/C/man2/send.2:276
5421 "The I<msg_iov> and I<msg_iovlen> fields specify scatter-gather locations, as "
5426 #: build/C/man2/send.2:287
5428 "You may send control information using the I<msg_control> and "
5429 "I<msg_controllen> members. The maximum control buffer length the kernel can "
5430 "process is limited per socket by the value in "
5431 "I</proc/sys/net/core/optmem_max>; see B<socket>(7)."
5434 #. Still to be documented:
5435 #. Send file descriptors and user credentials using the
5436 #. msg_control* fields.
5438 #: build/C/man2/send.2:294
5439 msgid "The I<msg_flags> field is ignored."
5443 #: build/C/man2/send.2:299
5445 "On success, these calls return the number of bytes sent. On error, -1 is "
5446 "returned, and I<errno> is set appropriately."
5450 #: build/C/man2/send.2:304
5452 "These are some standard errors generated by the socket layer. Additional "
5453 "errors may be generated and returned from the underlying protocol modules; "
5454 "see their respective manual pages."
5458 #: build/C/man2/send.2:312
5460 "(For UNIX domain sockets, which are identified by pathname) Write "
5461 "permission is denied on the destination socket file, or search permission is "
5462 "denied for one of the directories the path prefix. (See "
5463 "B<path_resolution>(7).)"
5467 #: build/C/man2/send.2:315
5469 "(For UDP sockets) An attempt was made to send to a network/broadcast address "
5470 "as though it was a unicast address."
5473 #. Actually EAGAIN on Linux
5475 #: build/C/man2/send.2:323
5477 "The socket is marked nonblocking and the requested operation would block. "
5478 "POSIX.1-2001 allows either error to be returned for this case, and does not "
5479 "require these constants to have the same value, so a portable application "
5480 "should check for both possibilities."
5484 #: build/C/man2/send.2:336
5486 "(Internet domain datagram sockets) The socket referred to by I<sockfd> had "
5487 "not previously been bound to an address and, upon attempting to bind it to "
5488 "an ephemeral port, it was determined that all port numbers in the ephemeral "
5489 "port range are currently in use. See the discussion of "
5490 "I</proc/sys/net/ipv4/ip_local_port_range> in B<ip>(7)."
5494 #: build/C/man2/send.2:339
5495 msgid "An invalid descriptor was specified."
5499 #: build/C/man2/send.2:339
5501 msgid "B<ECONNRESET>"
5505 #: build/C/man2/send.2:342
5506 msgid "Connection reset by peer."
5510 #: build/C/man2/send.2:342
5512 msgid "B<EDESTADDRREQ>"
5516 #: build/C/man2/send.2:345
5517 msgid "The socket is not connection-mode, and no peer address is set."
5521 #: build/C/man2/send.2:348
5522 msgid "An invalid user space address was specified for an argument."
5526 #: build/C/man2/send.2:352
5527 msgid "A signal occurred before any data was transmitted; see B<signal>(7)."
5531 #: build/C/man2/send.2:361
5533 "The connection-mode socket was connected already but a recipient was "
5534 "specified. (Now either this error is returned, or the recipient "
5535 "specification is ignored.)"
5539 #: build/C/man2/send.2:361
5544 #. (e.g., SOCK_DGRAM )
5546 #: build/C/man2/send.2:367
5548 "The socket type requires that message be sent atomically, and the size of "
5549 "the message to be sent made this impossible."
5553 #: build/C/man2/send.2:375
5555 "The output queue for a network interface was full. This generally indicates "
5556 "that the interface has stopped sending, but may be caused by transient "
5557 "congestion. (Normally, this does not occur in Linux. Packets are just "
5558 "silently dropped when a device queue overflows.)"
5562 #: build/C/man2/send.2:378
5563 msgid "No memory available."
5567 #: build/C/man2/send.2:381
5568 msgid "The socket is not connected, and no target has been given."
5572 #: build/C/man2/send.2:391
5573 msgid "Some bit in the I<flags> argument is inappropriate for the socket type."
5577 #: build/C/man2/send.2:391
5583 #: build/C/man2/send.2:400
5585 "The local end has been shut down on a connection oriented socket. In this "
5586 "case, the process will also receive a B<SIGPIPE> unless B<MSG_NOSIGNAL> is "
5591 #: build/C/man2/send.2:403
5592 msgid "4.4BSD, SVr4, POSIX.1-2001. These function calls appeared in 4.2BSD."
5596 #: build/C/man2/send.2:414
5598 "POSIX.1-2001 describes only the B<MSG_OOB> and B<MSG_EOR> flags. "
5599 "POSIX.1-2008 adds a specification of B<MSG_NOSIGNAL>. The B<MSG_CONFIRM> "
5600 "flag is a Linux extension."
5604 #: build/C/man2/send.2:433
5606 "See B<sendmmsg>(2) for information about a Linux-specific system call that "
5607 "can be used to transmit multiple datagrams in a single call."
5611 #: build/C/man2/send.2:438
5612 msgid "Linux may return B<EPIPE> instead of B<ENOTCONN>."
5616 #: build/C/man2/send.2:443
5617 msgid "An example of the use of B<sendto>() is shown in B<getaddrinfo>(3)."
5621 #: build/C/man2/send.2:458
5623 "B<fcntl>(2), B<getsockopt>(2), B<recv>(2), B<select>(2), B<sendfile>(2), "
5624 "B<sendmmsg>(2), B<shutdown>(2), B<socket>(2), B<write>(2), B<cmsg>(3), "
5625 "B<ip>(7), B<socket>(7), B<tcp>(7), B<udp>(7)"
5629 #: build/C/man2/sendmmsg.2:28
5635 #: build/C/man2/sendmmsg.2:28 build/C/man7/socket.7:58
5641 #: build/C/man2/sendmmsg.2:31
5642 msgid "sendmmsg - send multiple messages on a socket"
5646 #: build/C/man2/sendmmsg.2:39
5649 "B<int sendmmsg(int >I<sockfd>B<, struct mmsghdr *>I<msgvec>B<, unsigned int "
5651 "B< unsigned int >I<flags>B<);>\n"
5654 #. See commit 228e548e602061b08ee8e8966f567c12aa079682
5656 #: build/C/man2/sendmmsg.2:49
5658 "The B<sendmmsg>() system call is an extension of B<sendmsg>(2) that allows "
5659 "the caller to transmit multiple messages on a socket using a single system "
5660 "call. (This has performance benefits for some applications.)"
5664 #: build/C/man2/sendmmsg.2:54
5666 "The I<sockfd> argument is the file descriptor of the socket on which data is "
5667 "to be transmitted."
5671 #: build/C/man2/sendmmsg.2:75
5674 "struct mmsghdr {\n"
5675 " struct msghdr msg_hdr; /* Message header */\n"
5676 " unsigned int msg_len; /* Number of bytes transmitted */\n"
5681 #: build/C/man2/sendmmsg.2:91
5683 "The I<msg_hdr> field is a I<msghdr> structure, as described in "
5684 "B<sendmsg>(2). The I<msg_len> field is used to return the number of bytes "
5685 "sent from the message in I<msg_hdr> (i.e., the same as the return value from "
5686 "a single B<sendmsg>(2) call)."
5690 #: build/C/man2/sendmmsg.2:97
5692 "The I<flags> argument contains flags ORed together. The flags are the same "
5693 "as for B<sendmsg>(2)."
5697 #: build/C/man2/sendmmsg.2:107
5699 "A blocking B<sendmmsg>() call blocks until I<vlen> messages have been "
5700 "sent. A nonblocking call sends as many messages as possible (up to the "
5701 "limit specified by I<vlen>) and returns immediately."
5705 #: build/C/man2/sendmmsg.2:119
5707 "On return from B<sendmmsg>(), the I<msg_len> fields of successive elements "
5708 "of I<msgvec> are updated to contain the number of bytes transmitted from the "
5709 "corresponding I<msg_hdr>. The return value of the call indicates the number "
5710 "of elements of I<msgvec> that have been updated."
5714 #: build/C/man2/sendmmsg.2:129
5716 "On success, B<sendmmsg>() returns the number of messages sent from "
5717 "I<msgvec>; if this is less than I<vlen>, the caller can retry with a further "
5718 "B<sendmmsg>() call to send the remaining messages."
5722 #: build/C/man2/sendmmsg.2:133
5723 msgid "On error, -1 is returned, and I<errno> is set to indicate the error."
5726 #. commit 728ffb86f10873aaf4abd26dde691ee40ae731fe
5727 #. ... only return an error if no datagrams could be sent.
5728 #. If less than the requested number of messages were sent, the application
5729 #. must retry starting at the first failed one and if the problem is
5730 #. persistent the error will be returned.
5732 #. This matches the behavior of other syscalls like read/write - it
5733 #. is not an error if less than the requested number of elements are sent.
5735 #: build/C/man2/sendmmsg.2:145
5737 "Errors are as for B<sendmsg>(2). An error is returned only if no datagrams "
5742 #: build/C/man2/sendmmsg.2:150
5744 "The B<sendmmsg>() system call was added in Linux 3.0. Support in glibc was "
5745 "added in version 2.14."
5749 #: build/C/man2/sendmmsg.2:153
5750 msgid "B<sendmmsg>() is Linux-specific."
5753 #. commit 98382f419f32d2c12d021943b87dea555677144b
5754 #. net: Cap number of elements for sendmmsg
5756 #. To limit the amount of time we can spend in sendmmsg, cap the
5757 #. number of elements to UIO_MAXIOV (currently 1024).
5759 #. For error handling an application using sendmmsg needs to retry at
5760 #. the first unsent message, so capping is simpler and requires less
5761 #. application logic than returning EINVAL.
5763 #: build/C/man2/sendmmsg.2:168
5764 msgid "The value specified in I<vlen> is capped to B<UIO_MAXIOV> (1024)."
5768 #: build/C/man2/sendmmsg.2:177
5770 "The example below uses B<sendmmsg>() to send I<onetwo> and I<three> in two "
5771 "distinct UDP datagrams using one system call. The contents of the first "
5772 "datagram originates from a pair of buffers."
5776 #: build/C/man2/sendmmsg.2:186
5779 "#define _GNU_SOURCE\n"
5780 "#include E<lt>netinet/ip.hE<gt>\n"
5781 "#include E<lt>stdio.hE<gt>\n"
5782 "#include E<lt>stdlib.hE<gt>\n"
5783 "#include E<lt>string.hE<gt>\n"
5784 "#include E<lt>sys/types.hE<gt>\n"
5785 "#include E<lt>sys/socket.hE<gt>\n"
5789 #: build/C/man2/sendmmsg.2:195
5796 " struct sockaddr_in sa;\n"
5797 " struct mmsghdr msg[2];\n"
5798 " struct iovec msg1[2], msg2;\n"
5803 #: build/C/man2/sendmmsg.2:209
5806 " sa.sin_family = AF_INET;\n"
5807 " sa.sin_addr.s_addr = htonl(INADDR_LOOPBACK);\n"
5808 " sa.sin_port = htons(1234);\n"
5809 " if (connect(sockfd, (struct sockaddr *) &sa, sizeof(sa)) == -1) {\n"
5810 " perror(\"connect()\");\n"
5811 " exit(EXIT_FAILURE);\n"
5816 #: build/C/man2/sendmmsg.2:215
5819 " memset(msg1, 0, sizeof(msg1));\n"
5820 " msg1[0].iov_base = \"one\";\n"
5821 " msg1[0].iov_len = 3;\n"
5822 " msg1[1].iov_base = \"two\";\n"
5823 " msg1[1].iov_len = 3;\n"
5827 #: build/C/man2/sendmmsg.2:219
5830 " memset(&msg2, 0, sizeof(msg2));\n"
5831 " msg2.iov_base = \"three\";\n"
5832 " msg2.iov_len = 5;\n"
5836 #: build/C/man2/sendmmsg.2:223
5839 " memset(msg, 0, sizeof(msg));\n"
5840 " msg[0].msg_hdr.msg_iov = msg1;\n"
5841 " msg[0].msg_hdr.msg_iovlen = 2;\n"
5845 #: build/C/man2/sendmmsg.2:226
5848 " msg[1].msg_hdr.msg_iov = &msg2;\n"
5849 " msg[1].msg_hdr.msg_iovlen = 1;\n"
5853 #: build/C/man2/sendmmsg.2:232
5856 " retval = sendmmsg(sockfd, msg, 2, 0);\n"
5857 " if (retval == -1)\n"
5858 " perror(\"sendmmsg()\");\n"
5860 " printf(\"%d messages sent\\en\", retval);\n"
5864 #: build/C/man2/sendmmsg.2:235
5872 #: build/C/man2/sendmmsg.2:241
5873 msgid "B<recvmmsg>(2), B<sendmsg>(2), B<socket>(2), B<socket>(7)"
5877 #: build/C/man3/sockatmark.3:25
5883 #: build/C/man3/sockatmark.3:25
5889 #: build/C/man3/sockatmark.3:28
5890 msgid "sockatmark - determine whether socket is at out-of-band mark"
5894 #: build/C/man3/sockatmark.3:30 build/C/man2/socket.2:50 build/C/man7/socket.7:63 build/C/man2/socketpair.2:49
5895 msgid "B<#include E<lt>sys/socket.hE<gt>>"
5899 #: build/C/man3/sockatmark.3:32
5900 msgid "B<int sockatmark(int >I<sockfd>B<);>"
5904 #: build/C/man3/sockatmark.3:41
5906 "B<sockatmark>(): _POSIX_C_SOURCE\\ E<gt>=\\ 200112L || _XOPEN_SOURCE\\ "
5911 #: build/C/man3/sockatmark.3:51
5913 "B<sockatmark>() returns a value indicating whether or not the socket "
5914 "referred to by the file descriptor I<sockfd> is at the out-of-band mark. If "
5915 "the socket is at the mark, then 1 is returned; if the socket is not at the "
5916 "mark, 0 is returned. This function does not remove the out-of-band mark."
5920 #: build/C/man3/sockatmark.3:58
5922 "A successful call to B<sockatmark>() returns 1 if the socket is at the "
5923 "out-of-band mark, or 0 if it is not. On error, -1 is returned and I<errno> "
5924 "is set to indicate the error."
5928 #: build/C/man3/sockatmark.3:63
5929 msgid "I<sockfd> is not a valid file descriptor."
5932 #. POSIX.1 says ENOTTY for this case
5934 #: build/C/man3/sockatmark.3:70
5935 msgid "I<sockfd> is not a file descriptor to which B<sockatmark>() can be applied."
5939 #: build/C/man3/sockatmark.3:73
5940 msgid "B<sockatmark>() was added to glibc in version 2.2.4."
5944 #: build/C/man3/sockatmark.3:78
5945 msgid "The B<sockatmark>() function is thread-safe."
5949 #: build/C/man3/sockatmark.3:80
5950 msgid "POSIX.1-2001."
5954 #: build/C/man3/sockatmark.3:87
5956 "If B<sockatmark>() returns 1, then the out-of-band data can be read using "
5957 "the B<MSG_OOB> flag of B<recv>(2)."
5961 #: build/C/man3/sockatmark.3:89
5962 msgid "Out-of-band data is supported only on some stream socket protocols."
5966 #: build/C/man3/sockatmark.3:94
5968 "B<sockatmark>() can safely be called from a handler for the B<SIGURG> "
5973 #: build/C/man3/sockatmark.3:100
5975 "B<sockatmark>() is implemented using the B<SIOCATMARK> B<ioctl>(2) "
5980 #: build/C/man3/sockatmark.3:104
5981 msgid "Prior to glibc 2.4, B<sockatmark>() did not work."
5985 #: build/C/man3/sockatmark.3:109
5987 "The following code can be used after receipt of a B<SIGURG> signal to read "
5988 "(and discard) all data up to the mark, and then read the byte of data at the "
5993 #: build/C/man3/sockatmark.3:114
5996 " char buf[BUF_LEN];\n"
6002 #: build/C/man3/sockatmark.3:121
6006 " atmark = sockatmark(sockfd);\n"
6007 " if (atmark == -1) {\n"
6008 " perror(\"sockatmark\");\n"
6014 #: build/C/man3/sockatmark.3:124
6022 #: build/C/man3/sockatmark.3:131
6025 " s = read(sockfd, buf, BUF_LEN) E<lt>= 0);\n"
6027 " perror(\"read\");\n"
6028 " if (s E<lt>= 0)\n"
6034 #: build/C/man3/sockatmark.3:138
6037 " if (atmark == 1) {\n"
6038 " if (recv(sockfd, &oobdata, 1, MSG_OOB) == -1) {\n"
6039 " perror(\"recv\");\n"
6046 #: build/C/man3/sockatmark.3:144
6047 msgid "B<fcntl>(2), B<recv>(2), B<send>(2), B<tcp>(7)"
6051 #: build/C/man2/socket.2:43 build/C/man7/socket.7:58
6057 #: build/C/man2/socket.2:43
6063 #: build/C/man2/socket.2:46
6064 msgid "socket - create an endpoint for communication"
6068 #: build/C/man2/socket.2:48 build/C/man2/socketpair.2:47
6069 msgid "B<#include E<lt>sys/types.hE<gt>> /* See NOTES */"
6073 #: build/C/man2/socket.2:52
6074 msgid "B<int socket(int >I<domain>B<, int >I<type>B<, int >I<protocol>B<);>"
6078 #: build/C/man2/socket.2:55
6079 msgid "B<socket>() creates an endpoint for communication and returns a descriptor."
6083 #: build/C/man2/socket.2:63
6085 "The I<domain> argument specifies a communication domain; this selects the "
6086 "protocol family which will be used for communication. These families are "
6087 "defined in I<E<lt>sys/socket.hE<gt>>. The currently understood formats "
6092 #: build/C/man2/socket.2:66
6094 msgid "Name:Purpose:Man page\n"
6098 #: build/C/man2/socket.2:67 build/C/man2/socket.2:74 build/C/man2/socket.2:79 build/C/man2/socket.2:84 build/C/man2/socket.2:87 build/C/man2/socket.2:94 build/C/man2/socket.2:99 build/C/man2/socket.2:104 build/C/man2/socket.2:107 build/C/man2/socket.2:112
6104 #: build/C/man2/socket.2:68
6106 msgid "B<AF_UNIX>, B<AF_LOCAL>\n"
6110 #: build/C/man2/socket.2:69 build/C/man2/socket.2:71 build/C/man2/socket.2:89 build/C/man2/socket.2:91 build/C/man2/socket.2:101 build/C/man2/socket.2:114 build/C/man2/socket.2:116 build/C/man7/socket.7:194
6116 #: build/C/man2/socket.2:70
6118 msgid "Local communication\n"
6122 #: build/C/man2/socket.2:72
6124 msgid "B<unix>(7)\n"
6128 #: build/C/man2/socket.2:73 build/C/man2/socket.2:78 build/C/man2/socket.2:83 build/C/man2/socket.2:93 build/C/man2/socket.2:98 build/C/man2/socket.2:111 build/C/man2/socket.2:118 build/C/man7/socket.7:173 build/C/man7/socket.7:177 build/C/man7/socket.7:180 build/C/man7/socket.7:186 build/C/man7/socket.7:189 build/C/man7/socket.7:198 build/C/man7/socket.7:205
6134 #: build/C/man2/socket.2:75
6136 msgid "B<AF_INET>\n"
6140 #: build/C/man2/socket.2:76
6142 msgid "T}:IPv4 Internet protocols:T{\n"
6146 #: build/C/man2/socket.2:77
6152 #: build/C/man2/socket.2:80
6154 msgid "B<AF_INET6>\n"
6158 #: build/C/man2/socket.2:81
6160 msgid "T}:IPv6 Internet protocols:T{\n"
6164 #: build/C/man2/socket.2:82
6166 msgid "B<ipv6>(7)\n"
6170 #: build/C/man2/socket.2:85
6176 #: build/C/man2/socket.2:86
6178 msgid "T}:IPX - Novell protocols:\n"
6182 #: build/C/man2/socket.2:88
6184 msgid "B<AF_NETLINK>\n"
6188 #: build/C/man2/socket.2:90
6190 msgid "Kernel user interface device\n"
6194 #: build/C/man2/socket.2:92
6196 msgid "B<netlink>(7)\n"
6200 #: build/C/man2/socket.2:95
6206 #: build/C/man2/socket.2:96
6208 msgid "T}:ITU-T X.25 / ISO-8208 protocol:T{\n"
6212 #: build/C/man2/socket.2:97
6218 #: build/C/man2/socket.2:100
6220 msgid "B<AF_AX25>\n"
6224 #: build/C/man2/socket.2:102
6226 msgid "Amateur radio AX.25 protocol\n"
6230 #: build/C/man2/socket.2:103
6236 #: build/C/man2/socket.2:105
6238 msgid "B<AF_ATMPVC>\n"
6242 #: build/C/man2/socket.2:106
6244 msgid "T}:Access to raw ATM PVCs:\n"
6248 #: build/C/man2/socket.2:108
6250 msgid "B<AF_APPLETALK>\n"
6254 #: build/C/man2/socket.2:109
6256 msgid "T}:AppleTalk:T{\n"
6260 #: build/C/man2/socket.2:110
6266 #: build/C/man2/socket.2:113
6268 msgid "B<AF_PACKET>\n"
6272 #: build/C/man2/socket.2:115
6274 msgid "Low level packet interface\n"
6278 #: build/C/man2/socket.2:117
6280 msgid "B<packet>(7)\n"
6284 #: build/C/man2/socket.2:126
6286 "The socket has the indicated I<type>, which specifies the communication "
6287 "semantics. Currently defined types are:"
6291 #: build/C/man2/socket.2:126
6293 msgid "B<SOCK_STREAM>"
6297 #: build/C/man2/socket.2:130
6299 "Provides sequenced, reliable, two-way, connection-based byte streams. An "
6300 "out-of-band data transmission mechanism may be supported."
6304 #: build/C/man2/socket.2:130
6306 msgid "B<SOCK_DGRAM>"
6310 #: build/C/man2/socket.2:134
6312 "Supports datagrams (connectionless, unreliable messages of a fixed maximum "
6317 #: build/C/man2/socket.2:134
6319 msgid "B<SOCK_SEQPACKET>"
6323 #: build/C/man2/socket.2:139
6325 "Provides a sequenced, reliable, two-way connection-based data transmission "
6326 "path for datagrams of fixed maximum length; a consumer is required to read "
6327 "an entire packet with each input system call."
6331 #: build/C/man2/socket.2:139
6337 #: build/C/man2/socket.2:142
6338 msgid "Provides raw network protocol access."
6342 #: build/C/man2/socket.2:142
6348 #: build/C/man2/socket.2:145
6349 msgid "Provides a reliable datagram layer that does not guarantee ordering."
6353 #: build/C/man2/socket.2:145
6355 msgid "B<SOCK_PACKET>"
6359 #: build/C/man2/socket.2:150
6360 msgid "Obsolete and should not be used in new programs; see B<packet>(7)."
6364 #: build/C/man2/socket.2:152
6365 msgid "Some socket types may not be implemented by all protocol families."
6369 #: build/C/man2/socket.2:160
6371 "Since Linux 2.6.27, the I<type> argument serves a second purpose: in "
6372 "addition to specifying a socket type, it may include the bitwise OR of any "
6373 "of the following values, to modify the behavior of B<socket>():"
6377 #: build/C/man2/socket.2:194
6379 "The I<protocol> specifies a particular protocol to be used with the socket. "
6380 "Normally only a single protocol exists to support a particular socket type "
6381 "within a given protocol family, in which case I<protocol> can be specified "
6382 "as 0. However, it is possible that many protocols may exist, in which case "
6383 "a particular protocol must be specified in this manner. The protocol number "
6384 "to use is specific to the ``communication domain'' in which communication is "
6385 "to take place; see B<protocols>(5). See B<getprotoent>(3) on how to map "
6386 "protocol name strings to protocol numbers."
6390 #: build/C/man2/socket.2:224
6392 "Sockets of type B<SOCK_STREAM> are full-duplex byte streams, similar to "
6393 "pipes. They do not preserve record boundaries. A stream socket must be in "
6394 "a I<connected> state before any data may be sent or received on it. A "
6395 "connection to another socket is created with a B<connect>(2) call. Once "
6396 "connected, data may be transferred using B<read>(2) and B<write>(2) calls "
6397 "or some variant of the B<send>(2) and B<recv>(2) calls. When a session "
6398 "has been completed a B<close>(2) may be performed. Out-of-band data may "
6399 "also be transmitted as described in B<send>(2) and received as described in "
6404 #: build/C/man2/socket.2:250
6406 "The communications protocols which implement a B<SOCK_STREAM> ensure that "
6407 "data is not lost or duplicated. If a piece of data for which the peer "
6408 "protocol has buffer space cannot be successfully transmitted within a "
6409 "reasonable length of time, then the connection is considered to be dead. "
6410 "When B<SO_KEEPALIVE> is enabled on the socket the protocol checks in a "
6411 "protocol-specific manner if the other end is still alive. A B<SIGPIPE> "
6412 "signal is raised if a process sends or receives on a broken stream; this "
6413 "causes naive processes, which do not handle the signal, to exit. "
6414 "B<SOCK_SEQPACKET> sockets employ the same system calls as B<SOCK_STREAM> "
6415 "sockets. The only difference is that B<read>(2) calls will return only the "
6416 "amount of data requested, and any data remaining in the arriving packet will "
6417 "be discarded. Also all message boundaries in incoming datagrams are "
6422 #: build/C/man2/socket.2:260
6424 "B<SOCK_DGRAM> and B<SOCK_RAW> sockets allow sending of datagrams to "
6425 "correspondents named in B<sendto>(2) calls. Datagrams are generally "
6426 "received with B<recvfrom>(2), which returns the next datagram along with the "
6427 "address of its sender."
6431 #: build/C/man2/socket.2:267
6433 "B<SOCK_PACKET> is an obsolete socket type to receive raw packets directly "
6434 "from the device driver. Use B<packet>(7) instead."
6438 #: build/C/man2/socket.2:290
6440 "An B<fcntl>(2) B<F_SETOWN> operation can be used to specify a process or "
6441 "process group to receive a B<SIGURG> signal when the out-of-band data "
6442 "arrives or B<SIGPIPE> signal when a B<SOCK_STREAM> connection breaks "
6443 "unexpectedly. This operation may also be used to set the process or process "
6444 "group that receives the I/O and asynchronous notification of I/O events via "
6445 "B<SIGIO>. Using B<F_SETOWN> is equivalent to an B<ioctl>(2) call with the "
6446 "B<FIOSETOWN> or B<SIOCSPGRP> argument."
6450 #: build/C/man2/socket.2:300
6452 "When the network signals an error condition to the protocol module (e.g., "
6453 "using a ICMP message for IP) the pending error flag is set for the socket. "
6454 "The next operation on this socket will return the error code of the pending "
6455 "error. For some protocols it is possible to enable a per-socket error queue "
6456 "to retrieve detailed information about the error; see B<IP_RECVERR> in "
6461 #: build/C/man2/socket.2:310
6463 "The operation of sockets is controlled by socket level I<options>. These "
6464 "options are defined in I<E<lt>sys/socket.hE<gt>>. The functions "
6465 "B<setsockopt>(2) and B<getsockopt>(2) are used to set and get options, "
6470 #: build/C/man2/socket.2:315
6472 "On success, a file descriptor for the new socket is returned. On error, -1 "
6473 "is returned, and I<errno> is set appropriately."
6477 #: build/C/man2/socket.2:320
6479 "Permission to create a socket of the specified type and/or protocol is "
6484 #: build/C/man2/socket.2:323
6485 msgid "The implementation does not support the specified address family."
6489 #: build/C/man2/socket.2:326
6490 msgid "Unknown protocol, or protocol family not available."
6493 #. Since Linux 2.6.27
6495 #: build/C/man2/socket.2:331
6496 msgid "Invalid flags in I<type>."
6500 #: build/C/man2/socket.2:334
6501 msgid "Process file table overflow."
6505 #: build/C/man2/socket.2:337
6507 msgid "B<ENOBUFS> or B<ENOMEM>"
6511 #: build/C/man2/socket.2:342
6513 "Insufficient memory is available. The socket cannot be created until "
6514 "sufficient resources are freed."
6518 #: build/C/man2/socket.2:342 build/C/man2/socketpair.2:92
6520 msgid "B<EPROTONOSUPPORT>"
6524 #: build/C/man2/socket.2:346
6526 "The protocol type or the specified protocol is not supported within this "
6531 #: build/C/man2/socket.2:348
6532 msgid "Other errors may be generated by the underlying protocol modules."
6536 #: build/C/man2/socket.2:350
6537 msgid "4.4BSD, POSIX.1-2001."
6541 #: build/C/man2/socket.2:356
6542 msgid "The B<SOCK_NONBLOCK> and B<SOCK_CLOEXEC> flags are Linux-specific."
6546 #: build/C/man2/socket.2:362
6548 "B<socket>() appeared in 4.2BSD. It is generally portable to/from non-BSD "
6549 "systems supporting clones of the BSD socket layer (including System\\ V "
6554 #: build/C/man2/socket.2:381
6556 "The manifest constants used under 4.x BSD for protocol families are "
6557 "B<PF_UNIX>, B<PF_INET>, and so on, while B<AF_UNIX>, B<AF_INET>, and so on "
6558 "are used for address families. However, already the BSD man page promises: "
6559 "\"The protocol family generally is the same as the address family\", and "
6560 "subsequent standards use AF_* everywhere."
6564 #: build/C/man2/socket.2:386
6565 msgid "An example of the use of B<socket>() is shown in B<getaddrinfo>(3)."
6569 #: build/C/man2/socket.2:409
6571 "B<accept>(2), B<bind>(2), B<connect>(2), B<fcntl>(2), B<getpeername>(2), "
6572 "B<getsockname>(2), B<getsockopt>(2), B<ioctl>(2), B<listen>(2), B<read>(2), "
6573 "B<recv>(2), B<select>(2), B<send>(2), B<shutdown>(2), B<socketpair>(2), "
6574 "B<write>(2), B<getprotoent>(3), B<ip>(7), B<socket>(7), B<tcp>(7), "
6575 "B<udp>(7), B<unix>(7)"
6579 #: build/C/man2/socket.2:415
6581 "\\(lqAn Introductory 4.3BSD Interprocess Communication Tutorial\\(rq and "
6582 "\\(lqBSD Interprocess Communication Tutorial\\(rq, reprinted in I<UNIX "
6583 "Programmer's Supplementary Documents Volume 1.>"
6587 #: build/C/man7/socket.7:61
6588 msgid "socket - Linux socket interface"
6592 #: build/C/man7/socket.7:65
6594 "I<sockfd>B< = socket(int >I<socket_family>B<, int >I<socket_type>B<, int "
6599 #: build/C/man7/socket.7:84
6601 "This manual page describes the Linux networking socket layer user "
6602 "interface. The BSD compatible sockets are the uniform interface between the "
6603 "user process and the network protocol stacks in the kernel. The protocol "
6604 "modules are grouped into I<protocol families> such as B<AF_INET>, B<AF_IPX>, "
6605 "and B<AF_PACKET>, and I<socket types> such as B<SOCK_STREAM> or "
6606 "B<SOCK_DGRAM>. See B<socket>(2) for more information on families and "
6611 #: build/C/man7/socket.7:84
6613 msgid "Socket-layer functions"
6617 #: build/C/man7/socket.7:88
6619 "These functions are used by the user process to send or receive packets and "
6620 "to do other socket operations. For more information see their respective "
6625 #: build/C/man7/socket.7:104
6627 "B<socket>(2) creates a socket, B<connect>(2) connects a socket to a remote "
6628 "socket address, the B<bind>(2) function binds a socket to a local socket "
6629 "address, B<listen>(2) tells the socket that new connections shall be "
6630 "accepted, and B<accept>(2) is used to get a new socket with a new incoming "
6631 "connection. B<socketpair>(2) returns two connected anonymous sockets "
6632 "(implemented only for a few local families like B<AF_UNIX>)"
6636 #: build/C/man7/socket.7:126
6638 "B<send>(2), B<sendto>(2), and B<sendmsg>(2) send data over a socket, and "
6639 "B<recv>(2), B<recvfrom>(2), B<recvmsg>(2) receive data from a socket. "
6640 "B<poll>(2) and B<select>(2) wait for arriving data or a readiness to send "
6641 "data. In addition, the standard I/O operations like B<write>(2), "
6642 "B<writev>(2), B<sendfile>(2), B<read>(2), and B<readv>(2) can be used to "
6643 "read and write data."
6647 #: build/C/man7/socket.7:137
6649 "B<getsockname>(2) returns the local socket address and B<getpeername>(2) "
6650 "returns the remote socket address. B<getsockopt>(2) and B<setsockopt>(2) "
6651 "are used to set or get socket layer or protocol options. B<ioctl>(2) can "
6652 "be used to set or read some other options."
6656 #: build/C/man7/socket.7:142
6658 "B<close>(2) is used to close a socket. B<shutdown>(2) closes parts of a "
6659 "full-duplex socket connection."
6663 #: build/C/man7/socket.7:148
6665 "Seeking, or calling B<pread>(2) or B<pwrite>(2) with a nonzero position is "
6666 "not supported on sockets."
6670 #: build/C/man7/socket.7:165
6672 "It is possible to do nonblocking I/O on sockets by setting the B<O_NONBLOCK> "
6673 "flag on a socket file descriptor using B<fcntl>(2). Then all operations "
6674 "that would block will (usually) return with B<EAGAIN> (operation should be "
6675 "retried later); B<connect>(2) will return B<EINPROGRESS> error. The user "
6676 "can then wait for various events via B<poll>(2) or B<select>(2)."
6680 #: build/C/man7/socket.7:169
6682 msgid "I/O events\n"
6686 #: build/C/man7/socket.7:170
6688 msgid "Event:Poll flag:Occurrence\n"
6692 #: build/C/man7/socket.7:171 build/C/man7/socket.7:174
6694 msgid "Read:POLLIN:T{\n"
6698 #: build/C/man7/socket.7:172
6700 msgid "New data arrived.\n"
6704 #: build/C/man7/socket.7:175
6706 msgid "A connection setup has been completed\n"
6710 #: build/C/man7/socket.7:176
6712 msgid "(for connection-oriented sockets)\n"
6716 #: build/C/man7/socket.7:178 build/C/man7/socket.7:181
6718 msgid "Read:POLLHUP:T{\n"
6722 #: build/C/man7/socket.7:179
6724 msgid "A disconnection request has been initiated by the other end.\n"
6728 #: build/C/man7/socket.7:182
6730 msgid "A connection is broken (only for connection-oriented protocols).\n"
6734 #: build/C/man7/socket.7:183
6736 msgid "When the socket is written\n"
6740 #: build/C/man7/socket.7:184
6742 msgid "B<SIGPIPE>\n"
6746 #: build/C/man7/socket.7:185
6748 msgid "is also sent.\n"
6752 #: build/C/man7/socket.7:187
6754 msgid "Write:POLLOUT:T{\n"
6758 #: build/C/man7/socket.7:188
6760 msgid "Socket has enough send buffer space for writing new data.\n"
6764 #: build/C/man7/socket.7:190
6766 msgid "Read/Write:T{\n"
6770 #: build/C/man7/socket.7:191
6776 #: build/C/man7/socket.7:192
6782 #: build/C/man7/socket.7:193
6788 #: build/C/man7/socket.7:195
6790 msgid "An outgoing\n"
6794 #: build/C/man7/socket.7:196
6796 msgid "B<connect>(2)\n"
6800 #: build/C/man7/socket.7:197
6806 #: build/C/man7/socket.7:199
6808 msgid "Read/Write:POLLERR:An asynchronous error occurred.\n"
6812 #: build/C/man7/socket.7:200
6814 msgid "Read/Write:POLLHUP:The other end has shut down one direction.\n"
6818 #: build/C/man7/socket.7:201
6820 msgid "Exception:POLLPRI:T{\n"
6824 #: build/C/man7/socket.7:202
6826 msgid "Urgent data arrived.\n"
6830 #: build/C/man7/socket.7:203
6836 #: build/C/man7/socket.7:204
6838 msgid "is sent then.\n"
6842 #: build/C/man7/socket.7:233
6844 "An alternative to B<poll>(2) and B<select>(2) is to let the kernel inform "
6845 "the application about events via a B<SIGIO> signal. For that the B<O_ASYNC> "
6846 "flag must be set on a socket file descriptor via B<fcntl>(2) and a valid "
6847 "signal handler for B<SIGIO> must be installed via B<sigaction>(2). See the "
6848 "I<Signals> discussion below."
6852 #: build/C/man7/socket.7:233
6854 msgid "Socket address structures"
6858 #: build/C/man7/socket.7:249
6860 "Each socket domain has its own format for socket addresses, with a "
6861 "domain-specific address structure. Each of these structures begins with an "
6862 "integer \"family\" field (typed as I<sa_family_t>) that indicates the type "
6863 "of the address structure. This allows the various system calls (e.g., "
6864 "B<connect>(2), B<bind>(2), B<accept>(2), B<getsockname>(2), "
6865 "B<getpeername>(2)), which are generic to all socket domains, to determine "
6866 "the domain of a particular socket address."
6870 #: build/C/man7/socket.7:259
6872 "To allow any type of socket address to be passed to interfaces in the "
6873 "sockets API, the type I<struct sockaddr> is defined. The purpose of this "
6874 "type is purely to allow casting of domain-specific socket address types to a "
6875 "\"generic\" type, so as to avoid compiler warnings about type mismatches in "
6876 "calls to the sockets API."
6880 #: build/C/man7/socket.7:269
6882 "In addition, the sockets API provides the data type I<struct "
6883 "sockaddr_storage>. This type is suitable to accommodate all supported "
6884 "domain-specific socket address structures; it is large enough and is aligned "
6885 "properly. (In particular, it is large enough to hold IPv6 socket "
6886 "addresses.) The structure includes the following field, which can be used "
6887 "to identify the type of socket address actually stored in the structure:"
6891 #: build/C/man7/socket.7:273
6893 msgid " sa_family_t ss_family;\n"
6897 #: build/C/man7/socket.7:281
6899 "The I<sockaddr_storage> structure is useful in programs that must handle "
6900 "socket addresses in a generic way (e.g., programs that must deal with both "
6901 "IPv4 and IPv6 socket addresses)."
6905 #: build/C/man7/socket.7:281
6907 msgid "Socket options"
6911 #. In the list below, the text used to describe argument types
6912 #. for each socket option should be more consistent
6914 #. SO_ACCEPTCONN is in POSIX.1-2001, and its origin is explained in
6915 #. W R Stevens, UNPv1
6917 #: build/C/man7/socket.7:299
6919 "The socket options listed below can be set by using B<setsockopt>(2) and "
6920 "read with B<getsockopt>(2) with the socket level set to B<SOL_SOCKET> for "
6921 "all sockets. Unless otherwise noted, I<optval> is a pointer to an I<int>."
6925 #: build/C/man7/socket.7:299
6927 msgid "B<SO_ACCEPTCONN>"
6931 #: build/C/man7/socket.7:307
6933 "Returns a value indicating whether or not this socket has been marked to "
6934 "accept connections with B<listen>(2). The value 0 indicates that this is "
6935 "not a listening socket, the value 1 indicates that this is a listening "
6936 "socket. This socket option is read-only."
6940 #: build/C/man7/socket.7:307
6942 msgid "B<SO_BINDTODEVICE>"
6946 #: build/C/man7/socket.7:326
6948 "Bind this socket to a particular device like \\(lqeth0\\(rq, as specified in "
6949 "the passed interface name. If the name is an empty string or the option "
6950 "length is zero, the socket device binding is removed. The passed option is "
6951 "a variable-length null-terminated interface name string with the maximum "
6952 "size of B<IFNAMSIZ>. If a socket is bound to an interface, only packets "
6953 "received from that particular interface are processed by the socket. Note "
6954 "that this works only for some socket types, particularly B<AF_INET> "
6955 "sockets. It is not supported for packet sockets (use normal B<bind>(2) "
6960 #: build/C/man7/socket.7:340
6962 "Before Linux 3.8, this socket option could be set, but could not retrieved "
6963 "with B<getsockopt>(2). Since Linux 3.8, it is readable. The I<optlen> "
6964 "argument should contain the buffer size available to receive the device name "
6965 "and is recommended to be B<IFNAMSZ> bytes. The real device name length is "
6966 "reported back in the I<optlen> argument."
6970 #: build/C/man7/socket.7:340
6972 msgid "B<SO_BROADCAST>"
6976 #: build/C/man7/socket.7:346
6978 "Set or get the broadcast flag. When enabled, datagram sockets are allowed "
6979 "to send packets to a broadcast address. This option has no effect on "
6980 "stream-oriented sockets."
6984 #: build/C/man7/socket.7:346
6986 msgid "B<SO_BSDCOMPAT>"
6990 #: build/C/man7/socket.7:358
6992 "Enable BSD bug-to-bug compatibility. This is used by the UDP protocol "
6993 "module in Linux 2.0 and 2.2. If enabled, ICMP errors received for a UDP "
6994 "socket will not be passed to the user program. In later kernel versions, "
6995 "support for this option has been phased out: Linux 2.4 silently ignores it, "
6996 "and Linux 2.6 generates a kernel warning (printk()) if a program uses this "
6997 "option. Linux 2.0 also enabled BSD bug-to-bug compatibility options (random "
6998 "header changing, skipping of the broadcast flag) for raw sockets with this "
6999 "option, but that was removed in Linux 2.2."
7003 #: build/C/man7/socket.7:358
7009 #: build/C/man7/socket.7:364
7011 "Enable socket debugging. Only allowed for processes with the "
7012 "B<CAP_NET_ADMIN> capability or an effective user ID of 0."
7016 #: build/C/man7/socket.7:364
7018 msgid "B<SO_DOMAIN> (since Linux 2.6.32)"
7022 #: build/C/man7/socket.7:372
7024 "Retrieves the socket domain as an integer, returning a value such as "
7025 "B<AF_INET6>. See B<socket>(2) for details. This socket option is "
7030 #: build/C/man7/socket.7:372
7036 #: build/C/man7/socket.7:377
7038 "Get and clear the pending socket error. This socket option is read-only. "
7039 "Expects an integer."
7043 #: build/C/man7/socket.7:377
7045 msgid "B<SO_DONTROUTE>"
7049 #: build/C/man7/socket.7:386
7051 "Don't send via a gateway, send only to directly connected hosts. The same "
7052 "effect can be achieved by setting the B<MSG_DONTROUTE> flag on a socket "
7053 "B<send>(2) operation. Expects an integer boolean flag."
7057 #: build/C/man7/socket.7:386
7059 msgid "B<SO_KEEPALIVE>"
7063 #: build/C/man7/socket.7:390
7065 "Enable sending of keep-alive messages on connection-oriented sockets. "
7066 "Expects an integer boolean flag."
7070 #: build/C/man7/socket.7:390
7072 msgid "B<SO_LINGER>"
7076 #: build/C/man7/socket.7:398
7078 "Sets or gets the B<SO_LINGER> option. The argument is a I<linger> "
7083 #: build/C/man7/socket.7:405
7087 " int l_onoff; /* linger active */\n"
7088 " int l_linger; /* how many seconds to linger for */\n"
7093 #: build/C/man7/socket.7:419
7095 "When enabled, a B<close>(2) or B<shutdown>(2) will not return until all "
7096 "queued messages for the socket have been successfully sent or the linger "
7097 "timeout has been reached. Otherwise, the call returns immediately and the "
7098 "closing is done in the background. When the socket is closed as part of "
7099 "B<exit>(2), it always lingers in the background."
7103 #: build/C/man7/socket.7:419
7105 msgid "B<SO_MARK> (since Linux 2.6.25)"
7108 #. commit 4a19ec5800fc3bb64e2d87c4d9fdd9e636086fe0
7109 #. and 914a9ab386a288d0f22252fc268ecbc048cdcbd5
7111 #: build/C/man7/socket.7:430
7113 "Set the mark for each packet sent through this socket (similar to the "
7114 "netfilter MARK target but socket-based). Changing the mark can be used for "
7115 "mark-based routing without netfilter or for packet filtering. Setting this "
7116 "option requires the B<CAP_NET_ADMIN> capability."
7120 #: build/C/man7/socket.7:430
7122 msgid "B<SO_OOBINLINE>"
7125 #. don't document it because it can do too much harm.
7128 #: build/C/man7/socket.7:439
7130 "If this option is enabled, out-of-band data is directly placed into the "
7131 "receive data stream. Otherwise, out-of-band data is passed only when the "
7132 "B<MSG_OOB> flag is set during receiving."
7136 #: build/C/man7/socket.7:439
7138 msgid "B<SO_PASSCRED>"
7141 #. FIXME Document SO_PASSSEC, added in 2.6.18; there is some info
7142 #. in the 2.6.18 ChangeLog
7144 #: build/C/man7/socket.7:448
7146 "Enable or disable the receiving of the B<SCM_CREDENTIALS> control message. "
7147 "For more information see B<unix>(7)."
7151 #: build/C/man7/socket.7:448
7153 msgid "B<SO_PEEK_OFF> (since Linux 3.4)"
7156 #. commit ef64a54f6e558155b4f149bb10666b9e914b6c54
7158 #: build/C/man7/socket.7:458
7160 "This option, which is currently supported only for B<unix>(7) sockets, sets "
7161 "the value of the \"peek offset\" for the B<recv>(2) system call when used "
7162 "with B<MSG_PEEK> flag."
7166 #: build/C/man7/socket.7:466
7168 "When this option is set to a negative value (it is set to -1 for all new "
7169 "sockets), traditional behavior is provided: B<recv>(2) with the B<MSG_PEEK> "
7170 "flag will peek data from the front of the queue."
7174 #: build/C/man7/socket.7:473
7176 "When the option is set to a value greater than or equal to zero, then the "
7177 "next peek at data queued in the socket will occur at the byte offset "
7178 "specified by the option value. At the same time, the \"peek offset\" will "
7179 "be incremented by the number of bytes that were peeked from the queue, so "
7180 "that a subsequent peek will return the next data in the queue."
7184 #: build/C/man7/socket.7:485
7186 "If data is removed from the front of the queue via a call to B<recv>(2) (or "
7187 "similar) without the B<MSG_PEEK> flag, the \"peek offset\" will be decreased "
7188 "by the number of bytes removed. In other words, receiving data without the "
7189 "B<MSG_PEEK> flag will cause the \"peek offset\" to be adjusted to maintain "
7190 "the correct relative position in the queued data, so that a subsequent peek "
7191 "will retrieve the data that would have been retrieved had the data not been "
7196 #: build/C/man7/socket.7:490
7198 "For datagram sockets, if the \"peek offset\" points to the middle of a "
7199 "packet, the data returned will be marked with the B<MSG_TRUNC> flag."
7203 #: build/C/man7/socket.7:494
7205 "The following example serves to illustrate the use of B<SO_PEEK_OFF>. "
7206 "Suppose a stream socket has the following queued input data:"
7210 #: build/C/man7/socket.7:496
7212 msgid " aabbccddeeff\n"
7216 #: build/C/man7/socket.7:501
7218 "The following sequence of B<recv>(2) calls would have the effect noted in "
7223 #: build/C/man7/socket.7:506
7226 "int ov = 4; // Set peek offset to 4\n"
7227 "setsockopt(fd, SOL_SOCKET, SO_PEEK_OFF, &ov, sizeof(ov));\n"
7231 #: build/C/man7/socket.7:511
7234 "recv(fd, buf, 2, MSG_PEEK); // Peeks \"cc\"; offset set to 6\n"
7235 "recv(fd, buf, 2, MSG_PEEK); // Peeks \"dd\"; offset set to 8\n"
7236 "recv(fd, buf, 2, 0); // Reads \"aa\"; offset set to 6\n"
7237 "recv(fd, buf, 2, MSG_PEEK); // Peeks \"ee\"; offset set to 8\n"
7241 #: build/C/man7/socket.7:513
7243 msgid "B<SO_PEERCRED>"
7247 #: build/C/man7/socket.7:536
7249 "Return the credentials of the foreign process connected to this socket. "
7250 "This is possible only for connected B<AF_UNIX> stream sockets and B<AF_UNIX> "
7251 "stream and datagram socket pairs created using B<socketpair>(2); see "
7252 "B<unix>(7). The returned credentials are those that were in effect at the "
7253 "time of the call to B<connect>(2) or B<socketpair>(2). The argument is a "
7254 "I<ucred> structure; define the B<_GNU_SOURCE> feature test macro to obtain "
7255 "the definition of that structure from I<E<lt>sys/socket.hE<gt>>. This "
7256 "socket option is read-only."
7260 #: build/C/man7/socket.7:536
7262 msgid "B<SO_PRIORITY>"
7266 #: build/C/man7/socket.7:549
7268 "Set the protocol-defined priority for all packets to be sent on this "
7269 "socket. Linux uses this value to order the networking queues: packets with "
7270 "a higher priority may be processed first depending on the selected device "
7271 "queueing discipline. For B<ip>(7), this also sets the IP type-of-service "
7272 "(TOS) field for outgoing packets. Setting a priority outside the range 0 to "
7273 "6 requires the B<CAP_NET_ADMIN> capability."
7277 #: build/C/man7/socket.7:549
7279 msgid "B<SO_PROTOCOL> (since Linux 2.6.32)"
7283 #: build/C/man7/socket.7:557
7285 "Retrieves the socket protocol as an integer, returning a value such as "
7286 "B<IPPROTO_SCTP>. See B<socket>(2) for details. This socket option is "
7291 #: build/C/man7/socket.7:557
7293 msgid "B<SO_RCVBUF>"
7296 #. Most (all?) other implementations do not do this -- MTK, Dec 05
7297 #. The following thread on LMKL is quite informative:
7298 #. getsockopt/setsockopt with SO_RCVBUF and SO_SNDBUF "non-standard" behavior
7300 #. http://thread.gmane.org/gmane.linux.kernel/1328935
7302 #: build/C/man7/socket.7:576
7304 "Sets or gets the maximum socket receive buffer in bytes. The kernel doubles "
7305 "this value (to allow space for bookkeeping overhead) when it is set using "
7306 "B<setsockopt>(2), and this doubled value is returned by B<getsockopt>(2). "
7307 "The default value is set by the I</proc/sys/net/core/rmem_default> file, and "
7308 "the maximum allowed value is set by the I</proc/sys/net/core/rmem_max> "
7309 "file. The minimum (doubled) value for this option is 256."
7313 #: build/C/man7/socket.7:576
7315 msgid "B<SO_RCVBUFFORCE> (since Linux 2.6.14)"
7319 #: build/C/man7/socket.7:585
7321 "Using this socket option, a privileged (B<CAP_NET_ADMIN>) process can "
7322 "perform the same task as B<SO_RCVBUF>, but the I<rmem_max> limit can be "
7327 #: build/C/man7/socket.7:585
7329 msgid "B<SO_RCVLOWAT> and B<SO_SNDLOWAT>"
7332 #. See http://marc.theaimsgroup.com/?l=linux-kernel&m=111049368106984&w=2
7333 #. Tested on kernel 2.6.14 -- mtk, 30 Nov 05
7335 #: build/C/man7/socket.7:614
7337 "Specify the minimum number of bytes in the buffer until the socket layer "
7338 "will pass the data to the protocol (B<SO_SNDLOWAT>) or the user on "
7339 "receiving (B<SO_RCVLOWAT>). These two values are initialized to 1. "
7340 "B<SO_SNDLOWAT> is not changeable on Linux (B<setsockopt>(2) fails with the "
7341 "error B<ENOPROTOOPT>). B<SO_RCVLOWAT> is changeable only since Linux 2.4. "
7342 "The B<select>(2) and B<poll>(2) system calls currently do not respect the "
7343 "B<SO_RCVLOWAT> setting on Linux, and mark a socket readable when even a "
7344 "single byte of data is available. A subsequent read from the socket will "
7345 "block until B<SO_RCVLOWAT> bytes are available."
7349 #: build/C/man7/socket.7:614
7351 msgid "B<SO_RCVTIMEO> and B<SO_SNDTIMEO>"
7354 #. Not implemented in 2.0.
7355 #. Implemented in 2.1.11 for getsockopt: always return a zero struct.
7356 #. Implemented in 2.3.41 for setsockopt, and actually used.
7357 #. in fact to EAGAIN
7359 #: build/C/man7/socket.7:649
7361 "Specify the receiving or sending timeouts until reporting an error. The "
7362 "argument is a I<struct timeval>. If an input or output function blocks for "
7363 "this period of time, and data has been sent or received, the return value of "
7364 "that function will be the amount of data transferred; if no data has been "
7365 "transferred and the timeout has been reached, then -1 is returned with "
7366 "I<errno> set to B<EAGAIN> or B<EWOULDBLOCK>, or B<EINPROGRESS> (for "
7367 "B<connect>(2)) just as if the socket was specified to be nonblocking. If "
7368 "the timeout is set to zero (the default), then the operation will never "
7369 "timeout. Timeouts only have effect for system calls that perform socket I/O "
7370 "(e.g., B<read>(2), B<recvmsg>(2), B<send>(2), B<sendmsg>(2)); timeouts have "
7371 "no effect for B<select>(2), B<poll>(2), B<epoll_wait>(2), and so on."
7375 #: build/C/man7/socket.7:649
7377 msgid "B<SO_REUSEADDR>"
7381 #: build/C/man7/socket.7:664
7383 "Indicates that the rules used in validating addresses supplied in a "
7384 "B<bind>(2) call should allow reuse of local addresses. For B<AF_INET> "
7385 "sockets this means that a socket may bind, except when there is an active "
7386 "listening socket bound to the address. When the listening socket is bound "
7387 "to B<INADDR_ANY> with a specific port then it is not possible to bind to "
7388 "this port for any local address. Argument is an integer boolean flag."
7392 #: build/C/man7/socket.7:664
7394 msgid "B<SO_RXQ_OVFL> (since Linux 2.6.33)"
7397 #. commit 3b885787ea4112eaa80945999ea0901bf742707f
7399 #: build/C/man7/socket.7:671
7401 "Indicates that an unsigned 32-bit value ancillary message (cmsg) should be "
7402 "attached to received skbs indicating the number of packets dropped by the "
7403 "socket between the last received packet and this received packet."
7407 #: build/C/man7/socket.7:671
7409 msgid "B<SO_SNDBUF>"
7412 #. Most (all?) other implementations do not do this -- MTK, Dec 05
7413 #. See also the comment to SO_RCVBUF (17 Jul 2012 LKML mail)
7415 #: build/C/man7/socket.7:687
7417 "Sets or gets the maximum socket send buffer in bytes. The kernel doubles "
7418 "this value (to allow space for bookkeeping overhead) when it is set using "
7419 "B<setsockopt>(2), and this doubled value is returned by B<getsockopt>(2). "
7420 "The default value is set by the I</proc/sys/net/core/wmem_default> file and "
7421 "the maximum allowed value is set by the I</proc/sys/net/core/wmem_max> "
7422 "file. The minimum (doubled) value for this option is 2048."
7426 #: build/C/man7/socket.7:687
7428 msgid "B<SO_SNDBUFFORCE> (since Linux 2.6.14)"
7432 #: build/C/man7/socket.7:696
7434 "Using this socket option, a privileged (B<CAP_NET_ADMIN>) process can "
7435 "perform the same task as B<SO_SNDBUF>, but the I<wmem_max> limit can be "
7440 #: build/C/man7/socket.7:696
7442 msgid "B<SO_TIMESTAMP>"
7446 #: build/C/man7/socket.7:712
7448 "Enable or disable the receiving of the B<SO_TIMESTAMP> control message. The "
7449 "timestamp control message is sent with level B<SOL_SOCKET> and the "
7450 "I<cmsg_data> field is a I<struct timeval> indicating the reception time of "
7451 "the last packet passed to the user in this call. See B<cmsg>(3) for "
7452 "details on control messages."
7456 #: build/C/man7/socket.7:712
7462 #: build/C/man7/socket.7:717
7464 "Gets the socket type as an integer (e.g., B<SOCK_STREAM>). This socket "
7465 "option is read-only."
7469 #: build/C/man7/socket.7:717
7471 msgid "B<SO_BUSY_POLL> (since Linux 3.11)"
7475 #: build/C/man7/socket.7:726
7477 "Sets the approximate time in microseconds to busy poll on a blocking receive "
7478 "when there is no data. Increasing this value requires B<CAP_NET_ADMIN>. "
7479 "The default for this option is controlled by the "
7480 "I</proc/sys/net/core/busy_read> file."
7484 #: build/C/man7/socket.7:736
7486 "The value in the I</proc/sys/net/core/busy_poll> file determines how long "
7487 "B<select>(2) and B<poll>(2) will busy poll when they operate on sockets "
7488 "with B<SO_BUSY_POLL> set and no events to report are found."
7492 #: build/C/man7/socket.7:740
7494 "In both cases, busy polling will only be done when the socket last received "
7495 "data from a network device that supports this option."
7499 #: build/C/man7/socket.7:744
7501 "While busy polling may improve latency of some applications, care must be "
7502 "taken when using it since this will increase both CPU utilization and power "
7507 #: build/C/man7/socket.7:744
7513 #: build/C/man7/socket.7:755
7515 "When writing onto a connection-oriented socket that has been shut down (by "
7516 "the local or the remote end) B<SIGPIPE> is sent to the writing process and "
7517 "B<EPIPE> is returned. The signal is not sent when the write call specified "
7518 "the B<MSG_NOSIGNAL> flag."
7522 #: build/C/man7/socket.7:780
7524 "When requested with the B<FIOSETOWN> B<fcntl>(2) or B<SIOCSPGRP> "
7525 "B<ioctl>(2), B<SIGIO> is sent when an I/O event occurs. It is possible to "
7526 "use B<poll>(2) or B<select>(2) in the signal handler to find out which "
7527 "socket the event occurred on. An alternative (in Linux 2.2) is to set a "
7528 "real-time signal using the B<F_SETSIG> B<fcntl>(2); the handler of the real "
7529 "time signal will be called with the file descriptor in the I<si_fd> field of "
7530 "its I<siginfo_t>. See B<fcntl>(2) for more information."
7533 #. .SS Ancillary messages
7535 #: build/C/man7/socket.7:788
7537 "Under some circumstances (e.g., multiple processes accessing a single "
7538 "socket), the condition that caused the B<SIGIO> may have already disappeared "
7539 "when the process reacts to the signal. If this happens, the process should "
7540 "wait again because Linux will resend the signal later."
7544 #: build/C/man7/socket.7:788
7546 msgid "/proc interfaces"
7550 #: build/C/man7/socket.7:792
7552 "The core socket networking parameters can be accessed via files in the "
7553 "directory I</proc/sys/net/core/>."
7557 #: build/C/man7/socket.7:792
7559 msgid "I<rmem_default>"
7563 #: build/C/man7/socket.7:795
7564 msgid "contains the default setting in bytes of the socket receive buffer."
7568 #: build/C/man7/socket.7:795
7574 #: build/C/man7/socket.7:801
7576 "contains the maximum socket receive buffer size in bytes which a user may "
7577 "set by using the B<SO_RCVBUF> socket option."
7581 #: build/C/man7/socket.7:801
7583 msgid "I<wmem_default>"
7587 #: build/C/man7/socket.7:804
7588 msgid "contains the default setting in bytes of the socket send buffer."
7592 #: build/C/man7/socket.7:804
7598 #: build/C/man7/socket.7:810
7600 "contains the maximum socket send buffer size in bytes which a user may set "
7601 "by using the B<SO_SNDBUF> socket option."
7605 #: build/C/man7/socket.7:810
7607 msgid "I<message_cost> and I<message_burst>"
7611 #: build/C/man7/socket.7:814
7613 "configure the token bucket filter used to load limit warning messages caused "
7614 "by external network events."
7618 #: build/C/man7/socket.7:814
7620 msgid "I<netdev_max_backlog>"
7624 #: build/C/man7/socket.7:817
7625 msgid "Maximum number of packets in the global input queue."
7629 #: build/C/man7/socket.7:817
7631 msgid "I<optmem_max>"
7634 #. netdev_fastroute is not documented because it is experimental
7636 #: build/C/man7/socket.7:822
7638 "Maximum length of ancillary data and user control data like the iovecs per "
7643 #: build/C/man7/socket.7:822
7649 #: build/C/man7/socket.7:825
7650 msgid "These operations can be accessed using B<ioctl>(2):"
7654 #: build/C/man7/socket.7:829
7657 "I<error>B< = ioctl(>I<ip_socket>B<, >I<ioctl_type>B<, "
7658 ">I<&value_result>B<);>\n"
7662 #: build/C/man7/socket.7:831
7664 msgid "B<SIOCGSTAMP>"
7668 #: build/C/man7/socket.7:855
7670 "Return a I<struct timeval> with the receive timestamp of the last packet "
7671 "passed to the user. This is useful for accurate round trip time "
7672 "measurements. See B<setitimer>(2) for a description of I<struct timeval>. "
7673 "This ioctl should be used only if the socket option B<SO_TIMESTAMP> is not "
7674 "set on the socket. Otherwise, it returns the timestamp of the last packet "
7675 "that was received while B<SO_TIMESTAMP> was not set, or it fails if no such "
7676 "packet has been received, (i.e., B<ioctl>(2) returns -1 with I<errno> set "
7681 #: build/C/man7/socket.7:855
7683 msgid "B<SIOCSPGRP>"
7687 #: build/C/man7/socket.7:874
7689 "Set the process or process group to send B<SIGIO> or B<SIGURG> signals to "
7690 "when an asynchronous I/O operation has finished or urgent data is "
7691 "available. The argument is a pointer to a I<pid_t>. If the argument is "
7692 "positive, send the signals to that process. If the argument is negative, "
7693 "send the signals to the process group with the ID of the absolute value of "
7694 "the argument. The process may only choose itself or its own process group "
7695 "to receive signals unless it has the B<CAP_KILL> capability or an effective "
7700 #: build/C/man7/socket.7:874
7706 #: build/C/man7/socket.7:884
7708 "Change the B<O_ASYNC> flag to enable or disable asynchronous I/O mode of the "
7709 "socket. Asynchronous I/O mode means that the B<SIGIO> signal or the signal "
7710 "set with B<F_SETSIG> is raised when a new I/O event occurs."
7714 #: build/C/man7/socket.7:892
7716 "Argument is an integer boolean flag. (This operation is synonymous with the "
7717 "use of B<fcntl>(2) to set the B<O_ASYNC> flag.)"
7721 #: build/C/man7/socket.7:892
7723 msgid "B<SIOCGPGRP>"
7727 #: build/C/man7/socket.7:901
7729 "Get the current process or process group that receives B<SIGIO> or B<SIGURG> "
7730 "signals, or 0 when none is set."
7734 #: build/C/man7/socket.7:905
7735 msgid "Valid B<fcntl>(2) operations:"
7739 #: build/C/man7/socket.7:905
7741 msgid "B<FIOGETOWN>"
7745 #: build/C/man7/socket.7:910
7746 msgid "The same as the B<SIOCGPGRP> B<ioctl>(2)."
7750 #: build/C/man7/socket.7:910
7752 msgid "B<FIOSETOWN>"
7756 #: build/C/man7/socket.7:915
7757 msgid "The same as the B<SIOCSPGRP> B<ioctl>(2)."
7761 #: build/C/man7/socket.7:929
7763 "B<SO_BINDTODEVICE> was introduced in Linux 2.0.30. B<SO_PASSCRED> is new in "
7764 "Linux 2.2. The I</proc> interfaces was introduced in Linux 2.2. "
7765 "B<SO_RCVTIMEO> and B<SO_SNDTIMEO> are supported since Linux 2.3.41. "
7766 "Earlier, timeouts were fixed to a protocol-specific setting, and could not "
7767 "be read or written."
7771 #: build/C/man7/socket.7:934
7773 "Linux assumes that half of the send/receive buffer is used for internal "
7774 "kernel structures; thus the values in the corresponding I</proc> files are "
7775 "twice what can be observed on the wire."
7779 #: build/C/man7/socket.7:947
7781 "Linux will only allow port reuse with the B<SO_REUSEADDR> option when this "
7782 "option was set both in the previous program that performed a B<bind>(2) to "
7783 "the port and in the program that wants to reuse the port. This differs from "
7784 "some implementations (e.g., FreeBSD) where only the later program needs to "
7785 "set the B<SO_REUSEADDR> option. Typically this difference is invisible, "
7786 "since, for example, a server program is designed to always set this option."
7789 #. FIXME Document SO_ATTACH_FILTER and SO_DETACH_FILTER
7791 #. This man page was written by Andi Kleen.
7793 #: build/C/man7/socket.7:960
7795 "The B<CONFIG_FILTER> socket options B<SO_ATTACH_FILTER> and "
7796 "B<SO_DETACH_FILTER> are not documented. The suggested interface to use them "
7797 "is via the libpcap library."
7801 #: build/C/man7/socket.7:972
7803 "B<connect>(2), B<getsockopt>(2), B<setsockopt>(2), B<socket>(2), "
7804 "B<capabilities>(7), B<ddp>(7), B<ip>(7), B<packet>(7), B<tcp>(7), B<udp>(7), "
7809 #: build/C/man2/socketcall.2:25
7815 #: build/C/man2/socketcall.2:25
7821 #: build/C/man2/socketcall.2:28
7822 msgid "socketcall - socket system calls"
7826 #: build/C/man2/socketcall.2:30
7827 msgid "B<int socketcall(int >I<call>B<, unsigned long *>I<args>B<);>"
7831 #: build/C/man2/socketcall.2:38
7833 "B<socketcall>() is a common kernel entry point for the socket system "
7834 "calls. I<call> determines which socket function to invoke. I<args> points "
7835 "to a block containing the actual arguments, which are passed through to the "
7840 #: build/C/man2/socketcall.2:42
7842 "User programs should call the appropriate functions by their usual names. "
7843 "Only standard library implementors and kernel hackers need to know about "
7848 #: build/C/man2/socketcall.2:45
7850 "This call is specific to Linux, and should not be used in programs intended "
7855 #: build/C/man2/socketcall.2:53
7857 "On a some architectures\\(emfor example, x86-64 and ARM\\(emthere is no "
7858 "B<socketcall>() system call; instead B<socket>(2), B<accept>(2), "
7859 "B<bind>(2), and so on really are implemented as separate system calls."
7863 #: build/C/man2/socketcall.2:71
7865 "B<accept>(2), B<bind>(2), B<connect>(2), B<getpeername>(2), "
7866 "B<getsockname>(2), B<getsockopt>(2), B<listen>(2), B<recv>(2), "
7867 "B<recvfrom>(2), B<recvmsg>(2), B<send>(2), B<sendmsg>(2), B<sendto>(2), "
7868 "B<setsockopt>(2), B<shutdown>(2), B<socket>(2), B<socketpair>(2)"
7872 #: build/C/man2/socketpair.2:42
7878 #: build/C/man2/socketpair.2:42
7884 #: build/C/man2/socketpair.2:45
7885 msgid "socketpair - create a pair of connected sockets"
7889 #: build/C/man2/socketpair.2:52
7891 "B<int socketpair(int >I<domain>B<, int >I<type>B<, int >I<protocol>B<, int "
7896 #: build/C/man2/socketpair.2:63
7898 "The B<socketpair>() call creates an unnamed pair of connected sockets in "
7899 "the specified I<domain>, of the specified I<type>, and using the optionally "
7900 "specified I<protocol>. For further details of these arguments, see "
7905 #: build/C/man2/socketpair.2:69
7907 "The descriptors used in referencing the new sockets are returned in I<sv>[0] "
7908 "and I<sv>[1]. The two sockets are indistinguishable."
7912 #: build/C/man2/socketpair.2:78
7913 msgid "The specified address family is not supported on this machine."
7917 #: build/C/man2/socketpair.2:83
7919 "The address I<sv> does not specify a valid part of the process address "
7924 #: build/C/man2/socketpair.2:86
7925 msgid "Too many descriptors are in use by this process."
7929 #: build/C/man2/socketpair.2:92
7930 msgid "The specified protocol does not support creation of socket pairs."
7934 #: build/C/man2/socketpair.2:95
7935 msgid "The specified protocol is not supported on this machine."
7939 #: build/C/man2/socketpair.2:103
7941 "4.4BSD, POSIX.1-2001. The B<socketpair>() function call appeared in "
7942 "4.2BSD. It is generally portable to/from non-BSD systems supporting clones "
7943 "of the BSD socket layer (including System\\ V variants)."
7947 #: build/C/man2/socketpair.2:109
7949 "On Linux, the only supported domain for this call is B<AF_UNIX> (or "
7950 "synonymously, B<AF_LOCAL>). (Most implementations have the same "
7955 #: build/C/man2/socketpair.2:118
7957 "Since Linux 2.6.27, B<socketpair>() supports the B<SOCK_NONBLOCK> and "
7958 "B<SOCK_CLOEXEC> flags described in B<socket>(2)."
7962 #: build/C/man2/socketpair.2:131
7963 msgid "B<pipe>(2), B<read>(2), B<socket>(2), B<write>(2), B<socket>(7), B<unix>(7)"