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: 2012-05-01 04:39+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=CHARSET\n"
17 "Content-Transfer-Encoding: 8bit\n"
20 #: build/C/man2/accept.2:39
26 #: build/C/man2/accept.2:39
32 #: build/C/man2/accept.2:39 build/C/man2/bind.2:66 build/C/man2/connect.2:65 build/C/man2/getsockname.2:38 build/C/man2/getsockopt.2:42 build/C/man2/listen.2:43 build/C/man2/recv.2:39 build/C/man2/recvmmsg.2:26 build/C/man2/select.2:38 build/C/man2/select_tut.2:30 build/C/man2/send.2:38 build/C/man2/sendmmsg.2:28 build/C/man3/sockatmark.3:23 build/C/man2/socket.2:41 build/C/man7/socket.7:26 build/C/man2/socketcall.2:26 build/C/man2/socketpair.2:40
38 #: build/C/man2/accept.2:39 build/C/man2/bind.2:66 build/C/man3/bindresvport.3:27 build/C/man2/connect.2:65 build/C/man3/getifaddrs.3:33 build/C/man2/getsockname.2:38 build/C/man2/getsockopt.2:42 build/C/man2/listen.2:43 build/C/man2/recv.2:39 build/C/man2/recvmmsg.2:26 build/C/man2/select.2:38 build/C/man2/select_tut.2:30 build/C/man2/send.2:38 build/C/man2/sendmmsg.2:28 build/C/man3/sockatmark.3:23 build/C/man2/socket.2:41 build/C/man7/socket.7:26 build/C/man2/socketcall.2:26 build/C/man2/socketpair.2:40
40 msgid "Linux Programmer's Manual"
44 #: build/C/man2/accept.2:40 build/C/man2/bind.2:67 build/C/man3/bindresvport.3:28 build/C/man2/connect.2:66 build/C/man3/getifaddrs.3:34 build/C/man2/getsockname.2:39 build/C/man2/getsockopt.2:43 build/C/man2/listen.2:44 build/C/man2/recv.2:40 build/C/man2/recvmmsg.2:27 build/C/man2/select.2:39 build/C/man2/select_tut.2:31 build/C/man2/send.2:39 build/C/man2/sendmmsg.2:29 build/C/man3/sockatmark.3:24 build/C/man2/socket.2:42 build/C/man7/socket.7:27 build/C/man2/socketcall.2:27 build/C/man2/socketpair.2:41
50 #: build/C/man2/accept.2:42
51 msgid "accept - accept a connection on a socket"
55 #: build/C/man2/accept.2:42 build/C/man2/bind.2:69 build/C/man3/bindresvport.3:30 build/C/man2/connect.2:68 build/C/man3/getifaddrs.3:36 build/C/man2/getsockname.2:41 build/C/man2/getsockopt.2:45 build/C/man2/listen.2:46 build/C/man2/recv.2:42 build/C/man2/recvmmsg.2:29 build/C/man2/select.2:42 build/C/man2/select_tut.2:34 build/C/man2/send.2:41 build/C/man2/sendmmsg.2:31 build/C/man3/sockatmark.3:26 build/C/man2/socket.2:44 build/C/man7/socket.7:29 build/C/man2/socketcall.2:29 build/C/man2/socketpair.2:43
61 #: build/C/man2/accept.2:46 build/C/man2/bind.2:73
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:48
72 "B<int accept(int >I<sockfd>B<, struct sockaddr *>I<addr>B<, socklen_t "
77 #: build/C/man2/accept.2:51
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:54
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:55 build/C/man2/bind.2:77 build/C/man3/bindresvport.3:37 build/C/man2/connect.2:77 build/C/man3/getifaddrs.3:45 build/C/man2/getsockname.2:48 build/C/man2/getsockopt.2:56 build/C/man2/listen.2:54 build/C/man2/recv.2:57 build/C/man2/recvmmsg.2:39 build/C/man2/select.2:81 build/C/man2/select_tut.2:73 build/C/man2/send.2:56 build/C/man2/sendmmsg.2:40 build/C/man3/sockatmark.3:40 build/C/man2/socket.2:50 build/C/man7/socket.7:33 build/C/man2/socketcall.2:31 build/C/man2/socketpair.2:50
99 #: build/C/man2/accept.2:70
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:79
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:97
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:105
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:110 build/C/man2/getsockname.2:65
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:123
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:137
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:150
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:160
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:160 build/C/man2/socket.2:162
186 msgid "B<SOCK_NONBLOCK>"
190 #: build/C/man2/accept.2:168 build/C/man2/socket.2:170
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:168 build/C/man2/socket.2:170
200 msgid "B<SOCK_CLOEXEC>"
204 #: build/C/man2/accept.2:178 build/C/man2/socket.2:180
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:178 build/C/man2/bind.2:150 build/C/man3/bindresvport.3:64 build/C/man2/connect.2:125 build/C/man3/getifaddrs.3:137 build/C/man2/getsockname.2:65 build/C/man2/getsockopt.2:129 build/C/man2/listen.2:80 build/C/man2/recv.2:386 build/C/man2/recvmmsg.2:141 build/C/man2/select.2:285 build/C/man2/select_tut.2:483 build/C/man2/send.2:273 build/C/man2/sendmmsg.2:119 build/C/man3/sockatmark.3:49 build/C/man2/socket.2:312 build/C/man2/socketpair.2:67
218 #: build/C/man2/accept.2:185
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:185
228 msgid "Error Handling"
232 #: build/C/man2/accept.2:212
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 case of TCP/IP "
239 "these are B<ENETDOWN>, B<EPROTO>, B<ENOPROTOOPT>, B<EHOSTDOWN>, B<ENONET>, "
240 "B<EHOSTUNREACH>, B<EOPNOTSUPP>, and B<ENETUNREACH>."
244 #: build/C/man2/accept.2:212 build/C/man2/bind.2:155 build/C/man3/bindresvport.3:69 build/C/man2/connect.2:130 build/C/man3/getifaddrs.3:144 build/C/man2/getsockname.2:70 build/C/man2/getsockopt.2:134 build/C/man2/listen.2:85 build/C/man2/recv.2:391 build/C/man2/recvmmsg.2:149 build/C/man2/select.2:302 build/C/man2/send.2:278 build/C/man2/sendmmsg.2:133 build/C/man3/sockatmark.3:54 build/C/man2/socket.2:317 build/C/man2/socketpair.2:72
250 #: build/C/man2/accept.2:213 build/C/man2/recv.2:396 build/C/man2/send.2:294
252 msgid "B<EAGAIN> or B<EWOULDBLOCK>"
255 #. Actually EAGAIN on Linux
257 #: build/C/man2/accept.2:221
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:221 build/C/man2/bind.2:163 build/C/man2/connect.2:167 build/C/man2/getsockname.2:71 build/C/man2/getsockopt.2:135 build/C/man2/listen.2:89 build/C/man2/recv.2:405 build/C/man2/select.2:303 build/C/man2/send.2:302 build/C/man3/sockatmark.3:55
272 #: build/C/man2/accept.2:224
273 msgid "The descriptor is invalid."
277 #: build/C/man2/accept.2:224
279 msgid "B<ECONNABORTED>"
283 #: build/C/man2/accept.2:227
284 msgid "A connection has been aborted."
288 #: build/C/man2/accept.2:227 build/C/man2/bind.2:189 build/C/man2/connect.2:173 build/C/man2/getsockname.2:76 build/C/man2/getsockopt.2:140 build/C/man2/recv.2:414 build/C/man2/send.2:311 build/C/man2/socketpair.2:76
294 #: build/C/man2/accept.2:232
295 msgid "The I<addr> argument is not in a writable part of the user address space."
299 #: build/C/man2/accept.2:232 build/C/man2/connect.2:201 build/C/man2/recv.2:418 build/C/man2/select.2:308 build/C/man2/send.2:314
305 #: build/C/man2/accept.2:237
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:237 build/C/man2/accept.2:242 build/C/man2/bind.2:167 build/C/man2/bind.2:193 build/C/man2/getsockname.2:82 build/C/man2/getsockopt.2:150 build/C/man2/recv.2:423 build/C/man2/recvmmsg.2:153 build/C/man2/select.2:312 build/C/man2/send.2:318 build/C/man3/sockatmark.3:59 build/C/man2/socket.2:325 build/C/man2/socket.2:328
318 #: build/C/man2/accept.2:242
320 "Socket is not listening for connections, or I<addrlen> is invalid (e.g., is "
325 #: build/C/man2/accept.2:247
326 msgid "(B<accept4>()) invalid value in I<flags>."
330 #: build/C/man2/accept.2:247 build/C/man2/socket.2:333 build/C/man2/socketpair.2:81
336 #: build/C/man2/accept.2:250
337 msgid "The per-process limit of open file descriptors has been reached."
341 #: build/C/man2/accept.2:250 build/C/man2/socket.2:336 build/C/man2/socketpair.2:84
347 #: build/C/man2/accept.2:253 build/C/man2/socket.2:339 build/C/man2/socketpair.2:87
348 msgid "The system limit on the total number of open files has been reached."
352 #: build/C/man2/accept.2:253
354 msgid "B<ENOBUFS>, B<ENOMEM>"
358 #: build/C/man2/accept.2:258
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:258 build/C/man2/bind.2:172 build/C/man2/connect.2:213 build/C/man2/getsockname.2:90 build/C/man2/getsockopt.2:164 build/C/man2/listen.2:94 build/C/man2/recv.2:438 build/C/man2/send.2:347
371 #: build/C/man2/accept.2:261
372 msgid "The descriptor references a file, not a socket."
376 #: build/C/man2/accept.2:261 build/C/man2/listen.2:99 build/C/man2/send.2:352 build/C/man2/socketpair.2:87
378 msgid "B<EOPNOTSUPP>"
382 #: build/C/man2/accept.2:265
383 msgid "The referenced socket is not of type B<SOCK_STREAM>."
387 #: build/C/man2/accept.2:265
393 #: build/C/man2/accept.2:268
394 msgid "Protocol error."
398 #: build/C/man2/accept.2:272
399 msgid "In addition, Linux B<accept>() may fail if:"
403 #: build/C/man2/accept.2:272
409 #: build/C/man2/accept.2:275
410 msgid "Firewall rules forbid connection."
414 #: build/C/man2/accept.2:287
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:287 build/C/man3/getifaddrs.3:157 build/C/man2/recvmmsg.2:157 build/C/man2/select.2:321 build/C/man2/sendmmsg.2:145 build/C/man3/sockatmark.3:66 build/C/man7/socket.7:696
429 #: build/C/man2/accept.2:292
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:292 build/C/man2/bind.2:220 build/C/man3/bindresvport.3:89 build/C/man2/connect.2:223 build/C/man3/getifaddrs.3:165 build/C/man2/getsockname.2:95 build/C/man2/getsockopt.2:169 build/C/man2/listen.2:104 build/C/man2/recv.2:443 build/C/man2/recvmmsg.2:162 build/C/man2/select.2:327 build/C/man2/send.2:366 build/C/man2/sendmmsg.2:150 build/C/man3/sockatmark.3:69 build/C/man2/socket.2:350 build/C/man2/socketcall.2:43 build/C/man2/socketpair.2:93
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:304
450 "B<accept>(): POSIX.1-2001, SVr4, 4.4BSD, (B<accept>() first appeared in "
455 #: build/C/man2/accept.2:307
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:322
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:322 build/C/man2/bind.2:232 build/C/man3/bindresvport.3:92 build/C/man2/connect.2:239 build/C/man3/getifaddrs.3:185 build/C/man2/getsockname.2:101 build/C/man2/getsockopt.2:176 build/C/man2/listen.2:109 build/C/man2/recv.2:453 build/C/man2/select.2:342 build/C/man2/select_tut.2:501 build/C/man2/send.2:380 build/C/man2/sendmmsg.2:153 build/C/man3/sockatmark.3:71 build/C/man2/socket.2:364 build/C/man7/socket.7:710 build/C/man2/socketcall.2:46 build/C/man2/socketpair.2:101
479 #: build/C/man2/accept.2:328 build/C/man2/bind.2:238 build/C/man2/connect.2:245 build/C/man2/getsockopt.2:182 build/C/man2/listen.2:135 build/C/man2/socket.2:370 build/C/man2/socketpair.2:122
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:349
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 call "
494 "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:349
502 msgid "The socklen_t type"
506 #: build/C/man2/accept.2:359
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:376
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:376 build/C/man2/bind.2:252 build/C/man2/connect.2:256 build/C/man3/getifaddrs.3:198 build/C/man2/listen.2:164 build/C/man2/recv.2:488 build/C/man2/select.2:484 build/C/man2/select_tut.2:527 build/C/man2/send.2:417 build/C/man3/sockatmark.3:95 build/C/man2/socket.2:382
541 #: build/C/man2/accept.2:379 build/C/man2/listen.2:167
542 msgid "See B<bind>(2)."
546 #: build/C/man2/accept.2:379 build/C/man2/bind.2:317 build/C/man3/bindresvport.3:98 build/C/man2/connect.2:261 build/C/man3/getifaddrs.3:281 build/C/man2/getsockname.2:110 build/C/man2/getsockopt.2:200 build/C/man2/listen.2:167 build/C/man2/recv.2:493 build/C/man2/recvmmsg.2:165 build/C/man2/select.2:521 build/C/man2/select_tut.2:817 build/C/man2/send.2:422 build/C/man2/sendmmsg.2:168 build/C/man3/sockatmark.3:130 build/C/man2/socket.2:387 build/C/man7/socket.7:741 build/C/man2/socketcall.2:54 build/C/man2/socketpair.2:122
552 #: build/C/man2/accept.2:386
554 "B<bind>(2), B<connect>(2), B<listen>(2), B<select>(2), B<socket>(2), "
559 #: build/C/man2/accept.2:386 build/C/man2/bind.2:330 build/C/man3/bindresvport.3:101 build/C/man2/connect.2:268 build/C/man3/getifaddrs.3:287 build/C/man2/getsockname.2:117 build/C/man2/getsockopt.2:208 build/C/man2/listen.2:173 build/C/man2/recv.2:504 build/C/man2/recvmmsg.2:172 build/C/man2/select.2:536 build/C/man2/select_tut.2:836 build/C/man2/send.2:437 build/C/man2/sendmmsg.2:173 build/C/man3/sockatmark.3:135 build/C/man2/socket.2:418 build/C/man7/socket.7:752 build/C/man2/socketcall.2:72 build/C/man2/socketpair.2:129
565 #: build/C/man2/accept.2:393 build/C/man2/bind.2:337 build/C/man3/bindresvport.3:108 build/C/man2/connect.2:275 build/C/man3/getifaddrs.3:294 build/C/man2/getsockname.2:124 build/C/man2/getsockopt.2:215 build/C/man2/listen.2:180 build/C/man2/recv.2:511 build/C/man2/recvmmsg.2:179 build/C/man2/select.2:543 build/C/man2/select_tut.2:843 build/C/man2/send.2:444 build/C/man2/sendmmsg.2:180 build/C/man3/sockatmark.3:142 build/C/man2/socket.2:425 build/C/man7/socket.7:759 build/C/man2/socketcall.2:79 build/C/man2/socketpair.2:136
567 "This page is part of release 3.40 of the Linux I<man-pages> project. A "
568 "description of the project, and information about reporting bugs, can be "
569 "found at http://www.kernel.org/doc/man-pages/."
573 #: build/C/man2/bind.2:66
579 #: build/C/man2/bind.2:66
585 #: build/C/man2/bind.2:69
586 msgid "bind - bind a name to a socket"
590 #: build/C/man2/bind.2:76
593 "B<int bind(int >I<sockfd>B<, const struct sockaddr *>I<addr>B<,>\n"
594 "B< socklen_t >I<addrlen>B<);>\n"
598 #: build/C/man2/bind.2:90
600 "When a socket is created with B<socket>(2), it exists in a name space "
601 "(address family) but has no address assigned to it. B<bind>() assigns the "
602 "address specified by I<addr> to the socket referred to by the file "
603 "descriptor I<sockfd>. I<addrlen> specifies the size, in bytes, of the "
604 "address structure pointed to by I<addr>. Traditionally, this operation is "
605 "called \\(lqassigning a name to a socket\\(rq."
609 #: build/C/man2/bind.2:97
611 "It is normally necessary to assign a local address using B<bind>() before a "
612 "B<SOCK_STREAM> socket may receive connections (see B<accept>(2))."
616 #: build/C/man2/bind.2:128
618 "The rules used in name binding vary between address families. Consult the "
619 "manual entries in Section 7 for detailed information. For B<AF_INET> see "
620 "B<ip>(7), for B<AF_INET6> see B<ipv6>(7), for B<AF_UNIX> see B<unix>(7), for "
621 "B<AF_APPLETALK> see B<ddp>(7), for B<AF_PACKET> see B<packet>(7), for "
622 "B<AF_X25> see B<x25>(7) and for B<AF_NETLINK> see B<netlink>(7)."
626 #: build/C/man2/bind.2:135
628 "The actual structure passed for the I<addr> argument will depend on the "
629 "address family. The I<sockaddr> structure is defined as something like:"
633 #: build/C/man2/bind.2:142
636 "struct sockaddr {\n"
637 " sa_family_t sa_family;\n"
638 " char sa_data[14];\n"
643 #: build/C/man2/bind.2:150
645 "The only purpose of this structure is to cast the structure pointer passed "
646 "in I<addr> in order to avoid compiler warnings. See EXAMPLE below."
650 #: build/C/man2/bind.2:155 build/C/man2/getsockname.2:70 build/C/man2/getsockopt.2:134 build/C/man2/listen.2:85 build/C/man2/socketpair.2:72
652 "On success, zero is returned. On error, -1 is returned, and I<errno> is set "
657 #: build/C/man2/bind.2:156 build/C/man2/bind.2:180 build/C/man3/bindresvport.3:74 build/C/man2/connect.2:133 build/C/man2/send.2:283 build/C/man2/socket.2:318
662 #. e.g., privileged port in AF_INET domain
664 #: build/C/man2/bind.2:160
665 msgid "The address is protected, and the user is not the superuser."
669 #: build/C/man2/bind.2:160 build/C/man3/bindresvport.3:79 build/C/man2/connect.2:146 build/C/man2/listen.2:86
671 msgid "B<EADDRINUSE>"
675 #: build/C/man2/bind.2:163
676 msgid "The given address is already in use."
680 #: build/C/man2/bind.2:167
681 msgid "I<sockfd> is not a valid descriptor."
684 #. This may change in the future: see
685 #. .I linux/unix/sock.c for details.
687 #: build/C/man2/bind.2:172
688 msgid "The socket is already bound to an address."
692 #: build/C/man2/bind.2:176
693 msgid "I<sockfd> is a descriptor for a file, not a socket."
697 #: build/C/man2/bind.2:180
698 msgid "The following errors are specific to UNIX domain (B<AF_UNIX>) sockets:"
702 #: build/C/man2/bind.2:185
704 "Search permission is denied on a component of the path prefix. (See also "
705 "B<path_resolution>(7).)"
709 #: build/C/man2/bind.2:185
711 msgid "B<EADDRNOTAVAIL>"
715 #: build/C/man2/bind.2:189
717 "A nonexistent interface was requested or the requested address was not "
722 #: build/C/man2/bind.2:193
723 msgid "I<addr> points outside the user's accessible address space."
727 #: build/C/man2/bind.2:200
728 msgid "The I<addrlen> is wrong, or the socket was not in the B<AF_UNIX> family."
732 #: build/C/man2/bind.2:200
738 #: build/C/man2/bind.2:204
739 msgid "Too many symbolic links were encountered in resolving I<addr>."
743 #: build/C/man2/bind.2:204
745 msgid "B<ENAMETOOLONG>"
749 #: build/C/man2/bind.2:208
750 msgid "I<addr> is too long."
754 #: build/C/man2/bind.2:208
760 #: build/C/man2/bind.2:211
761 msgid "The file does not exist."
765 #: build/C/man2/bind.2:211 build/C/man2/recv.2:427 build/C/man2/select.2:318 build/C/man2/send.2:341
771 #: build/C/man2/bind.2:214
772 msgid "Insufficient kernel memory was available."
776 #: build/C/man2/bind.2:214
782 #: build/C/man2/bind.2:217
783 msgid "A component of the path prefix is not a directory."
787 #: build/C/man2/bind.2:217
793 #: build/C/man2/bind.2:220
794 msgid "The socket inode would reside on a read-only file system."
797 #. SVr4 documents an additional
799 #. general error condition, and
804 #. UNIX-domain error conditions.
806 #: build/C/man2/bind.2:232
807 msgid "SVr4, 4.4BSD, POSIX.1-2001 (B<bind>() first appeared in 4.2BSD)."
811 #: build/C/man2/bind.2:249
813 "The third argument of B<bind>() is in reality an I<int> (and this is what "
814 "4.x BSD and libc4 and libc5 have). Some POSIX confusion resulted in the "
815 "present I<socklen_t>, also used by glibc. See also B<accept>(2)."
819 #: build/C/man2/bind.2:249 build/C/man2/getsockopt.2:197 build/C/man2/select.2:425 build/C/man2/send.2:412 build/C/man3/sockatmark.3:91 build/C/man7/socket.7:728
824 #. FIXME What *are* transparent proxy options?
826 #: build/C/man2/bind.2:252
827 msgid "The transparent proxy options are not described."
831 #: build/C/man2/bind.2:257
833 "An example of the use of B<bind>() with Internet domain sockets can be "
834 "found in B<getaddrinfo>(3)."
837 #. listen.7 refers to this example.
838 #. accept.7 refers to this example.
839 #. unix.7 refers to this example.
841 #: build/C/man2/bind.2:264
843 "The following example shows how to bind a stream socket in the UNIX "
844 "(B<AF_UNIX>) domain, and accept connections:"
848 #: build/C/man2/bind.2:271
851 "#include E<lt>sys/socket.hE<gt>\n"
852 "#include E<lt>sys/un.hE<gt>\n"
853 "#include E<lt>stdlib.hE<gt>\n"
854 "#include E<lt>stdio.hE<gt>\n"
855 "#include E<lt>string.hE<gt>\n"
859 #: build/C/man2/bind.2:274
862 "#define MY_SOCK_PATH \"/somepath\"\n"
863 "#define LISTEN_BACKLOG 50\n"
867 #: build/C/man2/bind.2:277
870 "#define handle_error(msg) \\e\n"
871 " do { perror(msg); exit(EXIT_FAILURE); } while (0)\n"
875 #: build/C/man2/bind.2:284
879 "main(int argc, char *argv[])\n"
882 " struct sockaddr_un my_addr, peer_addr;\n"
883 " socklen_t peer_addr_size;\n"
887 #: build/C/man2/bind.2:288
890 " sfd = socket(AF_UNIX, SOCK_STREAM, 0);\n"
892 " handle_error(\"socket\");\n"
896 #: build/C/man2/bind.2:294
899 " memset(&my_addr, 0, sizeof(struct sockaddr_un));\n"
900 " /* Clear structure */\n"
901 " my_addr.sun_family = AF_UNIX;\n"
902 " strncpy(my_addr.sun_path, MY_SOCK_PATH,\n"
903 " sizeof(my_addr.sun_path) - 1);\n"
907 #: build/C/man2/bind.2:298
910 " if (bind(sfd, (struct sockaddr *) &my_addr,\n"
911 " sizeof(struct sockaddr_un)) == -1)\n"
912 " handle_error(\"bind\");\n"
916 #: build/C/man2/bind.2:301
919 " if (listen(sfd, LISTEN_BACKLOG) == -1)\n"
920 " handle_error(\"listen\");\n"
924 #: build/C/man2/bind.2:304
927 " /* Now we can accept incoming connections one\n"
928 " at a time using accept(2) */\n"
932 #: build/C/man2/bind.2:310
935 " peer_addr_size = sizeof(struct sockaddr_un);\n"
936 " cfd = accept(sfd, (struct sockaddr *) &peer_addr,\n"
937 " &peer_addr_size);\n"
939 " handle_error(\"accept\");\n"
943 #: build/C/man2/bind.2:312
945 msgid " /* Code to deal with incoming connection(s)... */\n"
949 #: build/C/man2/bind.2:316
952 " /* When no longer required, the socket pathname, MY_SOCK_PATH\n"
953 " should be deleted using unlink(2) or remove(3) */\n"
958 #: build/C/man2/bind.2:330
960 "B<accept>(2), B<connect>(2), B<getsockname>(2), B<listen>(2), B<socket>(2), "
961 "B<getaddrinfo>(3), B<getifaddrs>(3), B<ip>(7), B<ipv6>(7), "
962 "B<path_resolution>(7), B<socket>(7), B<unix>(7)"
966 #: build/C/man3/bindresvport.3:27
972 #: build/C/man3/bindresvport.3:27 build/C/man2/connect.2:65 build/C/man2/getsockname.2:38 build/C/man2/getsockopt.2:42 build/C/man3/sockatmark.3:23
978 #: build/C/man3/bindresvport.3:30
979 msgid "bindresvport - bind a socket to a privileged IP port"
983 #: build/C/man3/bindresvport.3:34
986 "B<#include E<lt>sys/types.hE<gt>>\n"
987 "B<#include E<lt>netinet/in.hE<gt>>\n"
991 #: build/C/man3/bindresvport.3:36
993 msgid "B<int bindresvport(int >I<sockfd>B<, struct sockaddr_in *>I<sin>B<);>\n"
996 #. Glibc actually starts searching with a port # in the range 600 to 1023
998 #: build/C/man3/bindresvport.3:43
1000 "B<bindresvport>() is used to bind a socket descriptor to a privileged "
1001 "anonymous IP port, that is, a port number arbitrarily selected from the "
1002 "range 512 to 1023."
1006 #: build/C/man3/bindresvport.3:53
1008 "If the B<bind>(2) performed by B<bindresvport>() is successful, and I<sin> "
1009 "is not NULL, then I<sin-E<gt>sin_port> returns the port number actually "
1014 #: build/C/man3/bindresvport.3:64
1016 "I<sin> can be NULL, in which case I<sin-E<gt>sin_family> is implicitly taken "
1017 "to be B<AF_INET>. However, in this case, B<bindresvport>() has no way to "
1018 "return the port number actually allocated. (This information can later be "
1019 "obtained using B<getsockname>(2).)"
1023 #: build/C/man3/bindresvport.3:69
1025 "B<bindresvport>() returns 0 on success; otherwise -1 is returned and "
1026 "I<errno> set to indicate the cause of the error."
1030 #: build/C/man3/bindresvport.3:74
1032 "B<bindresvport>() can fail for any of the same reasons as B<bind>(2). In "
1033 "addition, the following errors may occur:"
1037 #: build/C/man3/bindresvport.3:79
1039 "The caller did not have superuser privilege (to be precise: the "
1040 "B<CAP_NET_BIND_SERVICE> capability is required)."
1044 #: build/C/man3/bindresvport.3:82
1045 msgid "All privileged ports are in use."
1049 #: build/C/man3/bindresvport.3:82
1051 msgid "B<EAFNOSUPPORT> (B<EPFNOSUPPORT> in glibc 2.7 and earlier)"
1055 #: build/C/man3/bindresvport.3:89
1056 msgid "I<sin> is not NULL and I<sin-E<gt>sin_family> is not B<AF_INET>."
1060 #: build/C/man3/bindresvport.3:92
1061 msgid "Not in POSIX.1-2001. Present on the BSDs, Solaris, and many other systems."
1065 #: build/C/man3/bindresvport.3:98
1067 "Unlike some B<bindresvport>() implementations, the glibc implementation "
1068 "ignores any value that the caller supplies in I<sin-E<gt>sin_port>."
1072 #: build/C/man3/bindresvport.3:101
1073 msgid "B<bind>(2), B<getsockname>(2)"
1077 #: build/C/man2/connect.2:65
1083 #: build/C/man2/connect.2:68
1084 msgid "connect - initiate a connection on a socket"
1088 #: build/C/man2/connect.2:71 build/C/man2/getsockopt.2:48 build/C/man2/listen.2:49
1090 msgid "B<#include E<lt>sys/types.hE<gt>> /* See NOTES */\n"
1094 #: build/C/man2/connect.2:73 build/C/man2/getsockname.2:44 build/C/man2/getsockopt.2:50 build/C/man2/listen.2:51 build/C/man2/recv.2:49
1096 msgid "B<#include E<lt>sys/socket.hE<gt>>\n"
1100 #: build/C/man2/connect.2:76
1103 "B<int connect(int >I<sockfd>B<, const struct sockaddr *>I<addr>B<,>\n"
1104 "B< socklen_t >I<addrlen>B<);>\n"
1108 #: build/C/man2/connect.2:95
1110 "The B<connect>() system call connects the socket referred to by the file "
1111 "descriptor I<sockfd> to the address specified by I<addr>. The I<addrlen> "
1112 "argument specifies the size of I<addr>. The format of the address in "
1113 "I<addr> is determined by the address space of the socket I<sockfd>; see "
1114 "B<socket>(2) for further details."
1118 #: build/C/man2/connect.2:111
1120 "If the socket I<sockfd> is of type B<SOCK_DGRAM> then I<addr> is the address "
1121 "to which datagrams are sent by default, and the only address from which "
1122 "datagrams are received. If the socket is of type B<SOCK_STREAM> or "
1123 "B<SOCK_SEQPACKET>, this call attempts to make a connection to the socket "
1124 "that is bound to the address specified by I<addr>."
1128 #: build/C/man2/connect.2:125
1130 "Generally, connection-based protocol sockets may successfully B<connect>() "
1131 "only once; connectionless protocol sockets may use B<connect>() multiple "
1132 "times to change their association. Connectionless sockets may dissolve the "
1133 "association by connecting to an address with the I<sa_family> member of "
1134 "I<sockaddr> set to B<AF_UNSPEC> (supported on Linux since kernel 2.2)."
1138 #: build/C/man2/connect.2:130
1140 "If the connection or binding succeeds, zero is returned. On error, -1 is "
1141 "returned, and I<errno> is set appropriately."
1145 #: build/C/man2/connect.2:133
1147 "The following are general socket errors only. There may be other "
1148 "domain-specific error codes."
1152 #: build/C/man2/connect.2:141
1154 "For UNIX domain sockets, which are identified by pathname: Write permission "
1155 "is denied on the socket file, or search permission is denied for one of the "
1156 "directories in the path prefix. (See also B<path_resolution>(7).)"
1160 #: build/C/man2/connect.2:141
1162 msgid "B<EACCES>, B<EPERM>"
1166 #: build/C/man2/connect.2:146
1168 "The user tried to connect to a broadcast address without having the socket "
1169 "broadcast flag enabled or the connection request failed because of a local "
1174 #: build/C/man2/connect.2:149
1175 msgid "Local address is already in use."
1179 #: build/C/man2/connect.2:149 build/C/man2/socket.2:322 build/C/man2/socketpair.2:73
1181 msgid "B<EAFNOSUPPORT>"
1185 #: build/C/man2/connect.2:154
1187 "The passed address didn't have the correct address family in its "
1188 "I<sa_family> field."
1192 #: build/C/man2/connect.2:154
1198 #: build/C/man2/connect.2:163
1200 "No more free local ports or insufficient entries in the routing cache. For "
1201 "B<AF_INET> see the description of I</proc/sys/net/ipv4/ip_local_port_range> "
1202 "B<ip>(7) for information on how to increase the number of local ports."
1206 #: build/C/man2/connect.2:163
1212 #: build/C/man2/connect.2:167
1214 "The socket is nonblocking and a previous connection attempt has not yet been "
1219 #: build/C/man2/connect.2:170
1220 msgid "The file descriptor is not a valid index in the descriptor table."
1224 #: build/C/man2/connect.2:170 build/C/man2/recv.2:410
1226 msgid "B<ECONNREFUSED>"
1230 #: build/C/man2/connect.2:173
1231 msgid "No-one listening on the remote address."
1235 #: build/C/man2/connect.2:176
1236 msgid "The socket structure address is outside the user's address space."
1240 #: build/C/man2/connect.2:176
1242 msgid "B<EINPROGRESS>"
1246 #: build/C/man2/connect.2:201
1248 "The socket is nonblocking and the connection cannot be completed "
1249 "immediately. It is possible to B<select>(2) or B<poll>(2) for completion "
1250 "by selecting the socket for writing. After B<select>(2) indicates "
1251 "writability, use B<getsockopt>(2) to read the B<SO_ERROR> option at level "
1252 "B<SOL_SOCKET> to determine whether B<connect>() completed successfully "
1253 "(B<SO_ERROR> is zero) or unsuccessfully (B<SO_ERROR> is one of the usual "
1254 "error codes listed here, explaining the reason for the failure)."
1257 #. For TCP, the connection will complete asynchronously.
1258 #. See http://lkml.org/lkml/2005/7/12/254
1260 #: build/C/man2/connect.2:207
1262 "The system call was interrupted by a signal that was caught; see "
1267 #: build/C/man2/connect.2:207 build/C/man2/send.2:321
1273 #: build/C/man2/connect.2:210
1274 msgid "The socket is already connected."
1278 #: build/C/man2/connect.2:210
1280 msgid "B<ENETUNREACH>"
1284 #: build/C/man2/connect.2:213
1285 msgid "Network is unreachable."
1289 #: build/C/man2/connect.2:216
1290 msgid "The file descriptor is not associated with a socket."
1294 #: build/C/man2/connect.2:216
1296 msgid "B<ETIMEDOUT>"
1300 #: build/C/man2/connect.2:223
1302 "Timeout while attempting connection. The server may be too busy to accept "
1303 "new connections. Note that for IP sockets the timeout may be very long when "
1304 "syncookies are enabled on the server."
1307 #. SVr4 documents the additional
1308 #. general error codes
1309 #. .BR EADDRNOTAVAIL ,
1311 #. .BR EAFNOSUPPORT ,
1318 #. documents many additional error conditions not described here.
1320 #: build/C/man2/connect.2:239
1322 "SVr4, 4.4BSD, (the B<connect>() function first appeared in 4.2BSD), "
1327 #: build/C/man2/connect.2:256
1329 "The third argument of B<connect>() is in reality an I<int> (and this is "
1330 "what 4.x BSD and libc4 and libc5 have). Some POSIX confusion resulted in "
1331 "the present I<socklen_t>, also used by glibc. See also B<accept>(2)."
1335 #: build/C/man2/connect.2:261
1336 msgid "An example of the use of B<connect>() is shown in B<getaddrinfo>(3)."
1340 #: build/C/man2/connect.2:268
1342 "B<accept>(2), B<bind>(2), B<getsockname>(2), B<listen>(2), B<socket>(2), "
1343 "B<path_resolution>(7)"
1347 #: build/C/man3/getifaddrs.3:33
1353 #: build/C/man3/getifaddrs.3:33
1359 #: build/C/man3/getifaddrs.3:33
1365 #: build/C/man3/getifaddrs.3:36
1366 msgid "getifaddrs, freeifaddrs - get interface addresses"
1370 #: build/C/man3/getifaddrs.3:40
1373 "B<#include E<lt>sys/types.hE<gt>>\n"
1374 "B<#include E<lt>ifaddrs.hE<gt>>\n"
1378 #: build/C/man3/getifaddrs.3:42
1380 msgid "B<int getifaddrs(struct ifaddrs **>I<ifap>B<);>\n"
1384 #: build/C/man3/getifaddrs.3:44
1386 msgid "B<void freeifaddrs(struct ifaddrs *>I<ifa>B<);>\n"
1390 #: build/C/man3/getifaddrs.3:55
1392 "The B<getifaddrs>() function creates a linked list of structures describing "
1393 "the network interfaces of the local system, and stores the address of the "
1394 "first item of the list in I<*ifap>. The list consists of I<ifaddrs> "
1395 "structures, defined as follows:"
1399 #: build/C/man3/getifaddrs.3:74
1402 "struct ifaddrs {\n"
1403 " struct ifaddrs *ifa_next; /* Next item in list */\n"
1404 " char *ifa_name; /* Name of interface */\n"
1405 " unsigned int ifa_flags; /* Flags from SIOCGIFFLAGS */\n"
1406 " struct sockaddr *ifa_addr; /* Address of interface */\n"
1407 " struct sockaddr *ifa_netmask; /* Netmask of interface */\n"
1409 " struct sockaddr *ifu_broadaddr;\n"
1410 " /* Broadcast address of interface */\n"
1411 " struct sockaddr *ifu_dstaddr;\n"
1412 " /* Point-to-point destination address */\n"
1414 "#define ifa_broadaddr ifa_ifu.ifu_broadaddr\n"
1415 "#define ifa_dstaddr ifa_ifu.ifu_dstaddr\n"
1416 " void *ifa_data; /* Address-specific data */\n"
1421 #: build/C/man3/getifaddrs.3:81
1423 "The I<ifa_next> field contains a pointer to the next structure on the list, "
1424 "or NULL if this is the last item of the list."
1429 #. indicates the maximum length of this field.
1431 #: build/C/man3/getifaddrs.3:88
1432 msgid "The I<ifa_name> points to the null-terminated interface name."
1436 #: build/C/man3/getifaddrs.3:97
1438 "The I<ifa_flags> field contains the interface flags, as returned by the "
1439 "B<SIOCGIFFLAGS> B<ioctl>(2) operation (see B<netdevice>(7) for a list of "
1444 #: build/C/man3/getifaddrs.3:105
1446 "The I<ifa_addr> field points to a structure containing the interface "
1447 "address. (The I<sa_family> subfield should be consulted to determine the "
1448 "format of the address structure.)"
1452 #: build/C/man3/getifaddrs.3:111
1454 "The I<ifa_netmask> field points to a structure containing the netmask "
1455 "associated with I<ifa_addr>, if applicable for the address family."
1459 #: build/C/man3/getifaddrs.3:126
1461 "Depending on whether the bit B<IFF_BROADCAST> or B<IFF_POINTOPOINT> is set "
1462 "in I<ifa_flags> (only one can be set at a time), either I<ifa_broadaddr> "
1463 "will contain the broadcast address associated with I<ifa_addr> (if "
1464 "applicable for the address family) or I<ifa_dstaddr> will contain the "
1465 "destination address of the point-to-point interface."
1469 #: build/C/man3/getifaddrs.3:131
1471 "The I<ifa_data> field points to a buffer containing address-family-specific "
1472 "data; this field may be NULL if there is no such data for this interface."
1476 #: build/C/man3/getifaddrs.3:137
1478 "The data returned by B<getifaddrs>() is dynamically allocated and should be "
1479 "freed using B<freeifaddrs>() when no longer needed."
1483 #: build/C/man3/getifaddrs.3:144
1485 "On success, B<getifaddrs>() returns zero; on error, -1 is returned, and "
1486 "I<errno> is set appropriately."
1490 #: build/C/man3/getifaddrs.3:157
1492 "B<getifaddrs>() may fail and set I<errno> for any of the errors specified "
1493 "for B<socket>(2), B<bind>(2), B<getsockname>(2), B<recvmsg>(2), "
1494 "B<sendto>(2), B<malloc>(3), or B<realloc>(3)."
1498 #: build/C/man3/getifaddrs.3:165
1500 "The B<getifaddrs>() function first appeared in glibc 2.3, but before glibc "
1501 "2.3.3, the implementation only supported IPv4 addresses; IPv6 support was "
1502 "added in glibc 2.3.3. Support of address families other than IPv4 is only "
1503 "available on kernels that support netlink."
1506 #. , but the BSD-derived documentation generally
1507 #. appears to be confused and obsolete on this point.
1508 #. i.e., commonly it still says one of them will be NULL, even if
1509 #. the ifa_ifu union is already present
1511 #: build/C/man3/getifaddrs.3:185
1513 "Not in POSIX.1-2001. This function first appeared in BSDi and is present on "
1514 "the BSD systems, but with slightly different semantics "
1515 "documented\\(emreturning one entry per interface, not per address. This "
1516 "means I<ifa_addr> and other fields can actually be NULL if the interface has "
1517 "no address, and no link-level address is returned if the interface has an IP "
1518 "address assigned. Also, the way of choosing either I<ifa_broadaddr> or "
1519 "I<ifa_dstaddr> differs on various systems."
1523 #: build/C/man3/getifaddrs.3:198
1525 "The addresses returned on Linux will usually be the IPv4 and IPv6 addresses "
1526 "assigned to the interface, but also one B<AF_PACKET> address per interface "
1527 "containing lower-level details about the interface and its physical layer. "
1528 "In this case, the I<ifa_data> field may contain a pointer to a I<struct "
1529 "net_device_stats>, defined in I<E<lt>linux/netdevice.hE<gt>>, which contains "
1530 "various interface attributes and statistics."
1534 #: build/C/man3/getifaddrs.3:205
1536 "The program below demonstrates the use of B<getifaddrs>(), B<freeifaddrs>(), "
1537 "and B<getnameinfo>(3). Here is what we see when running this program on one "
1542 #: build/C/man3/getifaddrs.3:219
1546 "lo address family: 17 (AF_PACKET)\n"
1547 "eth0 address family: 17 (AF_PACKET)\n"
1548 "lo address family: 2 (AF_INET)\n"
1549 " address: E<lt>127.0.0.1E<gt>\n"
1550 "eth0 address family: 2 (AF_INET)\n"
1551 " address: E<lt>10.1.1.4E<gt>\n"
1552 "lo address family: 10 (AF_INET6)\n"
1553 " address: E<lt>::1E<gt>\n"
1554 "eth0 address family: 10 (AF_INET6)\n"
1555 " address: E<lt>fe80::2d0:59ff:feda:eb51%eth0E<gt>\n"
1559 #: build/C/man3/getifaddrs.3:221
1561 msgid "Program source"
1565 #: build/C/man3/getifaddrs.3:231
1568 "#include E<lt>arpa/inet.hE<gt>\n"
1569 "#include E<lt>sys/socket.hE<gt>\n"
1570 "#include E<lt>netdb.hE<gt>\n"
1571 "#include E<lt>ifaddrs.hE<gt>\n"
1572 "#include E<lt>stdio.hE<gt>\n"
1573 "#include E<lt>stdlib.hE<gt>\n"
1574 "#include E<lt>unistd.hE<gt>\n"
1578 #: build/C/man3/getifaddrs.3:238
1582 "main(int argc, char *argv[])\n"
1584 " struct ifaddrs *ifaddr, *ifa;\n"
1586 " char host[NI_MAXHOST];\n"
1590 #: build/C/man3/getifaddrs.3:243
1593 " if (getifaddrs(&ifaddr) == -1) {\n"
1594 " perror(\"getifaddrs\");\n"
1595 " exit(EXIT_FAILURE);\n"
1600 #: build/C/man3/getifaddrs.3:246
1603 " /* Walk through linked list, maintaining head pointer so we\n"
1604 " can free list later */\n"
1608 #: build/C/man3/getifaddrs.3:250
1611 " for (ifa = ifaddr; ifa != NULL; ifa = ifa-E<gt>ifa_next) {\n"
1612 " if (ifa-E<gt>ifa_addr == NULL)\n"
1617 #: build/C/man3/getifaddrs.3:252
1619 msgid " family = ifa-E<gt>ifa_addr-E<gt>sa_family;\n"
1623 #: build/C/man3/getifaddrs.3:255
1626 " /* Display interface name and family (including symbolic\n"
1627 " form of the latter for the common families) */\n"
1631 #: build/C/man3/getifaddrs.3:261
1634 " printf(\"%s\\t address family: %d%s\\en\",\n"
1635 " ifa-E<gt>ifa_name, family,\n"
1636 " (family == AF_PACKET) ? \" (AF_PACKET)\" :\n"
1637 " (family == AF_INET) ? \" (AF_INET)\" :\n"
1638 " (family == AF_INET6) ? \" (AF_INET6)\" : \"\");\n"
1642 #: build/C/man3/getifaddrs.3:263
1644 msgid " /* For an AF_INET* interface address, display the address */\n"
1648 #: build/C/man3/getifaddrs.3:276
1651 " if (family == AF_INET || family == AF_INET6) {\n"
1652 " s = getnameinfo(ifa-E<gt>ifa_addr,\n"
1653 " (family == AF_INET) ? sizeof(struct sockaddr_in) :\n"
1654 " sizeof(struct sockaddr_in6),\n"
1655 " host, NI_MAXHOST, NULL, 0, NI_NUMERICHOST);\n"
1657 " printf(\"getnameinfo() failed: %s\\en\", gai_strerror(s));\n"
1658 " exit(EXIT_FAILURE);\n"
1660 " printf(\"\\etaddress: E<lt>%sE<gt>\\en\", host);\n"
1666 #: build/C/man3/getifaddrs.3:280
1669 " freeifaddrs(ifaddr);\n"
1670 " exit(EXIT_SUCCESS);\n"
1675 #: build/C/man3/getifaddrs.3:287
1676 msgid "B<bind>(2), B<getsockname>(2), B<socket>(2), B<packet>(7), B<ifconfig>(8)"
1680 #: build/C/man2/getsockname.2:38
1686 #: build/C/man2/getsockname.2:41
1687 msgid "getsockname - get socket name"
1691 #: build/C/man2/getsockname.2:47
1694 "B<int getsockname(int >I<sockfd>B<, struct sockaddr *>I<addr>B<, socklen_t "
1695 "*>I<addrlen>B<);>\n"
1699 #: build/C/man2/getsockname.2:60
1701 "B<getsockname>() returns the current address to which the socket I<sockfd> "
1702 "is bound, in the buffer pointed to by I<addr>. The I<addrlen> argument "
1703 "should be initialized to indicate the amount of space (in bytes) pointed to "
1704 "by I<addr>. On return it contains the actual size of the socket address."
1708 #: build/C/man2/getsockname.2:76 build/C/man2/getsockopt.2:140 build/C/man2/listen.2:94
1709 msgid "The argument I<sockfd> is not a valid descriptor."
1713 #: build/C/man2/getsockname.2:82
1715 "The I<addr> argument points to memory not in a valid part of the process "
1720 #: build/C/man2/getsockname.2:86
1721 msgid "I<addrlen> is invalid (e.g., is negative)."
1725 #: build/C/man2/getsockname.2:86 build/C/man2/send.2:333
1731 #: build/C/man2/getsockname.2:90
1733 "Insufficient resources were available in the system to perform the "
1738 #: build/C/man2/getsockname.2:95 build/C/man2/getsockopt.2:169
1739 msgid "The argument I<sockfd> is a file, not a socket."
1742 #. SVr4 documents additional ENOMEM
1743 #. and ENOSR error codes.
1745 #: build/C/man2/getsockname.2:101
1747 "SVr4, 4.4BSD (the B<getsockname>() function call appeared in 4.2BSD), "
1752 #: build/C/man2/getsockname.2:110
1754 "The third argument of B<getsockname>() is in reality an I<int *> (and this "
1755 "is what 4.x BSD and libc4 and libc5 have). Some POSIX confusion resulted in "
1756 "the present I<socklen_t>, also used by glibc. See also B<accept>(2)."
1760 #: build/C/man2/getsockname.2:117
1762 "B<bind>(2), B<socket>(2), B<getifaddrs>(3), B<ip>(7), B<socket>(7), "
1767 #: build/C/man2/getsockopt.2:42
1773 #: build/C/man2/getsockopt.2:45
1774 msgid "getsockopt, setsockopt - get and set options on sockets"
1778 #: build/C/man2/getsockopt.2:55
1781 "B<int getsockopt(int >I<sockfd>B<, int >I<level>B<, int >I<optname>B<,>\n"
1782 "B< void *>I<optval>B<, socklen_t *>I<optlen>B<);>\n"
1783 "B<int setsockopt(int >I<sockfd>B<, int >I<level>B<, int >I<optname>B<,>\n"
1784 "B< const void *>I<optval>B<, socklen_t >I<optlen>B<);>\n"
1788 #: build/C/man2/getsockopt.2:65
1790 "B<getsockopt>() and B<setsockopt>() manipulate options for the socket "
1791 "referred to by the file descriptor I<sockfd>. Options may exist at multiple "
1792 "protocol levels; they are always present at the uppermost socket level."
1796 #: build/C/man2/getsockopt.2:84
1798 "When manipulating socket options, the level at which the option resides and "
1799 "the name of the option must be specified. To manipulate options at the "
1800 "sockets API level, I<level> is specified as B<SOL_SOCKET>. To manipulate "
1801 "options at any other level the protocol number of the appropriate protocol "
1802 "controlling the option is supplied. For example, to indicate that an option "
1803 "is to be interpreted by the B<TCP> protocol, I<level> should be set to the "
1804 "protocol number of B<TCP>; see B<getprotoent>(3)."
1808 #: build/C/man2/getsockopt.2:106
1810 "The arguments I<optval> and I<optlen> are used to access option values for "
1811 "B<setsockopt>(). For B<getsockopt>() they identify a buffer in which the "
1812 "value for the requested option(s) are to be returned. For B<getsockopt>(), "
1813 "I<optlen> is a value-result argument, initially containing the size of the "
1814 "buffer pointed to by I<optval>, and modified on return to indicate the "
1815 "actual size of the value returned. If no option value is to be supplied or "
1816 "returned, I<optval> may be NULL."
1820 #: build/C/man2/getsockopt.2:116
1822 "I<Optname> and any specified options are passed uninterpreted to the "
1823 "appropriate protocol module for interpretation. The include file "
1824 "I<E<lt>sys/socket.hE<gt>> contains definitions for socket level options, "
1825 "described below. Options at other protocol levels vary in format and name; "
1826 "consult the appropriate entries in section 4 of the manual."
1830 #: build/C/man2/getsockopt.2:125
1832 "Most socket-level options utilize an I<int> argument for I<optval>. For "
1833 "B<setsockopt>(), the argument should be nonzero to enable a boolean option, "
1834 "or zero if the option is to be disabled."
1838 #: build/C/man2/getsockopt.2:129
1840 "For a description of the available socket options see B<socket>(7) and the "
1841 "appropriate protocol man pages."
1845 #: build/C/man2/getsockopt.2:150
1847 "The address pointed to by I<optval> is not in a valid part of the process "
1848 "address space. For B<getsockopt>(), this error may also be returned if "
1849 "I<optlen> is not in a valid part of the process address space."
1853 #: build/C/man2/getsockopt.2:161
1855 "I<optlen> invalid in B<setsockopt>(). In some cases this error can also "
1856 "occur for an invalid value in I<optval> (e.g., for the B<IP_ADD_MEMBERSHIP> "
1857 "option described in B<ip>(7))."
1861 #: build/C/man2/getsockopt.2:161
1863 msgid "B<ENOPROTOOPT>"
1867 #: build/C/man2/getsockopt.2:164
1868 msgid "The option is unknown at the level indicated."
1871 #. SVr4 documents additional ENOMEM and ENOSR error codes, but does
1873 #. .BR SO_SNDLOWAT ", " SO_RCVLOWAT ", " SO_SNDTIMEO ", " SO_RCVTIMEO
1876 #: build/C/man2/getsockopt.2:176
1877 msgid "SVr4, 4.4BSD (these system calls first appeared in 4.2BSD), POSIX.1-2001."
1881 #: build/C/man2/getsockopt.2:197
1883 "The I<optlen> argument of B<getsockopt>() and B<setsockopt>() is in "
1884 "reality an I<int [*]> (and this is what 4.x BSD and libc4 and libc5 have). "
1885 "Some POSIX confusion resulted in the present I<socklen_t>, also used by "
1886 "glibc. See also B<accept>(2)."
1890 #: build/C/man2/getsockopt.2:200
1892 "Several of the socket options should be handled at lower levels of the "
1897 #: build/C/man2/getsockopt.2:208
1899 "B<ioctl>(2), B<socket>(2), B<getprotoent>(3), B<protocols>(5), B<socket>(7), "
1900 "B<tcp>(7), B<unix>(7)"
1904 #: build/C/man2/listen.2:43
1910 #: build/C/man2/listen.2:43
1916 #: build/C/man2/listen.2:46
1917 msgid "listen - listen for connections on a socket"
1921 #: build/C/man2/listen.2:53
1923 msgid "B<int listen(int >I<sockfd>B<, int >I<backlog>B<);>\n"
1927 #: build/C/man2/listen.2:61
1929 "B<listen>() marks the socket referred to by I<sockfd> as a passive socket, "
1930 "that is, as a socket that will be used to accept incoming connection "
1931 "requests using B<accept>(2)."
1935 #: build/C/man2/listen.2:68
1937 "The I<sockfd> argument is a file descriptor that refers to a socket of type "
1938 "B<SOCK_STREAM> or B<SOCK_SEQPACKET>."
1942 #: build/C/man2/listen.2:80
1944 "The I<backlog> argument defines the maximum length to which the queue of "
1945 "pending connections for I<sockfd> may grow. If a connection request arrives "
1946 "when the queue is full, the client may receive an error with an indication "
1947 "of B<ECONNREFUSED> or, if the underlying protocol supports retransmission, "
1948 "the request may be ignored so that a later reattempt at connection succeeds."
1952 #: build/C/man2/listen.2:89
1953 msgid "Another socket is already listening on the same port."
1957 #: build/C/man2/listen.2:99 build/C/man2/send.2:352
1958 msgid "The argument I<sockfd> is not a socket."
1962 #: build/C/man2/listen.2:104
1963 msgid "The socket is not of a type that supports the B<listen>() operation."
1967 #: build/C/man2/listen.2:109
1969 "4.4BSD, POSIX.1-2001. The B<listen>() function call first appeared in "
1974 #: build/C/man2/listen.2:111
1975 msgid "To accept connections, the following steps are performed:"
1979 #: build/C/man2/listen.2:112 build/C/man2/select_tut.2:345
1985 #: build/C/man2/listen.2:115
1986 msgid "A socket is created with B<socket>(2)."
1990 #: build/C/man2/listen.2:115 build/C/man2/select_tut.2:354
1996 #: build/C/man2/listen.2:121
1998 "The socket is bound to a local address using B<bind>(2), so that other "
1999 "sockets may be B<connect>(2)ed to it."
2003 #: build/C/man2/listen.2:121 build/C/man2/select_tut.2:358
2009 #: build/C/man2/listen.2:125
2011 "A willingness to accept incoming connections and a queue limit for incoming "
2012 "connections are specified with B<listen>()."
2016 #: build/C/man2/listen.2:125 build/C/man2/select_tut.2:365
2022 #: build/C/man2/listen.2:128
2023 msgid "Connections are accepted with B<accept>(2)."
2027 #: build/C/man2/listen.2:151
2029 "The behavior of the I<backlog> argument on TCP sockets changed with Linux "
2030 "2.2. Now it specifies the queue length for I<completely> established "
2031 "sockets waiting to be accepted, instead of the number of incomplete "
2032 "connection requests. The maximum length of the queue for incomplete sockets "
2033 "can be set using I</proc/sys/net/ipv4/tcp_max_syn_backlog>. When syncookies "
2034 "are enabled there is no logical maximum length and this setting is ignored. "
2035 "See B<tcp>(7) for more information."
2038 #. The following is now rather historic information (MTK, Jun 05)
2039 #. Don't rely on this value in portable applications since BSD
2040 #. (and some BSD-derived systems) limit the backlog to 5.
2042 #: build/C/man2/listen.2:164
2044 "If the I<backlog> argument is greater than the value in "
2045 "I</proc/sys/net/core/somaxconn>, then it is silently truncated to that "
2046 "value; the default value in this file is 128. In kernels before 2.4.25, "
2047 "this limit was a hard coded value, B<SOMAXCONN>, with the value 128."
2051 #: build/C/man2/listen.2:173
2052 msgid "B<accept>(2), B<bind>(2), B<connect>(2), B<socket>(2), B<socket>(7)"
2056 #: build/C/man2/recv.2:39
2062 #: build/C/man2/recv.2:39
2068 #: build/C/man2/recv.2:42
2069 msgid "recv, recvfrom, recvmsg - receive a message from a socket"
2073 #: build/C/man2/recv.2:47 build/C/man2/select.2:53 build/C/man2/select_tut.2:45
2075 msgid "B<#include E<lt>sys/types.hE<gt>>\n"
2079 #: build/C/man2/recv.2:51
2082 "B<ssize_t recv(int >I<sockfd>B<, void *>I<buf>B<, size_t >I<len>B<, int "
2087 #: build/C/man2/recv.2:54
2090 "B<ssize_t recvfrom(int >I<sockfd>B<, void *>I<buf>B<, size_t >I<len>B<, int "
2092 "B< struct sockaddr *>I<src_addr>B<, socklen_t "
2093 "*>I<addrlen>B<);>\n"
2097 #: build/C/man2/recv.2:56
2100 "B<ssize_t recvmsg(int >I<sockfd>B<, struct msghdr *>I<msg>B<, int "
2105 #: build/C/man2/recv.2:64
2107 "The B<recvfrom>() and B<recvmsg>() calls are used to receive messages from "
2108 "a socket, and may be used to receive data on a socket whether or not it is "
2109 "connection-oriented."
2112 #. (Note: for datagram sockets in both the UNIX and Internet domains,
2116 #. is also filled in for stream sockets in the UNIX domain, but is not
2117 #. filled in for stream sockets in the Internet domain.)
2118 #. [The above notes on AF_UNIX and AF_INET sockets apply as at
2119 #. Kernel 2.4.18. (MTK, 22 Jul 02)]
2121 #: build/C/man2/recv.2:93
2123 "If I<src_addr> is not NULL, and the underlying protocol provides the source "
2124 "address, this source address is filled in. When I<src_addr> is NULL, "
2125 "nothing is filled in; in this case, I<addrlen> is not used, and should also "
2126 "be NULL. The argument I<addrlen> is a value-result argument, which the "
2127 "caller should initialize before the call to the size of the buffer "
2128 "associated with I<src_addr>, and modified on return to indicate the actual "
2129 "size of the source address. The returned address is truncated if the buffer "
2130 "provided is too small; in this case, I<addrlen> will return a value greater "
2131 "than was supplied to the call."
2135 #: build/C/man2/recv.2:105
2137 "The B<recv>() call is normally used only on a I<connected> socket (see "
2138 "B<connect>(2)) and is identical to B<recvfrom>() with a NULL I<src_addr> "
2143 #: build/C/man2/recv.2:111
2145 "All three routines return the length of the message on successful "
2146 "completion. If a message is too long to fit in the supplied buffer, excess "
2147 "bytes may be discarded depending on the type of socket the message is "
2152 #: build/C/man2/recv.2:121
2154 "If no messages are available at the socket, the receive calls wait for a "
2155 "message to arrive, unless the socket is nonblocking (see B<fcntl>(2)), in "
2156 "which case the value -1 is returned and the external variable I<errno> is "
2157 "set to B<EAGAIN> or B<EWOULDBLOCK>. The receive calls normally return any "
2158 "data available, up to the requested amount, rather than waiting for receipt "
2159 "of the full amount requested."
2163 #: build/C/man2/recv.2:127
2165 "The B<select>(2) or B<poll>(2) call may be used to determine when more "
2170 #: build/C/man2/recv.2:133
2172 "The I<flags> argument to a B<recv>() call is formed by ORing one or more of "
2173 "the following values:"
2177 #: build/C/man2/recv.2:133
2179 msgid "B<MSG_CMSG_CLOEXEC> (B<recvmsg>() only; since Linux 2.6.23)"
2183 #: build/C/man2/recv.2:144
2185 "Set the close-on-exec flag for the file descriptor received via a UNIX "
2186 "domain file descriptor using the B<SCM_RIGHTS> operation (described in "
2187 "B<unix>(7)). This flag is useful for the same reasons as the B<O_CLOEXEC> "
2188 "flag of B<open>(2)."
2192 #: build/C/man2/recv.2:144 build/C/man2/send.2:186
2194 msgid "B<MSG_DONTWAIT> (since Linux 2.2)"
2198 #: build/C/man2/recv.2:154
2200 "Enables nonblocking operation; if the operation would block, the call fails "
2201 "with the error B<EAGAIN> or B<EWOULDBLOCK> (this can also be enabled using "
2202 "the B<O_NONBLOCK> flag with the B<F_SETFL> B<fcntl>(2))."
2206 #: build/C/man2/recv.2:154
2208 msgid "B<MSG_ERRQUEUE> (since Linux 2.2)"
2212 #: build/C/man2/recv.2:173
2214 "This flag specifies that queued errors should be received from the socket "
2215 "error queue. The error is passed in an ancillary message with a type "
2216 "dependent on the protocol (for IPv4 B<IP_RECVERR>). The user should supply "
2217 "a buffer of sufficient size. See B<cmsg>(3) and B<ip>(7) for more "
2218 "information. The payload of the original packet that caused the error is "
2219 "passed as normal data via I<msg_iovec>. The original destination address of "
2220 "the datagram that caused the error is supplied via I<msg_name>."
2224 #: build/C/man2/recv.2:185 build/C/man2/recv.2:248
2226 "For local errors, no address is passed (this can be checked with the "
2227 "I<cmsg_len> member of the I<cmsghdr>). For error receives, the "
2228 "B<MSG_ERRQUEUE> is set in the I<msghdr>. After an error has been passed, "
2229 "the pending socket error is regenerated based on the next queued error and "
2230 "will be passed on the next socket operation."
2234 #: build/C/man2/recv.2:189
2235 msgid "The error is supplied in a I<sock_extended_err> structure:"
2239 #: build/C/man2/recv.2:196
2242 "#define SO_EE_ORIGIN_NONE 0\n"
2243 "#define SO_EE_ORIGIN_LOCAL 1\n"
2244 "#define SO_EE_ORIGIN_ICMP 2\n"
2245 "#define SO_EE_ORIGIN_ICMP6 3\n"
2249 #: build/C/man2/recv.2:208
2252 "struct sock_extended_err\n"
2254 " uint32_t ee_errno; /* error number */\n"
2255 " uint8_t ee_origin; /* where the error originated */\n"
2256 " uint8_t ee_type; /* type */\n"
2257 " uint8_t ee_code; /* code */\n"
2258 " uint8_t ee_pad; /* padding */\n"
2259 " uint32_t ee_info; /* additional information */\n"
2260 " uint32_t ee_data; /* other data */\n"
2261 " /* More data may follow */\n"
2266 #: build/C/man2/recv.2:210
2268 msgid "struct sockaddr *SO_EE_OFFENDER(struct sock_extended_err *);\n"
2272 #: build/C/man2/recv.2:234
2274 "I<ee_errno> contains the I<errno> number of the queued error. I<ee_origin> "
2275 "is the origin code of where the error originated. The other fields are "
2276 "protocol-specific. The macro B<SOCK_EE_OFFENDER> returns a pointer to the "
2277 "address of the network object where the error originated from given a "
2278 "pointer to the ancillary message. If this address is not known, the "
2279 "I<sa_family> member of the I<sockaddr> contains B<AF_UNSPEC> and the other "
2280 "fields of the I<sockaddr> are undefined. The payload of the packet that "
2281 "caused the error is passed as normal data."
2285 #: build/C/man2/recv.2:248 build/C/man2/recv.2:379 build/C/man2/send.2:228
2291 #: build/C/man2/recv.2:255
2293 "This flag requests receipt of out-of-band data that would not be received in "
2294 "the normal data stream. Some protocols place expedited data at the head of "
2295 "the normal data queue, and thus this flag cannot be used with such "
2300 #: build/C/man2/recv.2:255
2306 #: build/C/man2/recv.2:262
2308 "This flag causes the receive operation to return data from the beginning of "
2309 "the receive queue without removing that data from the queue. Thus, a "
2310 "subsequent receive call will return the same data."
2314 #: build/C/man2/recv.2:262
2316 msgid "B<MSG_TRUNC> (since Linux 2.2)"
2320 #: build/C/man2/recv.2:273
2322 "For raw (B<AF_PACKET>), Internet datagram (since Linux 2.4.27/2.6.8), and "
2323 "netlink (since Linux 2.6.22) sockets: return the real length of the packet "
2324 "or datagram, even when it was longer than the passed buffer. Not "
2325 "implemented for UNIX domain (B<unix>(7)) sockets."
2329 #: build/C/man2/recv.2:276
2330 msgid "For use with Internet stream sockets, see B<tcp>(7)."
2334 #: build/C/man2/recv.2:276
2336 msgid "B<MSG_WAITALL> (since Linux 2.2)"
2340 #: build/C/man2/recv.2:283
2342 "This flag requests that the operation block until the full request is "
2343 "satisfied. However, the call may still return less data than requested if a "
2344 "signal is caught, an error or disconnect occurs, or the next data to be "
2345 "received is of a different type than that returned."
2349 #: build/C/man2/recv.2:291
2351 "The B<recvmsg>() call uses a I<msghdr> structure to minimize the number of "
2352 "directly supplied arguments. This structure is defined as follows in "
2353 "I<E<lt>sys/socket.hE<gt>>:"
2357 #: build/C/man2/recv.2:298
2360 "struct iovec { /* Scatter/gather array items */\n"
2361 " void *iov_base; /* Starting address */\n"
2362 " size_t iov_len; /* Number of bytes to transfer */\n"
2367 #: build/C/man2/recv.2:308 build/C/man2/send.2:256
2371 " void *msg_name; /* optional address */\n"
2372 " socklen_t msg_namelen; /* size of address */\n"
2373 " struct iovec *msg_iov; /* scatter/gather array */\n"
2374 " size_t msg_iovlen; /* # elements in msg_iov */\n"
2375 " void *msg_control; /* ancillary data, see below */\n"
2376 " size_t msg_controllen; /* ancillary data buffer len */\n"
2377 " int msg_flags; /* flags on received message */\n"
2382 #: build/C/man2/recv.2:338
2384 "Here I<msg_name> and I<msg_namelen> specify the source address if the socket "
2385 "is unconnected; I<msg_name> may be given as a NULL pointer if no names are "
2386 "desired or required. The fields I<msg_iov> and I<msg_iovlen> describe "
2387 "scatter-gather locations, as discussed in B<readv>(2). The field "
2388 "I<msg_control>, which has length I<msg_controllen>, points to a buffer for "
2389 "other protocol control-related messages or miscellaneous ancillary data. "
2390 "When B<recvmsg>() is called, I<msg_controllen> should contain the length of "
2391 "the available buffer in I<msg_control>; upon return from a successful call "
2392 "it will contain the length of the control message sequence."
2396 #: build/C/man2/recv.2:340
2397 msgid "The messages are of the form:"
2401 #: build/C/man2/recv.2:350
2404 "struct cmsghdr {\n"
2405 " socklen_t cmsg_len; /* data byte count, including hdr */\n"
2406 " int cmsg_level; /* originating protocol */\n"
2407 " int cmsg_type; /* protocol-specific type */\n"
2409 " unsigned char cmsg_data[]; */\n"
2414 #: build/C/man2/recv.2:355
2415 msgid "Ancillary data should only be accessed by the macros defined in B<cmsg>(3)."
2419 #: build/C/man2/recv.2:358
2421 "As an example, Linux uses this ancillary data mechanism to pass extended "
2422 "errors, IP options, or file descriptors over UNIX domain sockets."
2426 #: build/C/man2/recv.2:366
2428 "The I<msg_flags> field in the I<msghdr> is set on return of B<recvmsg>(). "
2429 "It can contain several flags:"
2433 #: build/C/man2/recv.2:366
2439 #: build/C/man2/recv.2:371
2441 "indicates end-of-record; the data returned completed a record (generally "
2442 "used with sockets of type B<SOCK_SEQPACKET>)."
2446 #: build/C/man2/recv.2:371
2448 msgid "B<MSG_TRUNC>"
2452 #: build/C/man2/recv.2:375
2454 "indicates that the trailing portion of a datagram was discarded because the "
2455 "datagram was larger than the buffer supplied."
2459 #: build/C/man2/recv.2:375
2461 msgid "B<MSG_CTRUNC>"
2465 #: build/C/man2/recv.2:379
2467 "indicates that some control data were discarded due to lack of space in the "
2468 "buffer for ancillary data."
2472 #: build/C/man2/recv.2:382
2473 msgid "is returned to indicate that expedited or out-of-band data were received."
2477 #: build/C/man2/recv.2:382
2479 msgid "B<MSG_ERRQUEUE>"
2483 #: build/C/man2/recv.2:386
2485 "indicates that no data was received but an extended error from the socket "
2490 #: build/C/man2/recv.2:391
2492 "These calls return the number of bytes received, or -1 if an error "
2493 "occurred. The return value will be 0 when the peer has performed an orderly "
2498 #: build/C/man2/recv.2:396
2500 "These are some standard errors generated by the socket layer. Additional "
2501 "errors may be generated and returned from the underlying protocol modules; "
2502 "see their manual pages."
2505 #. Actually EAGAIN on Linux
2507 #: build/C/man2/recv.2:405
2509 "The socket is marked nonblocking and the receive operation would block, or a "
2510 "receive timeout had been set and the timeout expired before data was "
2511 "received. POSIX.1-2001 allows either error to be returned for this case, "
2512 "and does not require these constants to have the same value, so a portable "
2513 "application should check for both possibilities."
2517 #: build/C/man2/recv.2:410
2518 msgid "The argument I<sockfd> is an invalid descriptor."
2522 #: build/C/man2/recv.2:414
2524 "A remote host refused to allow the network connection (typically because it "
2525 "is not running the requested service)."
2529 #: build/C/man2/recv.2:418
2530 msgid "The receive buffer pointer(s) point outside the process's address space."
2534 #: build/C/man2/recv.2:423
2536 "The receive was interrupted by delivery of a signal before any data were "
2537 "available; see B<signal>(7)."
2541 #: build/C/man2/recv.2:427 build/C/man2/send.2:321
2542 msgid "Invalid argument passed."
2546 #: build/C/man2/recv.2:431
2547 msgid "Could not allocate memory for B<recvmsg>()."
2551 #: build/C/man2/recv.2:431 build/C/man2/send.2:344
2557 #: build/C/man2/recv.2:438
2559 "The socket is associated with a connection-oriented protocol and has not "
2560 "been connected (see B<connect>(2) and B<accept>(2))."
2564 #: build/C/man2/recv.2:443
2565 msgid "The argument I<sockfd> does not refer to a socket."
2569 #: build/C/man2/recv.2:446
2570 msgid "4.4BSD (these function calls first appeared in 4.2BSD), POSIX.1-2001."
2574 #: build/C/man2/recv.2:453
2576 "POSIX.1-2001 only describes the B<MSG_OOB>, B<MSG_PEEK>, and B<MSG_WAITALL> "
2581 #: build/C/man2/recv.2:469
2583 "The prototypes given above follow glibc2. The Single UNIX Specification "
2584 "agrees, except that it has return values of type I<ssize_t> (while 4.x BSD "
2585 "and libc4 and libc5 all have I<int>). The I<flags> argument is I<int> in "
2586 "4.x BSD, but I<unsigned int> in libc4 and libc5. The I<len> argument is "
2587 "I<int> in 4.x BSD, but I<size_t> in libc4 and libc5. The I<addrlen> "
2588 "argument is I<int\\ *> in 4.x BSD, libc4 and libc5. The present "
2589 "I<socklen_t\\ *> was invented by POSIX. See also B<accept>(2)."
2592 #. glibc bug raised 12 Mar 2006
2593 #. http://sourceware.org/bugzilla/show_bug.cgi?id=2448
2594 #. The problem is an underlying kernel issue: the size of the
2595 #. __kernel_size_t type used to type this field varies
2596 #. across architectures, but socklen_t is always 32 bits.
2598 #: build/C/man2/recv.2:483 build/C/man2/send.2:407
2600 "According to POSIX.1-2001, the I<msg_controllen> field of the I<msghdr> "
2601 "structure should be typed as I<socklen_t>, but glibc currently types it as "
2606 #: build/C/man2/recv.2:488
2608 "See B<recvmmsg(2)> for information about a Linux-specific system call that "
2609 "can be used to receive multiple datagrams in a single call."
2613 #: build/C/man2/recv.2:493
2614 msgid "An example of the use of B<recvfrom>() is shown in B<getaddrinfo>(3)."
2618 #: build/C/man2/recv.2:504
2620 "B<fcntl>(2), B<getsockopt>(2), B<read>(2), B<recvmmsg>(2), B<select>(2), "
2621 "B<shutdown>(2), B<socket>(2), B<cmsg>(3), B<sockatmark>(3), B<socket>(7)"
2625 #: build/C/man2/recvmmsg.2:26
2631 #: build/C/man2/recvmmsg.2:26
2637 #: build/C/man2/recvmmsg.2:29
2638 msgid "recvmmsg - receive multiple messages on a socket"
2642 #: build/C/man2/recvmmsg.2:33 build/C/man2/sendmmsg.2:35
2645 "B<#define _GNU_SOURCE>\n"
2646 "B<#include E<lt>sys/socket.hE<gt>>\n"
2650 #: build/C/man2/recvmmsg.2:36
2653 "B<int recvmmsg(int >I<sockfd>B<, struct mmsghdr *>I<msgvec>B<, unsigned int "
2658 #: build/C/man2/recvmmsg.2:38
2660 msgid "B< unsigned int >I<flags>B<, struct timespec *>I<timeout>B<);>\n"
2664 #: build/C/man2/recvmmsg.2:50
2666 "The B<recvmmsg>() system call is an extension of B<recvmsg>(2) that allows "
2667 "the caller to receive multiple messages from a socket using a single system "
2668 "call. (This has performance benefits for some applications.) A further "
2669 "extension over B<recvmsg>(2) is support for a timeout on the receive "
2674 #: build/C/man2/recvmmsg.2:54
2676 "The I<sockfd> argument is the file descriptor of the socket to receive data "
2681 #: build/C/man2/recvmmsg.2:62 build/C/man2/sendmmsg.2:62
2683 "The I<msgvec> argument is a pointer to an array of I<mmsghdr> structures. "
2684 "The size of this array is specified in I<vlen>."
2688 #: build/C/man2/recvmmsg.2:68 build/C/man2/sendmmsg.2:68
2689 msgid "The I<mmsghdr> structure is defined in I<E<lt>sys/socket.hE<gt>> as:"
2693 #: build/C/man2/recvmmsg.2:75
2696 "struct mmsghdr {\n"
2697 " struct msghdr msg_hdr; /* Message header */\n"
2698 " unsigned int msg_len; /* Number of received bytes for header */\n"
2703 #: build/C/man2/recvmmsg.2:90
2705 "The I<msg_hdr> field is a I<msghdr> structure, as described in "
2706 "B<recvmsg>(2). The I<msg_len> field is the number of bytes returned for the "
2707 "message in the entry. This field has the same value as the return value of "
2708 "a single B<recvmsg>(2) on the header."
2712 #: build/C/man2/recvmmsg.2:97
2714 "The I<flags> argument contains flags ORed together. The flags are the same "
2715 "as documented for B<recvmsg>(2), with the following addition:"
2719 #: build/C/man2/recvmmsg.2:97
2721 msgid "B<MSG_WAITFORONE>"
2725 #: build/C/man2/recvmmsg.2:102
2726 msgid "Turns on B<MSG_DONTWAIT> after the first message has been received."
2730 #: build/C/man2/recvmmsg.2:115
2732 "The I<timeout> argument points to a I<struct timespec> (see "
2733 "B<clock_gettime>(2)) defining a timeout (seconds plus nanoseconds) for the "
2734 "receive operation. If I<timeout> is I<NULL> then the operation blocks "
2739 #: build/C/man2/recvmmsg.2:126
2741 "A blocking B<recvmmsg>() call blocks until I<vlen> messages have been "
2742 "received or until the timeout expires. A nonblocking call reads as many "
2743 "messages as are available (up to the limit specified by I<vlen>) and "
2744 "returns immediately."
2748 #: build/C/man2/recvmmsg.2:141
2750 "On return from B<recvmmsg>(), successive elements of I<msgvec> are updated "
2751 "to contain information about each received message: I<msg_len> contains the "
2752 "size of the received message; the subfields of I<msg_hdr> are updated as "
2753 "described in B<recvmsg>(2). The return value of the call indicates the "
2754 "number of elements of I<msgvec> that have been updated."
2758 #: build/C/man2/recvmmsg.2:149
2760 "On success, B<recvmmsg>() returns the number of messages received in "
2761 "I<msgvec>; on error, -1 is returned, and I<errno> is set to indicate the "
2766 #: build/C/man2/recvmmsg.2:153
2768 "Errors are as for B<recvmsg>(2). In addition, the following error can "
2773 #: build/C/man2/recvmmsg.2:157
2774 msgid "I<timeout> is invalid."
2778 #: build/C/man2/recvmmsg.2:162
2780 "The B<recvmmsg>() system call was added in Linux 2.6.32. Support in glibc "
2781 "was added in version 2.12."
2785 #: build/C/man2/recvmmsg.2:165
2786 msgid "B<recvmmsg>() is Linux-specific."
2790 #: build/C/man2/recvmmsg.2:172
2792 "B<clock_gettime>(2), B<recvmsg>(2), B<sendmmsg>(2), B<sendmsg>(2), "
2793 "B<socket>(2), B<socket>(7)"
2797 #: build/C/man2/select.2:38
2803 #: build/C/man2/select.2:38
2809 #: build/C/man2/select.2:42 build/C/man2/select_tut.2:34
2811 "select, pselect, FD_CLR, FD_ISSET, FD_SET, FD_ZERO - synchronous I/O "
2816 #: build/C/man2/select.2:45 build/C/man2/select_tut.2:37
2818 msgid "/* According to POSIX.1-2001 */\n"
2822 #: build/C/man2/select.2:47 build/C/man2/select.2:68 build/C/man2/select_tut.2:39 build/C/man2/select_tut.2:60
2824 msgid "B<#include E<lt>sys/select.hE<gt>>\n"
2828 #: build/C/man2/select.2:49 build/C/man2/select_tut.2:41
2830 msgid "/* According to earlier standards */\n"
2834 #: build/C/man2/select.2:51 build/C/man2/select_tut.2:43
2836 msgid "B<#include E<lt>sys/time.hE<gt>>\n"
2840 #: build/C/man2/select.2:55 build/C/man2/select_tut.2:47
2842 msgid "B<#include E<lt>unistd.hE<gt>>\n"
2846 #: build/C/man2/select.2:58
2849 "B<int select(int >I<nfds>B<, fd_set *>I<readfds>B<, fd_set "
2850 "*>I<writefds>B<,>\n"
2851 "B< fd_set *>I<exceptfds>B<, struct timeval *>I<timeout>B<);>\n"
2855 #: build/C/man2/select.2:60 build/C/man2/select_tut.2:52
2857 msgid "B<void FD_CLR(int >I<fd>B<, fd_set *>I<set>B<);>\n"
2861 #: build/C/man2/select.2:62 build/C/man2/select_tut.2:54
2863 msgid "B<int FD_ISSET(int >I<fd>B<, fd_set *>I<set>B<);>\n"
2867 #: build/C/man2/select.2:64 build/C/man2/select_tut.2:56
2869 msgid "B<void FD_SET(int >I<fd>B<, fd_set *>I<set>B<);>\n"
2873 #: build/C/man2/select.2:66 build/C/man2/select_tut.2:58
2875 msgid "B<void FD_ZERO(fd_set *>I<set>B<);>\n"
2879 #: build/C/man2/select.2:72
2882 "B<int pselect(int >I<nfds>B<, fd_set *>I<readfds>B<, fd_set "
2883 "*>I<writefds>B<,>\n"
2884 "B< fd_set *>I<exceptfds>B<, const struct timespec "
2885 "*>I<timeout>B<,>\n"
2886 "B< const sigset_t *>I<sigmask>B<);>\n"
2890 #: build/C/man2/select.2:77 build/C/man2/select_tut.2:69 build/C/man3/sockatmark.3:34
2891 msgid "Feature Test Macro Requirements for glibc (see B<feature_test_macros>(7)):"
2895 #: build/C/man2/select.2:81 build/C/man2/select_tut.2:73
2897 "B<pselect>(): _POSIX_C_SOURCE\\ E<gt>=\\ 200112L || _XOPEN_SOURCE\\ E<gt>=\\ "
2902 #: build/C/man2/select.2:92
2904 "B<select>() and B<pselect>() allow a program to monitor multiple file "
2905 "descriptors, waiting until one or more of the file descriptors become "
2906 "\"ready\" for some class of I/O operation (e.g., input possible). A file "
2907 "descriptor is considered ready if it is possible to perform the "
2908 "corresponding I/O operation (e.g., B<read>(2)) without blocking."
2912 #: build/C/man2/select.2:98
2914 "The operation of B<select>() and B<pselect>() is identical, with three "
2919 #: build/C/man2/select.2:98
2925 #: build/C/man2/select.2:108
2927 "B<select>() uses a timeout that is a I<struct timeval> (with seconds and "
2928 "microseconds), while B<pselect>() uses a I<struct timespec> (with seconds "
2933 #: build/C/man2/select.2:108
2939 #: build/C/man2/select.2:116
2941 "B<select>() may update the I<timeout> argument to indicate how much time "
2942 "was left. B<pselect>() does not change this argument."
2946 #: build/C/man2/select.2:116
2952 #: build/C/man2/select.2:125
2954 "B<select>() has no I<sigmask> argument, and behaves as B<pselect>() called "
2955 "with NULL I<sigmask>."
2959 #: build/C/man2/select.2:143
2961 "Three independent sets of file descriptors are watched. Those listed in "
2962 "I<readfds> will be watched to see if characters become available for reading "
2963 "(more precisely, to see if a read will not block; in particular, a file "
2964 "descriptor is also ready on end-of-file), those in I<writefds> will be "
2965 "watched to see if a write will not block, and those in I<exceptfds> will be "
2966 "watched for exceptions. On exit, the sets are modified in place to indicate "
2967 "which file descriptors actually changed status. Each of the three file "
2968 "descriptor sets may be specified as NULL if no file descriptors are to be "
2969 "watched for the corresponding class of events."
2973 #: build/C/man2/select.2:156
2975 "Four macros are provided to manipulate the sets. B<FD_ZERO>() clears a "
2976 "set. B<FD_SET>() and B<FD_CLR>() respectively add and remove a given file "
2977 "descriptor from a set. B<FD_ISSET>() tests to see if a file descriptor is "
2978 "part of the set; this is useful after B<select>() returns."
2982 #: build/C/man2/select.2:159
2984 "I<nfds> is the highest-numbered file descriptor in any of the three sets, "
2989 #: build/C/man2/select.2:175
2991 "I<timeout> is an upper bound on the amount of time elapsed before "
2992 "B<select>() returns. If both fields of the I<timeval> structure are zero, "
2993 "then B<select>() returns immediately. (This is useful for polling.) If "
2994 "I<timeout> is NULL (no timeout), B<select>() can block indefinitely."
2998 #: build/C/man2/select.2:185
3000 "I<sigmask> is a pointer to a signal mask (see B<sigprocmask>(2)); if it is "
3001 "not NULL, then B<pselect>() first replaces the current signal mask by the "
3002 "one pointed to by I<sigmask>, then does the \"select\" function, and then "
3003 "restores the original signal mask."
3007 #: build/C/man2/select.2:191
3009 "Other than the difference in the precision of the I<timeout> argument, the "
3010 "following B<pselect>() call:"
3014 #: build/C/man2/select.2:195
3017 " ready = pselect(nfds, &readfds, &writefds, &exceptfds,\n"
3018 " timeout, &sigmask);\n"
3022 #: build/C/man2/select.2:200
3023 msgid "is equivalent to I<atomically> executing the following calls:"
3027 #: build/C/man2/select.2:203
3029 msgid " sigset_t origmask;\n"
3033 #: build/C/man2/select.2:207
3036 " sigprocmask(SIG_SETMASK, &sigmask, &origmask);\n"
3037 " ready = select(nfds, &readfds, &writefds, &exceptfds, timeout);\n"
3038 " sigprocmask(SIG_SETMASK, &origmask, NULL);\n"
3042 #: build/C/man2/select.2:228
3044 "The reason that B<pselect>() is needed is that if one wants to wait for "
3045 "either a signal or for a file descriptor to become ready, then an atomic "
3046 "test is needed to prevent race conditions. (Suppose the signal handler sets "
3047 "a global flag and returns. Then a test of this global flag followed by a "
3048 "call of B<select>() could hang indefinitely if the signal arrived just "
3049 "after the test but just before the call. By contrast, B<pselect>() allows "
3050 "one to first block signals, handle the signals that have come in, then call "
3051 "B<pselect>() with the desired I<sigmask>, avoiding the race.)"
3055 #: build/C/man2/select.2:228
3061 #: build/C/man2/select.2:232
3063 "The time structures involved are defined in I<E<lt>sys/time.hE<gt>> and look "
3068 #: build/C/man2/select.2:239
3071 "struct timeval {\n"
3072 " long tv_sec; /* seconds */\n"
3073 " long tv_usec; /* microseconds */\n"
3078 #: build/C/man2/select.2:243
3083 #: build/C/man2/select.2:250
3086 "struct timespec {\n"
3087 " long tv_sec; /* seconds */\n"
3088 " long tv_nsec; /* nanoseconds */\n"
3093 #: build/C/man2/select.2:254
3094 msgid "(However, see below on the POSIX.1-2001 versions.)"
3098 #: build/C/man2/select.2:262
3100 "Some code calls B<select>() with all three sets empty, I<nfds> zero, and a "
3101 "non-NULL I<timeout> as a fairly portable way to sleep with subsecond "
3105 #. .PP - it is rumored that:
3106 #. On BSD, when a timeout occurs, the file descriptor bits are not changed.
3107 #. - it is certainly true that:
3108 #. Linux follows SUSv2 and sets the bit masks to zero upon a timeout.
3110 #: build/C/man2/select.2:285
3112 "On Linux, B<select>() modifies I<timeout> to reflect the amount of time not "
3113 "slept; most other implementations do not do this. (POSIX.1-2001 permits "
3114 "either behavior.) This causes problems both when Linux code which reads "
3115 "I<timeout> is ported to other operating systems, and when code is ported to "
3116 "Linux that reuses a I<struct timeval> for multiple B<select>()s in a loop "
3117 "without reinitializing it. Consider I<timeout> to be undefined after "
3118 "B<select>() returns."
3122 #: build/C/man2/select.2:302
3124 "On success, B<select>() and B<pselect>() return the number of file "
3125 "descriptors contained in the three returned descriptor sets (that is, the "
3126 "total number of bits that are set in I<readfds>, I<writefds>, I<exceptfds>) "
3127 "which may be zero if the timeout expires before anything interesting "
3128 "happens. On error, -1 is returned, and I<errno> is set appropriately; the "
3129 "sets and I<timeout> become undefined, so do not rely on their contents after "
3134 #: build/C/man2/select.2:308
3136 "An invalid file descriptor was given in one of the sets. (Perhaps a file "
3137 "descriptor that was already closed, or one on which an error has occurred.)"
3141 #: build/C/man2/select.2:312
3142 msgid "A signal was caught; see B<signal>(7)."
3146 #: build/C/man2/select.2:318
3147 msgid "I<nfds> is negative or the value contained within I<timeout> is invalid."
3151 #: build/C/man2/select.2:321
3152 msgid "unable to allocate memory for internal tables."
3156 #: build/C/man2/select.2:327
3158 "B<pselect>() was added to Linux in kernel 2.6.16. Prior to this, "
3159 "B<pselect>() was emulated in glibc (but see BUGS)."
3163 #: build/C/man2/select.2:338
3165 "B<select>() conforms to POSIX.1-2001 and 4.4BSD (B<select>() first "
3166 "appeared in 4.2BSD). Generally portable to/from non-BSD systems supporting "
3167 "clones of the BSD socket layer (including System V variants). However, note "
3168 "that the System V variant typically sets the timeout variable before exit, "
3169 "but the BSD variant does not."
3173 #: build/C/man2/select.2:342
3174 msgid "B<pselect>() is defined in POSIX.1g, and in POSIX.1-2001."
3178 #: build/C/man2/select.2:359
3180 "An I<fd_set> is a fixed size buffer. Executing B<FD_CLR>() or B<FD_SET>() "
3181 "with a value of I<fd> that is negative or is equal to or larger than "
3182 "B<FD_SETSIZE> will result in undefined behavior. Moreover, POSIX requires "
3183 "I<fd> to be a valid file descriptor."
3187 #: build/C/man2/select.2:368
3189 "Concerning the types involved, the classical situation is that the two "
3190 "fields of a I<timeval> structure are typed as I<long> (as shown above), and "
3191 "the structure is defined in I<E<lt>sys/time.hE<gt>>. The POSIX.1-2001 "
3196 #: build/C/man2/select.2:375
3199 "struct timeval {\n"
3200 " time_t tv_sec; /* seconds */\n"
3201 " suseconds_t tv_usec; /* microseconds */\n"
3206 #: build/C/man2/select.2:386
3208 "where the structure is defined in I<E<lt>sys/select.hE<gt>> and the data "
3209 "types I<time_t> and I<suseconds_t> are defined in I<E<lt>sys/types.hE<gt>>."
3213 #: build/C/man2/select.2:398
3215 "Concerning prototypes, the classical situation is that one should include "
3216 "I<E<lt>time.hE<gt>> for B<select>(). The POSIX.1-2001 situation is that one "
3217 "should include I<E<lt>sys/select.hE<gt>> for B<select>() and B<pselect>()."
3221 #: build/C/man2/select.2:410
3223 "Libc4 and libc5 do not have a I<E<lt>sys/select.hE<gt>> header; under glibc "
3224 "2.0 and later this header exists. Under glibc 2.0 it unconditionally gives "
3225 "the wrong prototype for B<pselect>(). Under glibc 2.1 to 2.2.1 it gives "
3226 "B<pselect>() when B<_GNU_SOURCE> is defined. Since glibc 2.2.2 the "
3227 "requirements are as shown in the SYNOPSIS."
3231 #: build/C/man2/select.2:410
3237 #: build/C/man2/select.2:425
3239 "The Linux B<pselect>() system call modifies its I<timeout> argument. "
3240 "However, the glibc wrapper function hides this behavior by using a local "
3241 "variable for the timeout argument that is passed to the system call. Thus, "
3242 "the glibc B<pselect>() function does not modify its I<timeout> argument; "
3243 "this is the behavior required by POSIX.1-2001."
3247 #: build/C/man2/select.2:431
3249 "Glibc 2.0 provided a version of B<pselect>() that did not take a I<sigmask> "
3254 #: build/C/man2/select.2:444
3256 "Starting with version 2.1, glibc provided an emulation of B<pselect>() that "
3257 "was implemented using B<sigprocmask>(2) and B<select>(). This "
3258 "implementation remained vulnerable to the very race condition that "
3259 "B<pselect>() was designed to prevent. Modern versions of glibc use the "
3260 "(race-free) B<pselect>() system call on kernels where it is provided."
3264 #: build/C/man2/select.2:453
3266 "On systems that lack B<pselect>(), reliable (and more portable) signal "
3267 "trapping can be achieved using the self-pipe trick (where a signal handler "
3268 "writes a byte to a pipe whose other end is monitored by B<select>() in the "
3272 #. Stevens discusses a case where accept can block after select
3273 #. returns successfully because of an intervening RST from the client.
3274 #. Maybe the kernel should have returned EIO in such a situation?
3276 #: build/C/man2/select.2:469
3278 "Under Linux, B<select>() may report a socket file descriptor as \"ready for "
3279 "reading\", while nevertheless a subsequent read blocks. This could for "
3280 "example happen when data has arrived but upon examination has wrong checksum "
3281 "and is discarded. There may be other circumstances in which a file "
3282 "descriptor is spuriously reported as ready. Thus it may be safer to use "
3283 "B<O_NONBLOCK> on sockets that should not block."
3287 #: build/C/man2/select.2:484
3289 "On Linux, B<select>() also modifies I<timeout> if the call is interrupted "
3290 "by a signal handler (i.e., the B<EINTR> error return). This is not "
3291 "permitted by POSIX.1-2001. The Linux B<pselect>() system call has the same "
3292 "behavior, but the glibc wrapper hides this behavior by internally copying "
3293 "the I<timeout> to a local variable and passing that variable to the system "
3298 #: build/C/man2/select.2:491
3301 "#include E<lt>stdio.hE<gt>\n"
3302 "#include E<lt>stdlib.hE<gt>\n"
3303 "#include E<lt>sys/time.hE<gt>\n"
3304 "#include E<lt>sys/types.hE<gt>\n"
3305 "#include E<lt>unistd.hE<gt>\n"
3309 #: build/C/man2/select.2:498
3316 " struct timeval tv;\n"
3321 #: build/C/man2/select.2:502
3324 " /* Watch stdin (fd 0) to see when it has input. */\n"
3325 " FD_ZERO(&rfds);\n"
3326 " FD_SET(0, &rfds);\n"
3330 #: build/C/man2/select.2:506
3333 " /* Wait up to five seconds. */\n"
3335 " tv.tv_usec = 0;\n"
3339 #: build/C/man2/select.2:509
3342 " retval = select(1, &rfds, NULL, NULL, &tv);\n"
3343 " /* Don't rely on the value of tv now! */\n"
3347 #: build/C/man2/select.2:517
3350 " if (retval == -1)\n"
3351 " perror(\"select()\");\n"
3352 " else if (retval)\n"
3353 " printf(\"Data is available now.\\en\");\n"
3354 " /* FD_ISSET(0, &rfds) will be true. */\n"
3356 " printf(\"No data within five seconds.\\en\");\n"
3360 #: build/C/man2/select.2:520
3363 " exit(EXIT_SUCCESS);\n"
3368 #: build/C/man2/select.2:524
3369 msgid "For a tutorial with discussion and examples, see B<select_tut>(2)."
3373 #: build/C/man2/select.2:536
3375 "For vaguely related stuff, see B<accept>(2), B<connect>(2), B<poll>(2), "
3376 "B<read>(2), B<recv>(2), B<send>(2), B<sigprocmask>(2), B<write>(2), "
3377 "B<epoll>(7), B<time>(7)"
3381 #: build/C/man2/select_tut.2:30
3387 #: build/C/man2/select_tut.2:30
3393 #: build/C/man2/select_tut.2:50
3396 "B<int select(int >I<nfds>B<, fd_set *>I<readfds>B<, fd_set "
3397 "*>I<writefds>B<,>\n"
3398 "B< fd_set *>I<exceptfds>B<, struct timeval *>I<utimeout>B<);>\n"
3402 #: build/C/man2/select_tut.2:64
3405 "B<int pselect(int >I<nfds>B<, fd_set *>I<readfds>B<, fd_set "
3406 "*>I<writefds>B<,>\n"
3407 "B< fd_set *>I<exceptfds>B<, const struct timespec "
3408 "*>I<ntimeout>B<,>\n"
3409 "B< const sigset_t *>I<sigmask>B<);>\n"
3413 #: build/C/man2/select_tut.2:81
3415 "B<select>() (or B<pselect>()) is used to efficiently monitor multiple file "
3416 "descriptors, to see if any of them is, or becomes, \"ready\"; that is, to "
3417 "see whether I/O becomes possible, or an \"exceptional condition\" has "
3418 "occurred on any of the descriptors."
3422 #: build/C/man2/select_tut.2:106
3424 "Its principal arguments are three \"sets\" of file descriptors: I<readfds>, "
3425 "I<writefds>, and I<exceptfds>. Each set is declared as type I<fd_set>, and "
3426 "its contents can be manipulated with the macros B<FD_CLR>(), B<FD_ISSET>(), "
3427 "B<FD_SET>(), and B<FD_ZERO>(). A newly declared set should first be cleared "
3428 "using B<FD_ZERO>(). B<select>() modifies the contents of the sets "
3429 "according to the rules described below; after calling B<select>() you can "
3430 "test if a file descriptor is still present in a set with the B<FD_ISSET>() "
3431 "macro. B<FD_ISSET>() returns nonzero if a specified file descriptor is "
3432 "present in a set and zero if it is not. B<FD_CLR>() removes a file "
3433 "descriptor from a set."
3437 #: build/C/man2/select_tut.2:106
3443 #: build/C/man2/select_tut.2:107
3449 #: build/C/man2/select_tut.2:116
3451 "This set is watched to see if data is available for reading from any of its "
3452 "file descriptors. After B<select>() has returned, I<readfds> will be "
3453 "cleared of all file descriptors except for those that are immediately "
3454 "available for reading."
3458 #: build/C/man2/select_tut.2:116
3464 #: build/C/man2/select_tut.2:125
3466 "This set is watched to see if there is space to write data to any of its "
3467 "file descriptors. After B<select>() has returned, I<writefds> will be "
3468 "cleared of all file descriptors except for those that are immediately "
3469 "available for writing."
3473 #: build/C/man2/select_tut.2:125
3475 msgid "I<exceptfds>"
3479 #: build/C/man2/select_tut.2:147
3481 "This set is watched for \"exceptional conditions\". In practice, only one "
3482 "such exceptional condition is common: the availability of I<out-of-band> "
3483 "(OOB) data for reading from a TCP socket. See B<recv>(2), B<send>(2), and "
3484 "B<tcp>(7) for more details about OOB data. (One other less common case "
3485 "where B<select>(2) indicates an exceptional condition occurs with "
3486 "pseudoterminals in packet mode; see B<tty_ioctl>(4).) After B<select>() "
3487 "has returned, I<exceptfds> will be cleared of all file descriptors except "
3488 "for those for which an exceptional condition has occurred."
3492 #: build/C/man2/select_tut.2:147
3498 #: build/C/man2/select_tut.2:154
3500 "This is an integer one more than the maximum of any file descriptor in any "
3501 "of the sets. In other words, while adding file descriptors to each of the "
3502 "sets, you must calculate the maximum integer value of all of them, then "
3503 "increment this value by one, and then pass this as I<nfds>."
3507 #: build/C/man2/select_tut.2:154
3513 #: build/C/man2/select_tut.2:167
3515 "This is the longest time B<select>() may wait before returning, even if "
3516 "nothing interesting happened. If this value is passed as NULL, then "
3517 "B<select>() blocks indefinitely waiting for a file descriptor to become "
3518 "ready. I<utimeout> can be set to zero seconds, which causes B<select>() to "
3519 "return immediately, with information about the readiness of file descriptors "
3520 "at the time of the call. The structure I<struct timeval> is defined as:"
3524 #: build/C/man2/select_tut.2:174
3527 "struct timeval {\n"
3528 " time_t tv_sec; /* seconds */\n"
3529 " long tv_usec; /* microseconds */\n"
3534 #: build/C/man2/select_tut.2:176
3540 #: build/C/man2/select_tut.2:185
3542 "This argument for B<pselect>() has the same meaning as I<utimeout>, but "
3543 "I<struct timespec> has nanosecond precision as follows:"
3547 #: build/C/man2/select_tut.2:192
3550 "struct timespec {\n"
3551 " long tv_sec; /* seconds */\n"
3552 " long tv_nsec; /* nanoseconds */\n"
3557 #: build/C/man2/select_tut.2:194
3563 #: build/C/man2/select_tut.2:211
3565 "This argument holds a set of signals that the kernel should unblock (i.e., "
3566 "remove from the signal mask of the calling thread), while the caller is "
3567 "blocked inside the B<pselect>() call (see B<sigaddset>(3) and "
3568 "B<sigprocmask>(2)). It may be NULL, in which case the call does not modify "
3569 "the signal mask on entry and exit to the function. In this case, "
3570 "B<pselect>() will then behave just like B<select>()."
3574 #: build/C/man2/select_tut.2:211
3576 msgid "Combining Signal and Data Events"
3580 #: build/C/man2/select_tut.2:255
3582 "B<pselect>() is useful if you are waiting for a signal as well as for file "
3583 "descriptor(s) to become ready for I/O. Programs that receive signals "
3584 "normally use the signal handler only to raise a global flag. The global "
3585 "flag will indicate that the event must be processed in the main loop of the "
3586 "program. A signal will cause the B<select>() (or B<pselect>()) call to "
3587 "return with I<errno> set to B<EINTR>. This behavior is essential so that "
3588 "signals can be processed in the main loop of the program, otherwise "
3589 "B<select>() would block indefinitely. Now, somewhere in the main loop will "
3590 "be a conditional to check the global flag. So we must ask: what if a signal "
3591 "arrives after the conditional, but before the B<select>() call? The answer "
3592 "is that B<select>() would block indefinitely, even though an event is "
3593 "actually pending. This race condition is solved by the B<pselect>() call. "
3594 "This call can be used to set the signal mask to a set of signals that are "
3595 "only to be received within the B<pselect>() call. For instance, let us say "
3596 "that the event in question was the exit of a child process. Before the "
3597 "start of the main loop, we would block B<SIGCHLD> using B<sigprocmask>(2). "
3598 "Our B<pselect>() call would enable B<SIGCHLD> by using an empty signal "
3599 "mask. Our program would look like:"
3603 #: build/C/man2/select_tut.2:258
3605 msgid "static volatile sig_atomic_t got_SIGCHLD = 0;\n"
3609 #: build/C/man2/select_tut.2:264
3613 "child_sig_handler(int sig)\n"
3615 " got_SIGCHLD = 1;\n"
3620 #: build/C/man2/select_tut.2:272
3624 "main(int argc, char *argv[])\n"
3626 " sigset_t sigmask, empty_mask;\n"
3627 " struct sigaction sa;\n"
3628 " fd_set readfds, writefds, exceptfds;\n"
3633 #: build/C/man2/select_tut.2:279
3636 " sigemptyset(&sigmask);\n"
3637 " sigaddset(&sigmask, SIGCHLD);\n"
3638 " if (sigprocmask(SIG_BLOCK, &sigmask, NULL) == -1) {\n"
3639 " perror(\"sigprocmask\");\n"
3640 " exit(EXIT_FAILURE);\n"
3645 #: build/C/man2/select_tut.2:287
3648 " sa.sa_flags = 0;\n"
3649 " sa.sa_handler = child_sig_handler;\n"
3650 " sigemptyset(&sa.sa_mask);\n"
3651 " if (sigaction(SIGCHLD, &sa, NULL) == -1) {\n"
3652 " perror(\"sigaction\");\n"
3653 " exit(EXIT_FAILURE);\n"
3658 #: build/C/man2/select_tut.2:289
3660 msgid " sigemptyset(&empty_mask);\n"
3664 #: build/C/man2/select_tut.2:293
3667 " for (;;) { /* main loop */\n"
3668 " /* Initialize readfds, writefds, and exceptfds\n"
3669 " before the pselect() call. (Code omitted.) */\n"
3673 #: build/C/man2/select_tut.2:299
3676 " r = pselect(nfds, &readfds, &writefds, &exceptfds,\n"
3677 " NULL, &empty_mask);\n"
3678 " if (r == -1 && errno != EINTR) {\n"
3679 " /* Handle error */\n"
3684 #: build/C/man2/select_tut.2:302
3687 " if (got_SIGCHLD) {\n"
3688 " got_SIGCHLD = 0;\n"
3692 #: build/C/man2/select_tut.2:306
3695 " /* Handle signalled event here; e.g., wait() for all\n"
3696 " terminated children. (Code omitted.) */\n"
3701 #: build/C/man2/select_tut.2:310
3704 " /* main body of program */\n"
3710 #: build/C/man2/select_tut.2:311
3716 #: build/C/man2/select_tut.2:332
3718 "So what is the point of B<select>()? Can't I just read and write to my "
3719 "descriptors whenever I want? The point of B<select>() is that it watches "
3720 "multiple descriptors at the same time and properly puts the process to sleep "
3721 "if there is no activity. UNIX programmers often find themselves in a "
3722 "position where they have to handle I/O from more than one file descriptor "
3723 "where the data flow may be intermittent. If you were to merely create a "
3724 "sequence of B<read>(2) and B<write>(2) calls, you would find that one of "
3725 "your calls may block waiting for data from/to a file descriptor, while "
3726 "another file descriptor is unused though ready for I/O. B<select>() "
3727 "efficiently copes with this situation."
3731 #: build/C/man2/select_tut.2:332
3737 #: build/C/man2/select_tut.2:345
3739 "Many people who try to use B<select>() come across behavior that is "
3740 "difficult to understand and produces nonportable or borderline results. For "
3741 "instance, the above program is carefully written not to block at any point, "
3742 "even though it does not set its file descriptors to nonblocking mode. It is "
3743 "easy to introduce subtle errors that will remove the advantage of using "
3744 "B<select>(), so here is a list of essentials to watch for when using "
3749 #: build/C/man2/select_tut.2:354
3751 "You should always try to use B<select>() without a timeout. Your program "
3752 "should have nothing to do if there is no data available. Code that depends "
3753 "on timeouts is not usually portable and is difficult to debug."
3757 #: build/C/man2/select_tut.2:358
3759 "The value I<nfds> must be properly calculated for efficiency as explained "
3764 #: build/C/man2/select_tut.2:365
3766 "No file descriptor must be added to any set if you do not intend to check "
3767 "its result after the B<select>() call, and respond appropriately. See next "
3772 #: build/C/man2/select_tut.2:371
3774 "After B<select>() returns, all file descriptors in all sets should be "
3775 "checked to see if they are ready."
3779 #: build/C/man2/select_tut.2:371
3785 #: build/C/man2/select_tut.2:386
3787 "The functions B<read>(2), B<recv>(2), B<write>(2), and B<send>(2) do I<not> "
3788 "necessarily read/write the full amount of data that you have requested. If "
3789 "they do read/write the full amount, it's because you have a low traffic load "
3790 "and a fast stream. This is not always going to be the case. You should "
3791 "cope with the case of your functions only managing to send or receive a "
3796 #: build/C/man2/select_tut.2:386
3802 #: build/C/man2/select_tut.2:394
3804 "Never read/write only in single bytes at a time unless you are really sure "
3805 "that you have a small amount of data to process. It is extremely "
3806 "inefficient not to read/write as much data as you can buffer each time. The "
3807 "buffers in the example below are 1024 bytes although they could easily be "
3812 #: build/C/man2/select_tut.2:394
3817 #. Nonetheless, you should still cope with these errors for completeness.
3819 #: build/C/man2/select_tut.2:416
3821 "The functions B<read>(2), B<recv>(2), B<write>(2), and B<send>(2) as well "
3822 "as the B<select>() call can return -1 with I<errno> set to B<EINTR>, or "
3823 "with I<errno> set to B<EAGAIN> (B<EWOULDBLOCK>). These results must be "
3824 "properly managed (not done properly above). If your program is not going to "
3825 "receive any signals, then it is unlikely you will get B<EINTR>. If your "
3826 "program does not set nonblocking I/O, you will not get B<EAGAIN>."
3830 #: build/C/man2/select_tut.2:416
3836 #: build/C/man2/select_tut.2:425
3838 "Never call B<read>(2), B<recv>(2), B<write>(2), or B<send>(2) with a buffer "
3843 #: build/C/man2/select_tut.2:425
3849 #: build/C/man2/select_tut.2:441
3851 "If the functions B<read>(2), B<recv>(2), B<write>(2), and B<send>(2) fail "
3852 "with errors other than those listed in B<7.>, or one of the input functions "
3853 "returns 0, indicating end of file, then you should I<not> pass that "
3854 "descriptor to B<select>() again. In the example below, I close the "
3855 "descriptor immediately, and then set it to -1 to prevent it being included "
3860 #: build/C/man2/select_tut.2:441
3866 #: build/C/man2/select_tut.2:448
3868 "The timeout value must be initialized with each new call to B<select>(), "
3869 "since some operating systems modify the structure. B<pselect>() however "
3870 "does not modify its timeout structure."
3874 #: build/C/man2/select_tut.2:448
3879 #. "I have heard" does not fill me with confidence, and doesn't
3880 #. belong in a man page, so I've commented this point out.
3883 #. I have heard that the Windows socket layer does not cope with OOB data
3885 #. It also does not cope with
3887 #. calls when no file descriptors are set at all.
3888 #. Having no file descriptors set is a useful
3889 #. way to sleep the process with subsecond precision by using the timeout.
3890 #. (See further on.)
3892 #: build/C/man2/select_tut.2:467
3894 "Since B<select>() modifies its file descriptor sets, if the call is being "
3895 "used in a loop, then the sets must be reinitialized before each call."
3899 #: build/C/man2/select_tut.2:467
3901 msgid "Usleep Emulation"
3905 #: build/C/man2/select_tut.2:474
3907 "On systems that do not have a B<usleep>(3) function, you can call "
3908 "B<select>() with a finite timeout and no file descriptors as follows:"
3912 #: build/C/man2/select_tut.2:480
3915 " struct timeval tv;\n"
3917 " tv.tv_usec = 200000; /* 0.2 seconds */\n"
3918 " select(0, NULL, NULL, NULL, &tv);\n"
3922 #: build/C/man2/select_tut.2:483
3923 msgid "This is only guaranteed to work on UNIX systems, however."
3927 #: build/C/man2/select_tut.2:488
3929 "On success, B<select>() returns the total number of file descriptors still "
3930 "present in the file descriptor sets."
3934 #: build/C/man2/select_tut.2:494
3936 "If B<select>() timed out, then the return value will be zero. The file "
3937 "descriptors set should be all empty (but may not be on some systems)."
3941 #: build/C/man2/select_tut.2:501
3943 "A return value of -1 indicates an error, with I<errno> being set "
3944 "appropriately. In the case of an error, the contents of the returned sets "
3945 "and the I<struct timeout> contents are undefined and should not be used. "
3946 "B<pselect>() however never modifies I<ntimeout>."
3950 #: build/C/man2/select_tut.2:510
3952 "Generally speaking, all operating systems that support sockets also support "
3953 "B<select>(). B<select>() can be used to solve many problems in a portable "
3954 "and efficient way that naive programmers try to solve in a more complicated "
3955 "manner using threads, forking, IPCs, signals, memory sharing, and so on."
3959 #: build/C/man2/select_tut.2:519
3961 "The B<poll>(2) system call has the same functionality as B<select>(), and "
3962 "is somewhat more efficient when monitoring sparse file descriptor sets. It "
3963 "is nowadays widely available, but historically was less portable than "
3968 #: build/C/man2/select_tut.2:527
3970 "The Linux-specific B<epoll>(7) API provides an interface that is more "
3971 "efficient than B<select>(2) and B<poll>(2) when monitoring large numbers "
3972 "of file descriptors."
3976 #: build/C/man2/select_tut.2:532
3978 "Here is an example that better demonstrates the true utility of "
3979 "B<select>(). The listing below is a TCP forwarding program that forwards "
3980 "from one TCP port to another."
3984 #: build/C/man2/select_tut.2:545
3987 "#include E<lt>stdlib.hE<gt>\n"
3988 "#include E<lt>stdio.hE<gt>\n"
3989 "#include E<lt>unistd.hE<gt>\n"
3990 "#include E<lt>sys/time.hE<gt>\n"
3991 "#include E<lt>sys/types.hE<gt>\n"
3992 "#include E<lt>string.hE<gt>\n"
3993 "#include E<lt>signal.hE<gt>\n"
3994 "#include E<lt>sys/socket.hE<gt>\n"
3995 "#include E<lt>netinet/in.hE<gt>\n"
3996 "#include E<lt>arpa/inet.hE<gt>\n"
3997 "#include E<lt>errno.hE<gt>\n"
4001 #: build/C/man2/select_tut.2:547
4003 msgid "static int forward_port;\n"
4007 #: build/C/man2/select_tut.2:550
4011 "#define max(x,y) ((x) E<gt> (y) ? (x) : (y))\n"
4015 #: build/C/man2/select_tut.2:557
4019 "listen_socket(int listen_port)\n"
4021 " struct sockaddr_in a;\n"
4027 #: build/C/man2/select_tut.2:581
4030 " if ((s = socket(AF_INET, SOCK_STREAM, 0)) == -1) {\n"
4031 " perror(\"socket\");\n"
4035 " if (setsockopt(s, SOL_SOCKET, SO_REUSEADDR,\n"
4036 " (char *) &yes, sizeof(yes)) == -1) {\n"
4037 " perror(\"setsockopt\");\n"
4041 " memset(&a, 0, sizeof(a));\n"
4042 " a.sin_port = htons(listen_port);\n"
4043 " a.sin_family = AF_INET;\n"
4044 " if (bind(s, (struct sockaddr *) &a, sizeof(a)) == -1) {\n"
4045 " perror(\"bind\");\n"
4049 " printf(\"accepting connections on port %d\\en\", listen_port);\n"
4056 #: build/C/man2/select_tut.2:587
4060 "connect_socket(int connect_port, char *address)\n"
4062 " struct sockaddr_in a;\n"
4067 #: build/C/man2/select_tut.2:593
4070 " if ((s = socket(AF_INET, SOCK_STREAM, 0)) == -1) {\n"
4071 " perror(\"socket\");\n"
4078 #: build/C/man2/select_tut.2:597
4081 " memset(&a, 0, sizeof(a));\n"
4082 " a.sin_port = htons(connect_port);\n"
4083 " a.sin_family = AF_INET;\n"
4087 #: build/C/man2/select_tut.2:603
4090 " if (!inet_aton(address, (struct in_addr *) &a.sin_addr.s_addr)) {\n"
4091 " perror(\"bad IP address format\");\n"
4098 #: build/C/man2/select_tut.2:612
4101 " if (connect(s, (struct sockaddr *) &a, sizeof(a)) == -1) {\n"
4102 " perror(\"connect()\");\n"
4103 " shutdown(s, SHUT_RDWR);\n"
4112 #: build/C/man2/select_tut.2:620
4115 "#define SHUT_FD1 do { \\e\n"
4116 " if (fd1 E<gt>= 0) { \\e\n"
4117 " shutdown(fd1, SHUT_RDWR); \\e\n"
4118 " close(fd1); \\e\n"
4125 #: build/C/man2/select_tut.2:628
4128 "#define SHUT_FD2 do { \\e\n"
4129 " if (fd2 E<gt>= 0) { \\e\n"
4130 " shutdown(fd2, SHUT_RDWR); \\e\n"
4131 " close(fd2); \\e\n"
4138 #: build/C/man2/select_tut.2:630
4140 msgid "#define BUF_SIZE 1024\n"
4144 #: build/C/man2/select_tut.2:639
4148 "main(int argc, char *argv[])\n"
4151 " int fd1 = -1, fd2 = -1;\n"
4152 " char buf1[BUF_SIZE], buf2[BUF_SIZE];\n"
4153 " int buf1_avail, buf1_written;\n"
4154 " int buf2_avail, buf2_written;\n"
4158 #: build/C/man2/select_tut.2:645
4161 " if (argc != 4) {\n"
4162 " fprintf(stderr, \"Usage\\en\\etfwd E<lt>listen-portE<gt> \"\n"
4163 " \"E<lt>forward-to-portE<gt> "
4164 "E<lt>forward-to-ip-addressE<gt>\\en\");\n"
4165 " exit(EXIT_FAILURE);\n"
4170 #: build/C/man2/select_tut.2:647
4172 msgid " signal(SIGPIPE, SIG_IGN);\n"
4176 #: build/C/man2/select_tut.2:649
4178 msgid " forward_port = atoi(argv[2]);\n"
4182 #: build/C/man2/select_tut.2:653
4185 " h = listen_socket(atoi(argv[1]));\n"
4187 " exit(EXIT_FAILURE);\n"
4191 #: build/C/man2/select_tut.2:657
4195 " int r, nfds = 0;\n"
4196 " fd_set rd, wr, er;\n"
4200 #: build/C/man2/select_tut.2:687
4206 " FD_SET(h, &rd);\n"
4207 " nfds = max(nfds, h);\n"
4208 " if (fd1 E<gt> 0 && buf1_avail E<lt> BUF_SIZE) {\n"
4209 " FD_SET(fd1, &rd);\n"
4210 " nfds = max(nfds, fd1);\n"
4212 " if (fd2 E<gt> 0 && buf2_avail E<lt> BUF_SIZE) {\n"
4213 " FD_SET(fd2, &rd);\n"
4214 " nfds = max(nfds, fd2);\n"
4216 " if (fd1 E<gt> 0 && buf2_avail - buf2_written E<gt> 0) {\n"
4217 " FD_SET(fd1, &wr);\n"
4218 " nfds = max(nfds, fd1);\n"
4220 " if (fd2 E<gt> 0 && buf1_avail - buf1_written E<gt> 0) {\n"
4221 " FD_SET(fd2, &wr);\n"
4222 " nfds = max(nfds, fd2);\n"
4224 " if (fd1 E<gt> 0) {\n"
4225 " FD_SET(fd1, &er);\n"
4226 " nfds = max(nfds, fd1);\n"
4228 " if (fd2 E<gt> 0) {\n"
4229 " FD_SET(fd2, &er);\n"
4230 " nfds = max(nfds, fd2);\n"
4235 #: build/C/man2/select_tut.2:689
4237 msgid " r = select(nfds + 1, &rd, &wr, &er, NULL);\n"
4241 #: build/C/man2/select_tut.2:692
4244 " if (r == -1 && errno == EINTR)\n"
4249 #: build/C/man2/select_tut.2:697
4253 " perror(\"select()\");\n"
4254 " exit(EXIT_FAILURE);\n"
4259 #: build/C/man2/select_tut.2:701
4262 " if (FD_ISSET(h, &rd)) {\n"
4263 " unsigned int l;\n"
4264 " struct sockaddr_in client_address;\n"
4268 #: build/C/man2/select_tut.2:720
4271 " memset(&client_address, 0, l = sizeof(client_address));\n"
4272 " r = accept(h, (struct sockaddr *) &client_address, &l);\n"
4274 " perror(\"accept()\");\n"
4278 " buf1_avail = buf1_written = 0;\n"
4279 " buf2_avail = buf2_written = 0;\n"
4281 " fd2 = connect_socket(forward_port, argv[3]);\n"
4285 " printf(\"connect from %s\\en\",\n"
4286 " inet_ntoa(client_address.sin_addr));\n"
4292 #: build/C/man2/select_tut.2:722
4294 msgid " /* NB: read oob data before normal reads */\n"
4298 #: build/C/man2/select_tut.2:726
4301 " if (fd1 E<gt> 0)\n"
4302 " if (FD_ISSET(fd1, &er)) {\n"
4307 #: build/C/man2/select_tut.2:736
4310 " r = recv(fd1, &c, 1, MSG_OOB);\n"
4314 " send(fd2, &c, 1, MSG_OOB);\n"
4316 " if (fd2 E<gt> 0)\n"
4317 " if (FD_ISSET(fd2, &er)) {\n"
4322 #: build/C/man2/select_tut.2:779
4325 " r = recv(fd2, &c, 1, MSG_OOB);\n"
4329 " send(fd1, &c, 1, MSG_OOB);\n"
4331 " if (fd1 E<gt> 0)\n"
4332 " if (FD_ISSET(fd1, &rd)) {\n"
4333 " r = read(fd1, buf1 + buf1_avail,\n"
4334 " BUF_SIZE - buf1_avail);\n"
4338 " buf1_avail += r;\n"
4340 " if (fd2 E<gt> 0)\n"
4341 " if (FD_ISSET(fd2, &rd)) {\n"
4342 " r = read(fd2, buf2 + buf2_avail,\n"
4343 " BUF_SIZE - buf2_avail);\n"
4347 " buf2_avail += r;\n"
4349 " if (fd1 E<gt> 0)\n"
4350 " if (FD_ISSET(fd1, &wr)) {\n"
4351 " r = write(fd1, buf2 + buf2_written,\n"
4352 " buf2_avail - buf2_written);\n"
4356 " buf2_written += r;\n"
4358 " if (fd2 E<gt> 0)\n"
4359 " if (FD_ISSET(fd2, &wr)) {\n"
4360 " r = write(fd2, buf1 + buf1_written,\n"
4361 " buf1_avail - buf1_written);\n"
4365 " buf1_written += r;\n"
4370 #: build/C/man2/select_tut.2:781
4372 msgid " /* check if write data has caught read data */\n"
4376 #: build/C/man2/select_tut.2:786
4379 " if (buf1_written == buf1_avail)\n"
4380 " buf1_written = buf1_avail = 0;\n"
4381 " if (buf2_written == buf2_avail)\n"
4382 " buf2_written = buf2_avail = 0;\n"
4386 #: build/C/man2/select_tut.2:789
4389 " /* one side has closed the connection, keep\n"
4390 " writing to the other side until empty */\n"
4394 #: build/C/man2/select_tut.2:797
4397 " if (fd1 E<lt> 0 && buf1_avail - buf1_written == 0)\n"
4399 " if (fd2 E<lt> 0 && buf2_avail - buf2_written == 0)\n"
4402 " exit(EXIT_SUCCESS);\n"
4407 #: build/C/man2/select_tut.2:811
4409 "The above program properly forwards most kinds of TCP connections including "
4410 "OOB signal data transmitted by B<telnet> servers. It handles the tricky "
4411 "problem of having data flow in both directions simultaneously. You might "
4412 "think it more efficient to use a B<fork>(2) call and devote a thread to "
4413 "each stream. This becomes more tricky than you might suspect. Another idea "
4414 "is to set nonblocking I/O using B<fcntl>(2). This also has its problems "
4415 "because you end up using inefficient timeouts."
4419 #: build/C/man2/select_tut.2:817
4421 "The program does not handle more than one simultaneous connection at a time, "
4422 "although it could easily be extended to do this with a linked list of "
4423 "buffers\\(emone for each connection. At the moment, new connections cause "
4424 "the current connection to be dropped."
4428 #. This man page was written by Paul Sheer.
4430 #: build/C/man2/select_tut.2:836
4432 "B<accept>(2), B<connect>(2), B<ioctl>(2), B<poll>(2), B<read>(2), "
4433 "B<recv>(2), B<select>(2), B<send>(2), B<sigprocmask>(2), B<write>(2), "
4434 "B<sigaddset>(3), B<sigdelset>(3), B<sigemptyset>(3), B<sigfillset>(3), "
4435 "B<sigismember>(3), B<epoll>(7)"
4439 #: build/C/man2/send.2:38
4445 #: build/C/man2/send.2:38 build/C/man7/socket.7:26
4451 #: build/C/man2/send.2:41
4452 msgid "send, sendto, sendmsg - send a message on a socket"
4456 #: build/C/man2/send.2:45
4459 "B<#include E<lt>sys/types.hE<gt>>\n"
4460 "B<#include E<lt>sys/socket.hE<gt>>\n"
4464 #: build/C/man2/send.2:48
4467 "B<ssize_t send(int >I<sockfd>B<, const void *>I<buf>B<, size_t >I<len>B<, "
4468 "int >I<flags>B<);>\n"
4472 #: build/C/man2/send.2:52
4475 "B<ssize_t sendto(int >I<sockfd>B<, const void *>I<buf>B<, size_t >I<len>B<, "
4476 "int >I<flags>B<,>\n"
4477 "B< const struct sockaddr *>I<dest_addr>B<, socklen_t "
4478 ">I<addrlen>B<);>\n"
4482 #: build/C/man2/send.2:55
4485 "B<ssize_t sendmsg(int >I<sockfd>B<, const struct msghdr *>I<msg>B<, int "
4490 #: build/C/man2/send.2:63
4492 "The system calls B<send>(), B<sendto>(), and B<sendmsg>() are used to "
4493 "transmit a message to another socket."
4497 #: build/C/man2/send.2:82
4499 "The B<send>() call may be used only when the socket is in a I<connected> "
4500 "state (so that the intended recipient is known). The only difference "
4501 "between B<send>() and B<write>(2) is the presence of I<flags>. With a "
4502 "zero I<flags> argument, B<send>() is equivalent to B<write>(2). Also, the "
4507 #: build/C/man2/send.2:84
4509 msgid " send(sockfd, buf, len, flags);\n"
4513 #: build/C/man2/send.2:86
4514 msgid "is equivalent to"
4518 #: build/C/man2/send.2:88
4520 msgid " sendto(sockfd, buf, len, flags, NULL, 0);\n"
4524 #: build/C/man2/send.2:92
4525 msgid "The argument I<sockfd> is the file descriptor of the sending socket."
4529 #: build/C/man2/send.2:120
4531 "If B<sendto>() is used on a connection-mode (B<SOCK_STREAM>, "
4532 "B<SOCK_SEQPACKET>) socket, the arguments I<dest_addr> and I<addrlen> are "
4533 "ignored (and the error B<EISCONN> may be returned when they are not NULL and "
4534 "0), and the error B<ENOTCONN> is returned when the socket was not actually "
4535 "connected. Otherwise, the address of the target is given by I<dest_addr> "
4536 "with I<addrlen> specifying its size. For B<sendmsg>(), the address of the "
4537 "target is given by I<msg.msg_name>, with I<msg.msg_namelen> specifying its "
4542 #: build/C/man2/send.2:136
4544 "For B<send>() and B<sendto>(), the message is found in I<buf> and has "
4545 "length I<len>. For B<sendmsg>(), the message is pointed to by the elements "
4546 "of the array I<msg.msg_iov>. The B<sendmsg>() call also allows sending "
4547 "ancillary data (also known as control information)."
4551 #: build/C/man2/send.2:141
4553 "If the message is too long to pass atomically through the underlying "
4554 "protocol, the error B<EMSGSIZE> is returned, and the message is not "
4559 #: build/C/man2/send.2:145
4561 "No indication of failure to deliver is implicit in a B<send>(). Locally "
4562 "detected errors are indicated by a return value of -1."
4566 #: build/C/man2/send.2:158
4568 "When the message does not fit into the send buffer of the socket, B<send>() "
4569 "normally blocks, unless the socket has been placed in nonblocking I/O mode. "
4570 "In nonblocking mode it would fail with the error B<EAGAIN> or B<EWOULDBLOCK> "
4571 "in this case. The B<select>(2) call may be used to determine when it is "
4572 "possible to send more data."
4575 #. FIXME ? document MSG_PROXY (which went away in 2.3.15)
4577 #: build/C/man2/send.2:164
4579 "The I<flags> argument is the bitwise OR of zero or more of the following "
4584 #: build/C/man2/send.2:164
4586 msgid "B<MSG_CONFIRM> (Since Linux 2.3.15)"
4590 #: build/C/man2/send.2:178
4592 "Tell the link layer that forward progress happened: you got a successful "
4593 "reply from the other side. If the link layer doesn't get this it will "
4594 "regularly reprobe the neighbor (e.g., via a unicast ARP). Only valid on "
4595 "B<SOCK_DGRAM> and B<SOCK_RAW> sockets and currently only implemented for "
4596 "IPv4 and IPv6. See B<arp>(7) for details."
4600 #: build/C/man2/send.2:178
4602 msgid "B<MSG_DONTROUTE>"
4606 #: build/C/man2/send.2:186
4608 "Don't use a gateway to send out the packet, only send to hosts on directly "
4609 "connected networks. This is usually used only by diagnostic or routing "
4610 "programs. This is only defined for protocol families that route; packet "
4615 #: build/C/man2/send.2:197
4617 "Enables nonblocking operation; if the operation would block, B<EAGAIN> or "
4618 "B<EWOULDBLOCK> is returned (this can also be enabled using the B<O_NONBLOCK> "
4619 "flag with the B<F_SETFL> B<fcntl>(2))."
4623 #: build/C/man2/send.2:197
4625 msgid "B<MSG_EOR> (since Linux 2.2)"
4629 #: build/C/man2/send.2:201
4631 "Terminates a record (when this notion is supported, as for sockets of type "
4632 "B<SOCK_SEQPACKET>)."
4636 #: build/C/man2/send.2:201
4638 msgid "B<MSG_MORE> (Since Linux 2.4.4)"
4642 #: build/C/man2/send.2:210
4644 "The caller has more data to send. This flag is used with TCP sockets to "
4645 "obtain the same effect as the B<TCP_CORK> socket option (see B<tcp>(7)), "
4646 "with the difference that this flag can be set on a per-call basis."
4650 #: build/C/man2/send.2:219
4652 "Since Linux 2.6, this flag is also supported for UDP sockets, and informs "
4653 "the kernel to package all of the data sent in calls with this flag set into "
4654 "a single datagram which is only transmitted when a call is performed that "
4655 "does not specify this flag. (See also the B<UDP_CORK> socket option "
4656 "described in B<udp>(7).)"
4660 #: build/C/man2/send.2:219
4662 msgid "B<MSG_NOSIGNAL> (since Linux 2.2)"
4666 #: build/C/man2/send.2:228
4668 "Requests not to send B<SIGPIPE> on errors on stream oriented sockets when "
4669 "the other end breaks the connection. The B<EPIPE> error is still returned."
4673 #: build/C/man2/send.2:237
4675 "Sends I<out-of-band> data on sockets that support this notion (e.g., of type "
4676 "B<SOCK_STREAM>); the underlying protocol must also support I<out-of-band> "
4681 #: build/C/man2/send.2:244
4683 "The definition of the I<msghdr> structure follows. See B<recv>(2) and "
4684 "below for an exact description of its fields."
4687 #. Still to be documented:
4688 #. Send file descriptors and user credentials using the
4689 #. msg_control* fields.
4690 #. The flags returned in msg_flags.
4692 #: build/C/man2/send.2:273
4694 "You may send control information using the I<msg_control> and "
4695 "I<msg_controllen> members. The maximum control buffer length the kernel can "
4696 "process is limited per socket by the value in "
4697 "I</proc/sys/net/core/optmem_max>; see B<socket>(7)."
4701 #: build/C/man2/send.2:278
4703 "On success, these calls return the number of characters sent. On error, -1 "
4704 "is returned, and I<errno> is set appropriately."
4708 #: build/C/man2/send.2:283
4710 "These are some standard errors generated by the socket layer. Additional "
4711 "errors may be generated and returned from the underlying protocol modules; "
4712 "see their respective manual pages."
4716 #: build/C/man2/send.2:291
4718 "(For UNIX domain sockets, which are identified by pathname) Write "
4719 "permission is denied on the destination socket file, or search permission is "
4720 "denied for one of the directories the path prefix. (See "
4721 "B<path_resolution>(7).)"
4725 #: build/C/man2/send.2:294
4727 "(For UDP sockets) An attempt was made to send to a network/broadcast address "
4728 "as though it was a unicast address."
4731 #. Actually EAGAIN on Linux
4733 #: build/C/man2/send.2:302
4735 "The socket is marked nonblocking and the requested operation would block. "
4736 "POSIX.1-2001 allows either error to be returned for this case, and does not "
4737 "require these constants to have the same value, so a portable application "
4738 "should check for both possibilities."
4742 #: build/C/man2/send.2:305
4743 msgid "An invalid descriptor was specified."
4747 #: build/C/man2/send.2:305
4749 msgid "B<ECONNRESET>"
4753 #: build/C/man2/send.2:308
4754 msgid "Connection reset by peer."
4758 #: build/C/man2/send.2:308
4760 msgid "B<EDESTADDRREQ>"
4764 #: build/C/man2/send.2:311
4765 msgid "The socket is not connection-mode, and no peer address is set."
4769 #: build/C/man2/send.2:314
4770 msgid "An invalid user space address was specified for an argument."
4774 #: build/C/man2/send.2:318
4775 msgid "A signal occurred before any data was transmitted; see B<signal>(7)."
4779 #: build/C/man2/send.2:327
4781 "The connection-mode socket was connected already but a recipient was "
4782 "specified. (Now either this error is returned, or the recipient "
4783 "specification is ignored.)"
4787 #: build/C/man2/send.2:327
4792 #. (e.g., SOCK_DGRAM )
4794 #: build/C/man2/send.2:333
4796 "The socket type requires that message be sent atomically, and the size of "
4797 "the message to be sent made this impossible."
4801 #: build/C/man2/send.2:341
4803 "The output queue for a network interface was full. This generally indicates "
4804 "that the interface has stopped sending, but may be caused by transient "
4805 "congestion. (Normally, this does not occur in Linux. Packets are just "
4806 "silently dropped when a device queue overflows.)"
4810 #: build/C/man2/send.2:344
4811 msgid "No memory available."
4815 #: build/C/man2/send.2:347
4816 msgid "The socket is not connected, and no target has been given."
4820 #: build/C/man2/send.2:357
4821 msgid "Some bit in the I<flags> argument is inappropriate for the socket type."
4825 #: build/C/man2/send.2:357
4831 #: build/C/man2/send.2:366
4833 "The local end has been shut down on a connection oriented socket. In this "
4834 "case the process will also receive a B<SIGPIPE> unless B<MSG_NOSIGNAL> is "
4839 #: build/C/man2/send.2:369
4840 msgid "4.4BSD, SVr4, POSIX.1-2001. These function calls appeared in 4.2BSD."
4844 #: build/C/man2/send.2:380
4846 "POSIX.1-2001 only describes the B<MSG_OOB> and B<MSG_EOR> flags. "
4847 "POSIX.1-2008 adds a specification of B<MSG_NOSIGNAL>. The B<MSG_CONFIRM> "
4848 "flag is a Linux extension."
4852 #: build/C/man2/send.2:393
4854 "The prototypes given above follow the Single UNIX Specification, as glibc2 "
4855 "also does; the I<flags> argument was I<int> in 4.x BSD, but I<unsigned int> "
4856 "in libc4 and libc5; the I<len> argument was I<int> in 4.x BSD and libc4, but "
4857 "I<size_t> in libc5; the I<addrlen> argument was I<int> in 4.x BSD and libc4 "
4858 "and libc5. See also B<accept>(2)."
4862 #: build/C/man2/send.2:412
4864 "See B<sendmmsg(2)> for information about a Linux-specific system call that "
4865 "can be used to transmit multiple datagrams in a single call."
4869 #: build/C/man2/send.2:417
4870 msgid "Linux may return B<EPIPE> instead of B<ENOTCONN>."
4874 #: build/C/man2/send.2:422
4875 msgid "An example of the use of B<sendto>() is shown in B<getaddrinfo>(3)."
4879 #: build/C/man2/send.2:437
4881 "B<fcntl>(2), B<getsockopt>(2), B<recv>(2), B<select>(2), B<sendfile>(2), "
4882 "B<sendmmsg>(2), B<shutdown>(2), B<socket>(2), B<write>(2), B<cmsg>(3), "
4883 "B<ip>(7), B<socket>(7), B<tcp>(7), B<udp>(7)"
4887 #: build/C/man2/sendmmsg.2:28
4893 #: build/C/man2/sendmmsg.2:28
4899 #: build/C/man2/sendmmsg.2:31
4900 msgid "sendmmsg - send multiple messages on a socket"
4904 #: build/C/man2/sendmmsg.2:39
4907 "B<int sendmmsg(int >I<sockfd>B<, struct mmsghdr *>I<msgvec>B<, unsigned int "
4909 "B< unsigned int >I<flags>B<);>\n"
4912 #. See commit 228e548e602061b08ee8e8966f567c12aa079682
4914 #: build/C/man2/sendmmsg.2:49
4916 "The B<sendmmsg>() system call is an extension of B<sendmsg>(2) that allows "
4917 "the caller to transmit multiple messages on a socket using a single system "
4918 "call. (This has performance benefits for some applications.)"
4922 #: build/C/man2/sendmmsg.2:54
4924 "The I<sockfd> argument is the file descriptor of the socket on which data is "
4925 "to be transmitted."
4929 #: build/C/man2/sendmmsg.2:75
4932 "struct mmsghdr {\n"
4933 " struct msghdr msg_hdr; /* Message header */\n"
4934 " unsigned int msg_len; /* Number of bytes transmitted */\n"
4939 #: build/C/man2/sendmmsg.2:91
4941 "The I<msg_hdr> field is a I<msghdr> structure, as described in "
4942 "B<sendmsg>(2). The I<msg_len> field is used to return the number of bytes "
4943 "sent from the message in I<msg_hdr> (i.e., the same as the return value from "
4944 "a single B<sendmsg>(2) call)."
4948 #: build/C/man2/sendmmsg.2:97
4950 "The I<flags> argument contains flags ORed together. The flags are the same "
4951 "as for B<sendmsg>(2)."
4955 #: build/C/man2/sendmmsg.2:107
4957 "A blocking B<sendmmsg>() call blocks until I<vlen> messages have been "
4958 "sent. A nonblocking call sends as many messages as possible (up to the "
4959 "limit specified by I<vlen>) and returns immediately."
4963 #: build/C/man2/sendmmsg.2:119
4965 "On return from B<sendmmsg>(), the I<msg_len> fields of successive elements "
4966 "of I<msgvec> are updated to contain the number of bytes transmitted from the "
4967 "corresponding I<msg_hdr>. The return value of the call indicates the number "
4968 "of elements of I<msgvec> that have been updated."
4972 #: build/C/man2/sendmmsg.2:129
4974 "On success, B<sendmmsg>() returns the number of messages sent from "
4975 "I<msgvec>; if this is less than I<vlen>, the caller can retry with a further "
4976 "B<sendmmsg>() call to send the remaining messages."
4980 #: build/C/man2/sendmmsg.2:133
4981 msgid "On error, -1 is returned, and I<errno> is set to indicate the error."
4984 #. commit 728ffb86f10873aaf4abd26dde691ee40ae731fe
4985 #. ... only return an error if no datagrams could be sent.
4986 #. If less than the requested number of messages were sent, the application
4987 #. must retry starting at the first failed one and if the problem is
4988 #. persistent the error will be returned.
4990 #. This matches the behaviour of other syscalls like read/write - it
4991 #. is not an error if less than the requested number of elements are sent.
4993 #: build/C/man2/sendmmsg.2:145
4995 "Errors are as for B<sendmsg>(2). An error is returned only if no datagrams "
5000 #: build/C/man2/sendmmsg.2:150
5002 "The B<sendmmsg>() system call was added in Linux 3.0. Support in glibc was "
5003 "added in version 2.14."
5007 #: build/C/man2/sendmmsg.2:153
5008 msgid "B<sendmmsg>() is Linux-specific."
5011 #. commit 98382f419f32d2c12d021943b87dea555677144b
5012 #. net: Cap number of elements for sendmmsg
5014 #. To limit the amount of time we can spend in sendmmsg, cap the
5015 #. number of elements to UIO_MAXIOV (currently 1024).
5017 #. For error handling an application using sendmmsg needs to retry at
5018 #. the first unsent message, so capping is simpler and requires less
5019 #. application logic than returning EINVAL.
5021 #: build/C/man2/sendmmsg.2:168
5022 msgid "The value specified in I<vlen> is capped to B<UIO_MAXIOV> (1024)."
5026 #: build/C/man2/sendmmsg.2:173
5027 msgid "B<recvmmsg>(2), B<sendmsg>(2), B<socket>(2), B<socket>(7)"
5031 #: build/C/man3/sockatmark.3:23
5037 #: build/C/man3/sockatmark.3:26
5038 msgid "sockatmark - determine whether socket is at out-of-band mark"
5042 #: build/C/man3/sockatmark.3:28 build/C/man2/socket.2:48 build/C/man7/socket.7:31 build/C/man2/socketpair.2:47
5043 msgid "B<#include E<lt>sys/socket.hE<gt>>"
5047 #: build/C/man3/sockatmark.3:30
5048 msgid "B<int sockatmark(int >I<sockfd>B<);>"
5052 #: build/C/man3/sockatmark.3:39
5054 "B<sockatmark>(): _POSIX_C_SOURCE\\ E<gt>=\\ 200112L || _XOPEN_SOURCE\\ "
5059 #: build/C/man3/sockatmark.3:49
5061 "B<sockatmark>() returns a value indicating whether or not the socket "
5062 "referred to by the file descriptor I<sockfd> is at the out-of-band mark. If "
5063 "the socket is at the mark, then 1 is returned; if the socket is not at the "
5064 "mark, 0 is returned. This function does not remove the out-of-band mark."
5068 #: build/C/man3/sockatmark.3:54
5070 "A successful call to B<sockatmark>() returns 1 if the socket is at the "
5071 "out-of-band mark, or 0 if it is not. On error, -1 is returned and I<errno> "
5072 "is set to indicate the error."
5076 #: build/C/man3/sockatmark.3:59
5077 msgid "I<sockfd> is not a valid file descriptor."
5080 #. POSIX.1 says ENOTTY for this case
5082 #: build/C/man3/sockatmark.3:66
5083 msgid "I<sockfd> is not a file descriptor to which B<sockatmark>() can be applied."
5087 #: build/C/man3/sockatmark.3:69
5088 msgid "B<sockatmark>() was added to glibc in version 2.2.4."
5092 #: build/C/man3/sockatmark.3:71
5093 msgid "POSIX.1-2001."
5097 #: build/C/man3/sockatmark.3:78
5099 "If B<sockatmark>() returns 1, then the out-of-band data can be read using "
5100 "the B<MSG_OOB> flag of B<recv>(2)."
5104 #: build/C/man3/sockatmark.3:80
5105 msgid "Out-of-band data is only supported on some stream socket protocols."
5109 #: build/C/man3/sockatmark.3:85
5111 "B<sockatmark>() can safely be called from a handler for the B<SIGURG> "
5116 #: build/C/man3/sockatmark.3:91
5118 "B<sockatmark>() is implemented using the B<SIOCATMARK> B<ioctl>(2) "
5123 #: build/C/man3/sockatmark.3:95
5124 msgid "Prior to glibc 2.4, B<sockatmark>() did not work."
5128 #: build/C/man3/sockatmark.3:100
5130 "The following code can be used after receipt of a B<SIGURG> signal to read "
5131 "(and discard) all data up to the mark, and then read the byte of data at the "
5136 #: build/C/man3/sockatmark.3:105
5139 " char buf[BUF_LEN];\n"
5145 #: build/C/man3/sockatmark.3:112
5149 " atmark = sockatmark(sockfd);\n"
5150 " if (atmark == -1) {\n"
5151 " perror(\"sockatmark\");\n"
5157 #: build/C/man3/sockatmark.3:115
5165 #: build/C/man3/sockatmark.3:122
5168 " s = read(sockfd, buf, BUF_LEN) E<lt>= 0);\n"
5170 " perror(\"read\");\n"
5171 " if (s E<lt>= 0)\n"
5177 #: build/C/man3/sockatmark.3:129
5180 " if (atmark == 1) {\n"
5181 " if (recv(sockfd, &oobdata, 1, MSG_OOB) == -1) {\n"
5182 " perror(\"recv\");\n"
5189 #: build/C/man3/sockatmark.3:135
5190 msgid "B<fcntl>(2), B<recv>(2), B<send>(2), B<tcp>(7)"
5194 #: build/C/man2/socket.2:41 build/C/man7/socket.7:26
5200 #: build/C/man2/socket.2:41
5206 #: build/C/man2/socket.2:44
5207 msgid "socket - create an endpoint for communication"
5211 #: build/C/man2/socket.2:46 build/C/man2/socketpair.2:45
5212 msgid "B<#include E<lt>sys/types.hE<gt>> /* See NOTES */"
5216 #: build/C/man2/socket.2:50
5217 msgid "B<int socket(int >I<domain>B<, int >I<type>B<, int >I<protocol>B<);>"
5221 #: build/C/man2/socket.2:53
5222 msgid "B<socket>() creates an endpoint for communication and returns a descriptor."
5226 #: build/C/man2/socket.2:61
5228 "The I<domain> argument specifies a communication domain; this selects the "
5229 "protocol family which will be used for communication. These families are "
5230 "defined in I<E<lt>sys/socket.hE<gt>>. The currently understood formats "
5235 #: build/C/man2/socket.2:64
5237 msgid "Name:Purpose:Man page\n"
5241 #: build/C/man2/socket.2:65 build/C/man2/socket.2:72 build/C/man2/socket.2:77 build/C/man2/socket.2:82 build/C/man2/socket.2:85 build/C/man2/socket.2:92 build/C/man2/socket.2:97 build/C/man2/socket.2:102 build/C/man2/socket.2:105 build/C/man2/socket.2:110
5247 #: build/C/man2/socket.2:66
5249 msgid "B<AF_UNIX>, B<AF_LOCAL>\n"
5253 #: build/C/man2/socket.2:67 build/C/man2/socket.2:69 build/C/man2/socket.2:87 build/C/man2/socket.2:89 build/C/man2/socket.2:99 build/C/man2/socket.2:112 build/C/man2/socket.2:114 build/C/man7/socket.7:162
5259 #: build/C/man2/socket.2:68
5261 msgid "Local communication\n"
5265 #: build/C/man2/socket.2:70
5267 msgid "B<unix>(7)\n"
5271 #: build/C/man2/socket.2:71 build/C/man2/socket.2:76 build/C/man2/socket.2:81 build/C/man2/socket.2:91 build/C/man2/socket.2:96 build/C/man2/socket.2:109 build/C/man2/socket.2:116 build/C/man7/socket.7:141 build/C/man7/socket.7:145 build/C/man7/socket.7:148 build/C/man7/socket.7:154 build/C/man7/socket.7:157 build/C/man7/socket.7:166 build/C/man7/socket.7:173
5277 #: build/C/man2/socket.2:73
5279 msgid "B<AF_INET>\n"
5283 #: build/C/man2/socket.2:74
5285 msgid "T}:IPv4 Internet protocols:T{\n"
5289 #: build/C/man2/socket.2:75
5295 #: build/C/man2/socket.2:78
5297 msgid "B<AF_INET6>\n"
5301 #: build/C/man2/socket.2:79
5303 msgid "T}:IPv6 Internet protocols:T{\n"
5307 #: build/C/man2/socket.2:80
5309 msgid "B<ipv6>(7)\n"
5313 #: build/C/man2/socket.2:83
5319 #: build/C/man2/socket.2:84
5321 msgid "T}:IPX - Novell protocols:\n"
5325 #: build/C/man2/socket.2:86
5327 msgid "B<AF_NETLINK>\n"
5331 #: build/C/man2/socket.2:88
5333 msgid "Kernel user interface device\n"
5337 #: build/C/man2/socket.2:90
5339 msgid "B<netlink>(7)\n"
5343 #: build/C/man2/socket.2:93
5349 #: build/C/man2/socket.2:94
5351 msgid "T}:ITU-T X.25 / ISO-8208 protocol:T{\n"
5355 #: build/C/man2/socket.2:95
5361 #: build/C/man2/socket.2:98
5363 msgid "B<AF_AX25>\n"
5367 #: build/C/man2/socket.2:100
5369 msgid "Amateur radio AX.25 protocol\n"
5373 #: build/C/man2/socket.2:101
5379 #: build/C/man2/socket.2:103
5381 msgid "B<AF_ATMPVC>\n"
5385 #: build/C/man2/socket.2:104
5387 msgid "T}:Access to raw ATM PVCs:\n"
5391 #: build/C/man2/socket.2:106
5393 msgid "B<AF_APPLETALK>\n"
5397 #: build/C/man2/socket.2:107
5399 msgid "T}:Appletalk:T{\n"
5403 #: build/C/man2/socket.2:108
5409 #: build/C/man2/socket.2:111
5411 msgid "B<AF_PACKET>\n"
5415 #: build/C/man2/socket.2:113
5417 msgid "Low level packet interface\n"
5421 #: build/C/man2/socket.2:115
5423 msgid "B<packet>(7)\n"
5427 #: build/C/man2/socket.2:124
5429 "The socket has the indicated I<type>, which specifies the communication "
5430 "semantics. Currently defined types are:"
5434 #: build/C/man2/socket.2:124
5436 msgid "B<SOCK_STREAM>"
5440 #: build/C/man2/socket.2:128
5442 "Provides sequenced, reliable, two-way, connection-based byte streams. An "
5443 "out-of-band data transmission mechanism may be supported."
5447 #: build/C/man2/socket.2:128
5449 msgid "B<SOCK_DGRAM>"
5453 #: build/C/man2/socket.2:132
5455 "Supports datagrams (connectionless, unreliable messages of a fixed maximum "
5460 #: build/C/man2/socket.2:132
5462 msgid "B<SOCK_SEQPACKET>"
5466 #: build/C/man2/socket.2:137
5468 "Provides a sequenced, reliable, two-way connection-based data transmission "
5469 "path for datagrams of fixed maximum length; a consumer is required to read "
5470 "an entire packet with each input system call."
5474 #: build/C/man2/socket.2:137
5480 #: build/C/man2/socket.2:140
5481 msgid "Provides raw network protocol access."
5485 #: build/C/man2/socket.2:140
5491 #: build/C/man2/socket.2:143
5492 msgid "Provides a reliable datagram layer that does not guarantee ordering."
5496 #: build/C/man2/socket.2:143
5498 msgid "B<SOCK_PACKET>"
5502 #: build/C/man2/socket.2:148
5503 msgid "Obsolete and should not be used in new programs; see B<packet>(7)."
5507 #: build/C/man2/socket.2:154
5509 "Some socket types may not be implemented by all protocol families; for "
5510 "example, B<SOCK_SEQPACKET> is not implemented for B<AF_INET>."
5514 #: build/C/man2/socket.2:162
5516 "Since Linux 2.6.27, the I<type> argument serves a second purpose: in "
5517 "addition to specifying a socket type, it may include the bitwise OR of any "
5518 "of the following values, to modify the behavior of B<socket>():"
5522 #: build/C/man2/socket.2:196
5524 "The I<protocol> specifies a particular protocol to be used with the socket. "
5525 "Normally only a single protocol exists to support a particular socket type "
5526 "within a given protocol family, in which case I<protocol> can be specified "
5527 "as 0. However, it is possible that many protocols may exist, in which case "
5528 "a particular protocol must be specified in this manner. The protocol number "
5529 "to use is specific to the ``communication domain'' in which communication is "
5530 "to take place; see B<protocols>(5). See B<getprotoent>(3) on how to map "
5531 "protocol name strings to protocol numbers."
5535 #: build/C/man2/socket.2:226
5537 "Sockets of type B<SOCK_STREAM> are full-duplex byte streams, similar to "
5538 "pipes. They do not preserve record boundaries. A stream socket must be in "
5539 "a I<connected> state before any data may be sent or received on it. A "
5540 "connection to another socket is created with a B<connect>(2) call. Once "
5541 "connected, data may be transferred using B<read>(2) and B<write>(2) calls "
5542 "or some variant of the B<send>(2) and B<recv>(2) calls. When a session "
5543 "has been completed a B<close>(2) may be performed. Out-of-band data may "
5544 "also be transmitted as described in B<send>(2) and received as described in "
5549 #: build/C/man2/socket.2:252
5551 "The communications protocols which implement a B<SOCK_STREAM> ensure that "
5552 "data is not lost or duplicated. If a piece of data for which the peer "
5553 "protocol has buffer space cannot be successfully transmitted within a "
5554 "reasonable length of time, then the connection is considered to be dead. "
5555 "When B<SO_KEEPALIVE> is enabled on the socket the protocol checks in a "
5556 "protocol-specific manner if the other end is still alive. A B<SIGPIPE> "
5557 "signal is raised if a process sends or receives on a broken stream; this "
5558 "causes naive processes, which do not handle the signal, to exit. "
5559 "B<SOCK_SEQPACKET> sockets employ the same system calls as B<SOCK_STREAM> "
5560 "sockets. The only difference is that B<read>(2) calls will return only the "
5561 "amount of data requested, and any data remaining in the arriving packet will "
5562 "be discarded. Also all message boundaries in incoming datagrams are "
5567 #: build/C/man2/socket.2:262
5569 "B<SOCK_DGRAM> and B<SOCK_RAW> sockets allow sending of datagrams to "
5570 "correspondents named in B<sendto>(2) calls. Datagrams are generally "
5571 "received with B<recvfrom>(2), which returns the next datagram along with the "
5572 "address of its sender."
5576 #: build/C/man2/socket.2:269
5578 "B<SOCK_PACKET> is an obsolete socket type to receive raw packets directly "
5579 "from the device driver. Use B<packet>(7) instead."
5583 #: build/C/man2/socket.2:292
5585 "An B<fcntl>(2) B<F_SETOWN> operation can be used to specify a process or "
5586 "process group to receive a B<SIGURG> signal when the out-of-band data "
5587 "arrives or B<SIGPIPE> signal when a B<SOCK_STREAM> connection breaks "
5588 "unexpectedly. This operation may also be used to set the process or process "
5589 "group that receives the I/O and asynchronous notification of I/O events via "
5590 "B<SIGIO>. Using B<F_SETOWN> is equivalent to an B<ioctl>(2) call with the "
5591 "B<FIOSETOWN> or B<SIOCSPGRP> argument."
5595 #: build/C/man2/socket.2:302
5597 "When the network signals an error condition to the protocol module (e.g., "
5598 "using a ICMP message for IP) the pending error flag is set for the socket. "
5599 "The next operation on this socket will return the error code of the pending "
5600 "error. For some protocols it is possible to enable a per-socket error queue "
5601 "to retrieve detailed information about the error; see B<IP_RECVERR> in "
5606 #: build/C/man2/socket.2:312
5608 "The operation of sockets is controlled by socket level I<options>. These "
5609 "options are defined in I<E<lt>sys/socket.hE<gt>>. The functions "
5610 "B<setsockopt>(2) and B<getsockopt>(2) are used to set and get options, "
5615 #: build/C/man2/socket.2:317
5617 "On success, a file descriptor for the new socket is returned. On error, -1 "
5618 "is returned, and I<errno> is set appropriately."
5622 #: build/C/man2/socket.2:322
5624 "Permission to create a socket of the specified type and/or protocol is "
5629 #: build/C/man2/socket.2:325
5630 msgid "The implementation does not support the specified address family."
5634 #: build/C/man2/socket.2:328
5635 msgid "Unknown protocol, or protocol family not available."
5638 #. Since Linux 2.6.27
5640 #: build/C/man2/socket.2:333
5641 msgid "Invalid flags in I<type>."
5645 #: build/C/man2/socket.2:336
5646 msgid "Process file table overflow."
5650 #: build/C/man2/socket.2:339
5652 msgid "B<ENOBUFS> or B<ENOMEM>"
5656 #: build/C/man2/socket.2:344
5658 "Insufficient memory is available. The socket cannot be created until "
5659 "sufficient resources are freed."
5663 #: build/C/man2/socket.2:344 build/C/man2/socketpair.2:90
5665 msgid "B<EPROTONOSUPPORT>"
5669 #: build/C/man2/socket.2:348
5671 "The protocol type or the specified protocol is not supported within this "
5676 #: build/C/man2/socket.2:350
5677 msgid "Other errors may be generated by the underlying protocol modules."
5681 #: build/C/man2/socket.2:352
5682 msgid "4.4BSD, POSIX.1-2001."
5686 #: build/C/man2/socket.2:358
5687 msgid "The B<SOCK_NONBLOCK> and B<SOCK_CLOEXEC> flags are Linux-specific."
5691 #: build/C/man2/socket.2:364
5693 "B<socket>() appeared in 4.2BSD. It is generally portable to/from non-BSD "
5694 "systems supporting clones of the BSD socket layer (including System V "
5699 #: build/C/man2/socket.2:382
5701 "The manifest constants used under 4.x BSD for protocol families are "
5702 "B<PF_UNIX>, B<PF_INET>, etc., while B<AF_UNIX> etc. are used for address "
5703 "families. However, already the BSD man page promises: \"The protocol family "
5704 "generally is the same as the address family\", and subsequent standards use "
5709 #: build/C/man2/socket.2:387
5710 msgid "An example of the use of B<socket>() is shown in B<getaddrinfo>(3)."
5714 #: build/C/man2/socket.2:410
5716 "B<accept>(2), B<bind>(2), B<connect>(2), B<fcntl>(2), B<getpeername>(2), "
5717 "B<getsockname>(2), B<getsockopt>(2), B<ioctl>(2), B<listen>(2), B<read>(2), "
5718 "B<recv>(2), B<select>(2), B<send>(2), B<shutdown>(2), B<socketpair>(2), "
5719 "B<write>(2), B<getprotoent>(3), B<ip>(7), B<socket>(7), B<tcp>(7), "
5720 "B<udp>(7), B<unix>(7)"
5724 #: build/C/man2/socket.2:414
5726 "\\(lqAn Introductory 4.3BSD Interprocess Communication Tutorial\\(rq is "
5727 "reprinted in I<UNIX Programmer's Supplementary Documents Volume 1.>"
5731 #: build/C/man2/socket.2:418
5733 "\\(lqBSD Interprocess Communication Tutorial\\(rq is reprinted in I<UNIX "
5734 "Programmer's Supplementary Documents Volume 1.>"
5738 #: build/C/man7/socket.7:29
5739 msgid "socket - Linux socket interface"
5743 #: build/C/man7/socket.7:33
5745 "I<sockfd>B< = socket(int >I<socket_family>B<, int >I<socket_type>B<, int "
5750 #: build/C/man7/socket.7:52
5752 "This manual page describes the Linux networking socket layer user "
5753 "interface. The BSD compatible sockets are the uniform interface between the "
5754 "user process and the network protocol stacks in the kernel. The protocol "
5755 "modules are grouped into I<protocol families> like B<AF_INET>, B<AF_IPX>, "
5756 "B<AF_PACKET> and I<socket types> like B<SOCK_STREAM> or B<SOCK_DGRAM>. See "
5757 "B<socket>(2) for more information on families and types."
5761 #: build/C/man7/socket.7:52
5763 msgid "Socket Layer Functions"
5767 #: build/C/man7/socket.7:56
5769 "These functions are used by the user process to send or receive packets and "
5770 "to do other socket operations. For more information see their respective "
5775 #: build/C/man7/socket.7:72
5777 "B<socket>(2) creates a socket, B<connect>(2) connects a socket to a remote "
5778 "socket address, the B<bind>(2) function binds a socket to a local socket "
5779 "address, B<listen>(2) tells the socket that new connections shall be "
5780 "accepted, and B<accept>(2) is used to get a new socket with a new incoming "
5781 "connection. B<socketpair>(2) returns two connected anonymous sockets (only "
5782 "implemented for a few local families like B<AF_UNIX>)"
5786 #: build/C/man7/socket.7:94
5788 "B<send>(2), B<sendto>(2), and B<sendmsg>(2) send data over a socket, and "
5789 "B<recv>(2), B<recvfrom>(2), B<recvmsg>(2) receive data from a socket. "
5790 "B<poll>(2) and B<select>(2) wait for arriving data or a readiness to send "
5791 "data. In addition, the standard I/O operations like B<write>(2), "
5792 "B<writev>(2), B<sendfile>(2), B<read>(2), and B<readv>(2) can be used to "
5793 "read and write data."
5797 #: build/C/man7/socket.7:105
5799 "B<getsockname>(2) returns the local socket address and B<getpeername>(2) "
5800 "returns the remote socket address. B<getsockopt>(2) and B<setsockopt>(2) "
5801 "are used to set or get socket layer or protocol options. B<ioctl>(2) can "
5802 "be used to set or read some other options."
5806 #: build/C/man7/socket.7:110
5808 "B<close>(2) is used to close a socket. B<shutdown>(2) closes parts of a "
5809 "full-duplex socket connection."
5813 #: build/C/man7/socket.7:116
5815 "Seeking, or calling B<pread>(2) or B<pwrite>(2) with a nonzero position is "
5816 "not supported on sockets."
5820 #: build/C/man7/socket.7:133
5822 "It is possible to do nonblocking I/O on sockets by setting the B<O_NONBLOCK> "
5823 "flag on a socket file descriptor using B<fcntl>(2). Then all operations "
5824 "that would block will (usually) return with B<EAGAIN> (operation should be "
5825 "retried later); B<connect>(2) will return B<EINPROGRESS> error. The user "
5826 "can then wait for various events via B<poll>(2) or B<select>(2)."
5830 #: build/C/man7/socket.7:137
5832 msgid "I/O events\n"
5836 #: build/C/man7/socket.7:138
5838 msgid "Event:Poll flag:Occurrence\n"
5842 #: build/C/man7/socket.7:139 build/C/man7/socket.7:142
5844 msgid "Read:POLLIN:T{\n"
5848 #: build/C/man7/socket.7:140
5850 msgid "New data arrived.\n"
5854 #: build/C/man7/socket.7:143
5856 msgid "A connection setup has been completed\n"
5860 #: build/C/man7/socket.7:144
5862 msgid "(for connection-oriented sockets)\n"
5866 #: build/C/man7/socket.7:146 build/C/man7/socket.7:149
5868 msgid "Read:POLLHUP:T{\n"
5872 #: build/C/man7/socket.7:147
5874 msgid "A disconnection request has been initiated by the other end.\n"
5878 #: build/C/man7/socket.7:150
5880 msgid "A connection is broken (only for connection-oriented protocols).\n"
5884 #: build/C/man7/socket.7:151
5886 msgid "When the socket is written\n"
5890 #: build/C/man7/socket.7:152
5892 msgid "B<SIGPIPE>\n"
5896 #: build/C/man7/socket.7:153
5898 msgid "is also sent.\n"
5902 #: build/C/man7/socket.7:155
5904 msgid "Write:POLLOUT:T{\n"
5908 #: build/C/man7/socket.7:156
5910 msgid "Socket has enough send buffer space for writing new data.\n"
5914 #: build/C/man7/socket.7:158
5916 msgid "Read/Write:T{\n"
5920 #: build/C/man7/socket.7:159
5926 #: build/C/man7/socket.7:160
5932 #: build/C/man7/socket.7:161
5938 #: build/C/man7/socket.7:163
5940 msgid "An outgoing\n"
5944 #: build/C/man7/socket.7:164
5946 msgid "B<connect>(2)\n"
5950 #: build/C/man7/socket.7:165
5956 #: build/C/man7/socket.7:167
5958 msgid "Read/Write:POLLERR:An asynchronous error occurred.\n"
5962 #: build/C/man7/socket.7:168
5964 msgid "Read/Write:POLLHUP:The other end has shut down one direction.\n"
5968 #: build/C/man7/socket.7:169
5970 msgid "Exception:POLLPRI:T{\n"
5974 #: build/C/man7/socket.7:170
5976 msgid "Urgent data arrived.\n"
5980 #: build/C/man7/socket.7:171
5986 #: build/C/man7/socket.7:172
5988 msgid "is sent then.\n"
5992 #: build/C/man7/socket.7:202
5994 "An alternative to B<poll>(2) and B<select>(2) is to let the kernel inform "
5995 "the application about events via a B<SIGIO> signal. For that the B<O_ASYNC> "
5996 "flag must be set on a socket file descriptor via B<fcntl>(2) and a valid "
5997 "signal handler for B<SIGIO> must be installed via B<sigaction>(2). See the "
5998 "I<Signals> discussion below."
6002 #: build/C/man7/socket.7:202
6004 msgid "Socket Options"
6008 #. In the list below, the text used to describe argument types
6009 #. for each socket option should be more consistent
6011 #. SO_ACCEPTCONN is in POSIX.1-2001, and its origin is explained in
6012 #. W R Stevens, UNPv1
6014 #: build/C/man7/socket.7:216
6016 "These socket options can be set by using B<setsockopt>(2) and read with "
6017 "B<getsockopt>(2) with the socket level set to B<SOL_SOCKET> for all "
6022 #: build/C/man7/socket.7:216
6024 msgid "B<SO_ACCEPTCONN>"
6028 #: build/C/man7/socket.7:224
6030 "Returns a value indicating whether or not this socket has been marked to "
6031 "accept connections with B<listen>(2). The value 0 indicates that this is "
6032 "not a listening socket, the value 1 indicates that this is a listening "
6033 "socket. This socket option is read-only."
6037 #: build/C/man7/socket.7:224
6039 msgid "B<SO_BINDTODEVICE>"
6043 #: build/C/man7/socket.7:243
6045 "Bind this socket to a particular device like \\(lqeth0\\(rq, as specified in "
6046 "the passed interface name. If the name is an empty string or the option "
6047 "length is zero, the socket device binding is removed. The passed option is "
6048 "a variable-length null-terminated interface name string with the maximum "
6049 "size of B<IFNAMSIZ>. If a socket is bound to an interface, only packets "
6050 "received from that particular interface are processed by the socket. Note "
6051 "that this only works for some socket types, particularly B<AF_INET> "
6052 "sockets. It is not supported for packet sockets (use normal B<bind>(2) "
6057 #: build/C/man7/socket.7:243
6059 msgid "B<SO_BROADCAST>"
6063 #: build/C/man7/socket.7:249
6065 "Set or get the broadcast flag. When enabled, datagram sockets are allowed "
6066 "to send packets to a broadcast address. This option has no effect on "
6067 "stream-oriented sockets."
6071 #: build/C/man7/socket.7:249
6073 msgid "B<SO_BSDCOMPAT>"
6077 #: build/C/man7/socket.7:261
6079 "Enable BSD bug-to-bug compatibility. This is used by the UDP protocol "
6080 "module in Linux 2.0 and 2.2. If enabled ICMP errors received for a UDP "
6081 "socket will not be passed to the user program. In later kernel versions, "
6082 "support for this option has been phased out: Linux 2.4 silently ignores it, "
6083 "and Linux 2.6 generates a kernel warning (printk()) if a program uses this "
6084 "option. Linux 2.0 also enabled BSD bug-to-bug compatibility options (random "
6085 "header changing, skipping of the broadcast flag) for raw sockets with this "
6086 "option, but that was removed in Linux 2.2."
6090 #: build/C/man7/socket.7:261
6096 #: build/C/man7/socket.7:267
6098 "Enable socket debugging. Only allowed for processes with the "
6099 "B<CAP_NET_ADMIN> capability or an effective user ID of 0."
6103 #: build/C/man7/socket.7:267
6105 msgid "B<SO_DOMAIN> (since Linux 2.6.32)"
6109 #: build/C/man7/socket.7:275
6111 "Retrieves the socket domain as an integer, returning a value such as "
6112 "B<AF_INET6>. See B<socket>(2) for details. This socket option is "
6117 #: build/C/man7/socket.7:275
6123 #: build/C/man7/socket.7:280
6125 "Get and clear the pending socket error. This socket option is read-only. "
6126 "Expects an integer."
6130 #: build/C/man7/socket.7:280
6132 msgid "B<SO_DONTROUTE>"
6136 #: build/C/man7/socket.7:289
6138 "Don't send via a gateway, only send to directly connected hosts. The same "
6139 "effect can be achieved by setting the B<MSG_DONTROUTE> flag on a socket "
6140 "B<send>(2) operation. Expects an integer boolean flag."
6144 #: build/C/man7/socket.7:289
6146 msgid "B<SO_KEEPALIVE>"
6150 #: build/C/man7/socket.7:293
6152 "Enable sending of keep-alive messages on connection-oriented sockets. "
6153 "Expects an integer boolean flag."
6157 #: build/C/man7/socket.7:293
6159 msgid "B<SO_LINGER>"
6163 #: build/C/man7/socket.7:301
6165 "Sets or gets the B<SO_LINGER> option. The argument is a I<linger> "
6170 #: build/C/man7/socket.7:308
6174 " int l_onoff; /* linger active */\n"
6175 " int l_linger; /* how many seconds to linger for */\n"
6180 #: build/C/man7/socket.7:322
6182 "When enabled, a B<close>(2) or B<shutdown>(2) will not return until all "
6183 "queued messages for the socket have been successfully sent or the linger "
6184 "timeout has been reached. Otherwise, the call returns immediately and the "
6185 "closing is done in the background. When the socket is closed as part of "
6186 "B<exit>(2), it always lingers in the background."
6190 #: build/C/man7/socket.7:322
6192 msgid "B<SO_OOBINLINE>"
6195 #. don't document it because it can do too much harm.
6198 #: build/C/man7/socket.7:331
6200 "If this option is enabled, out-of-band data is directly placed into the "
6201 "receive data stream. Otherwise out-of-band data is only passed when the "
6202 "B<MSG_OOB> flag is set during receiving."
6206 #: build/C/man7/socket.7:331
6208 msgid "B<SO_PASSCRED>"
6211 #. FIXME Document SO_PASSSEC, added in 2.6.18; there is some info
6212 #. in the 2.6.18 ChangeLog
6214 #: build/C/man7/socket.7:340
6216 "Enable or disable the receiving of the B<SCM_CREDENTIALS> control message. "
6217 "For more information see B<unix>(7)."
6221 #: build/C/man7/socket.7:340
6223 msgid "B<SO_PEERCRED>"
6227 #: build/C/man7/socket.7:360
6229 "Return the credentials of the foreign process connected to this socket. "
6230 "This is only possible for connected B<AF_UNIX> stream sockets and B<AF_UNIX> "
6231 "stream and datagram socket pairs created using B<socketpair>(2); see "
6232 "B<unix>(7). The returned credentials are those that were in effect at the "
6233 "time of the call to B<connect>(2) or B<socketpair>(2). Argument is a "
6234 "I<ucred> structure. This socket option is read-only."
6238 #: build/C/man7/socket.7:360
6240 msgid "B<SO_PRIORITY>"
6244 #: build/C/man7/socket.7:373
6246 "Set the protocol-defined priority for all packets to be sent on this "
6247 "socket. Linux uses this value to order the networking queues: packets with "
6248 "a higher priority may be processed first depending on the selected device "
6249 "queueing discipline. For B<ip>(7), this also sets the IP type-of-service "
6250 "(TOS) field for outgoing packets. Setting a priority outside the range 0 to "
6251 "6 requires the B<CAP_NET_ADMIN> capability."
6255 #: build/C/man7/socket.7:373
6257 msgid "B<SO_PROTOCOL> (since Linux 2.6.32)"
6261 #: build/C/man7/socket.7:381
6263 "Retrieves the socket protocol as an integer, returning a value such as "
6264 "B<IPPROTO_SCTP>. See B<socket>(2) for details. This socket option is "
6269 #: build/C/man7/socket.7:381
6271 msgid "B<SO_RCVBUF>"
6274 #. Most (all?) other implementations do not do this -- MTK, Dec 05
6276 #: build/C/man7/socket.7:396
6278 "Sets or gets the maximum socket receive buffer in bytes. The kernel doubles "
6279 "this value (to allow space for bookkeeping overhead) when it is set using "
6280 "B<setsockopt>(2), and this doubled value is returned by B<getsockopt>(2). "
6281 "The default value is set by the I</proc/sys/net/core/rmem_default> file, and "
6282 "the maximum allowed value is set by the I</proc/sys/net/core/rmem_max> "
6283 "file. The minimum (doubled) value for this option is 256."
6287 #: build/C/man7/socket.7:396
6289 msgid "B<SO_RCVBUFFORCE> (since Linux 2.6.14)"
6293 #: build/C/man7/socket.7:405
6295 "Using this socket option, a privileged (B<CAP_NET_ADMIN>) process can "
6296 "perform the same task as B<SO_RCVBUF>, but the I<rmem_max> limit can be "
6301 #: build/C/man7/socket.7:405
6303 msgid "B<SO_RCVLOWAT> and B<SO_SNDLOWAT>"
6306 #. See http://marc.theaimsgroup.com/?l=linux-kernel&m=111049368106984&w=2
6307 #. Tested on kernel 2.6.14 -- mtk, 30 Nov 05
6309 #: build/C/man7/socket.7:434
6311 "Specify the minimum number of bytes in the buffer until the socket layer "
6312 "will pass the data to the protocol (B<SO_SNDLOWAT>) or the user on "
6313 "receiving (B<SO_RCVLOWAT>). These two values are initialized to 1. "
6314 "B<SO_SNDLOWAT> is not changeable on Linux (B<setsockopt>(2) fails with the "
6315 "error B<ENOPROTOOPT>). B<SO_RCVLOWAT> is changeable only since Linux 2.4. "
6316 "The B<select>(2) and B<poll>(2) system calls currently do not respect the "
6317 "B<SO_RCVLOWAT> setting on Linux, and mark a socket readable when even a "
6318 "single byte of data is available. A subsequent read from the socket will "
6319 "block until B<SO_RCVLOWAT> bytes are available."
6323 #: build/C/man7/socket.7:434
6325 msgid "B<SO_RCVTIMEO> and B<SO_SNDTIMEO>"
6328 #. Not implemented in 2.0.
6329 #. Implemented in 2.1.11 for getsockopt: always return a zero struct.
6330 #. Implemented in 2.3.41 for setsockopt, and actually used.
6331 #. in fact to EAGAIN
6333 #: build/C/man7/socket.7:465
6335 "Specify the receiving or sending timeouts until reporting an error. The "
6336 "argument is a I<struct timeval>. If an input or output function blocks for "
6337 "this period of time, and data has been sent or received, the return value of "
6338 "that function will be the amount of data transferred; if no data has been "
6339 "transferred and the timeout has been reached then -1 is returned with "
6340 "I<errno> set to B<EAGAIN> or B<EWOULDBLOCK> just as if the socket was "
6341 "specified to be nonblocking. If the timeout is set to zero (the default) "
6342 "then the operation will never timeout. Timeouts only have effect for system "
6343 "calls that perform socket I/O (e.g., B<read>(2), B<recvmsg>(2), B<send>(2), "
6344 "B<sendmsg>(2)); timeouts have no effect for B<select>(2), B<poll>(2), "
6345 "B<epoll_wait>(2), etc."
6349 #: build/C/man7/socket.7:465
6351 msgid "B<SO_REUSEADDR>"
6355 #: build/C/man7/socket.7:480
6357 "Indicates that the rules used in validating addresses supplied in a "
6358 "B<bind>(2) call should allow reuse of local addresses. For B<AF_INET> "
6359 "sockets this means that a socket may bind, except when there is an active "
6360 "listening socket bound to the address. When the listening socket is bound "
6361 "to B<INADDR_ANY> with a specific port then it is not possible to bind to "
6362 "this port for any local address. Argument is an integer boolean flag."
6366 #: build/C/man7/socket.7:480
6368 msgid "B<SO_SNDBUF>"
6371 #. Most (all?) other implementations do not do this -- MTK, Dec 05
6373 #: build/C/man7/socket.7:495
6375 "Sets or gets the maximum socket send buffer in bytes. The kernel doubles "
6376 "this value (to allow space for bookkeeping overhead) when it is set using "
6377 "B<setsockopt>(2), and this doubled value is returned by B<getsockopt>(2). "
6378 "The default value is set by the I</proc/sys/net/core/wmem_default> file and "
6379 "the maximum allowed value is set by the I</proc/sys/net/core/wmem_max> "
6380 "file. The minimum (doubled) value for this option is 2048."
6384 #: build/C/man7/socket.7:495
6386 msgid "B<SO_SNDBUFFORCE> (since Linux 2.6.14)"
6390 #: build/C/man7/socket.7:504
6392 "Using this socket option, a privileged (B<CAP_NET_ADMIN>) process can "
6393 "perform the same task as B<SO_SNDBUF>, but the I<wmem_max> limit can be "
6398 #: build/C/man7/socket.7:504
6400 msgid "B<SO_TIMESTAMP>"
6404 #: build/C/man7/socket.7:520
6406 "Enable or disable the receiving of the B<SO_TIMESTAMP> control message. The "
6407 "timestamp control message is sent with level B<SOL_SOCKET> and the "
6408 "I<cmsg_data> field is a I<struct timeval> indicating the reception time of "
6409 "the last packet passed to the user in this call. See B<cmsg>(3) for "
6410 "details on control messages."
6414 #: build/C/man7/socket.7:520
6420 #: build/C/man7/socket.7:525
6422 "Gets the socket type as an integer (e.g., B<SOCK_STREAM>). This socket "
6423 "option is read-only."
6427 #: build/C/man7/socket.7:525
6433 #: build/C/man7/socket.7:536
6435 "When writing onto a connection-oriented socket that has been shut down (by "
6436 "the local or the remote end) B<SIGPIPE> is sent to the writing process and "
6437 "B<EPIPE> is returned. The signal is not sent when the write call specified "
6438 "the B<MSG_NOSIGNAL> flag."
6442 #: build/C/man7/socket.7:561
6444 "When requested with the B<FIOSETOWN> B<fcntl>(2) or B<SIOCSPGRP> "
6445 "B<ioctl>(2), B<SIGIO> is sent when an I/O event occurs. It is possible to "
6446 "use B<poll>(2) or B<select>(2) in the signal handler to find out which "
6447 "socket the event occurred on. An alternative (in Linux 2.2) is to set a "
6448 "real-time signal using the B<F_SETSIG> B<fcntl>(2); the handler of the real "
6449 "time signal will be called with the file descriptor in the I<si_fd> field of "
6450 "its I<siginfo_t>. See B<fcntl>(2) for more information."
6453 #. .SS Ancillary Messages
6455 #: build/C/man7/socket.7:569
6457 "Under some circumstances (e.g., multiple processes accessing a single "
6458 "socket), the condition that caused the B<SIGIO> may have already disappeared "
6459 "when the process reacts to the signal. If this happens, the process should "
6460 "wait again because Linux will resend the signal later."
6464 #: build/C/man7/socket.7:569
6466 msgid "/proc interfaces"
6470 #: build/C/man7/socket.7:573
6472 "The core socket networking parameters can be accessed via files in the "
6473 "directory I</proc/sys/net/core/>."
6477 #: build/C/man7/socket.7:573
6479 msgid "I<rmem_default>"
6483 #: build/C/man7/socket.7:576
6484 msgid "contains the default setting in bytes of the socket receive buffer."
6488 #: build/C/man7/socket.7:576
6494 #: build/C/man7/socket.7:582
6496 "contains the maximum socket receive buffer size in bytes which a user may "
6497 "set by using the B<SO_RCVBUF> socket option."
6501 #: build/C/man7/socket.7:582
6503 msgid "I<wmem_default>"
6507 #: build/C/man7/socket.7:585
6508 msgid "contains the default setting in bytes of the socket send buffer."
6512 #: build/C/man7/socket.7:585
6518 #: build/C/man7/socket.7:591
6520 "contains the maximum socket send buffer size in bytes which a user may set "
6521 "by using the B<SO_SNDBUF> socket option."
6525 #: build/C/man7/socket.7:591
6527 msgid "I<message_cost> and I<message_burst>"
6531 #: build/C/man7/socket.7:595
6533 "configure the token bucket filter used to load limit warning messages caused "
6534 "by external network events."
6538 #: build/C/man7/socket.7:595
6540 msgid "I<netdev_max_backlog>"
6544 #: build/C/man7/socket.7:598
6545 msgid "Maximum number of packets in the global input queue."
6549 #: build/C/man7/socket.7:598
6551 msgid "I<optmem_max>"
6554 #. netdev_fastroute is not documented because it is experimental
6556 #: build/C/man7/socket.7:603
6558 "Maximum length of ancillary data and user control data like the iovecs per "
6563 #: build/C/man7/socket.7:603
6569 #: build/C/man7/socket.7:606
6570 msgid "These operations can be accessed using B<ioctl>(2):"
6574 #: build/C/man7/socket.7:610
6577 "I<error>B< = ioctl(>I<ip_socket>B<, >I<ioctl_type>B<, "
6578 ">I<&value_result>B<);>\n"
6582 #: build/C/man7/socket.7:612
6584 msgid "B<SIOCGSTAMP>"
6588 #: build/C/man7/socket.7:636
6590 "Return a I<struct timeval> with the receive timestamp of the last packet "
6591 "passed to the user. This is useful for accurate round trip time "
6592 "measurements. See B<setitimer>(2) for a description of I<struct timeval>. "
6593 "This ioctl should only be used if the socket option B<SO_TIMESTAMP> is not "
6594 "set on the socket. Otherwise, it returns the timestamp of the last packet "
6595 "that was received while B<SO_TIMESTAMP> was not set, or it fails if no such "
6596 "packet has been received, (i.e., B<ioctl>(2) returns -1 with I<errno> set "
6601 #: build/C/man7/socket.7:636
6603 msgid "B<SIOCSPGRP>"
6607 #: build/C/man7/socket.7:655
6609 "Set the process or process group to send B<SIGIO> or B<SIGURG> signals to "
6610 "when an asynchronous I/O operation has finished or urgent data is "
6611 "available. The argument is a pointer to a I<pid_t>. If the argument is "
6612 "positive, send the signals to that process. If the argument is negative, "
6613 "send the signals to the process group with the ID of the absolute value of "
6614 "the argument. The process may only choose itself or its own process group "
6615 "to receive signals unless it has the B<CAP_KILL> capability or an effective "
6620 #: build/C/man7/socket.7:655
6626 #: build/C/man7/socket.7:665
6628 "Change the B<O_ASYNC> flag to enable or disable asynchronous I/O mode of the "
6629 "socket. Asynchronous I/O mode means that the B<SIGIO> signal or the signal "
6630 "set with B<F_SETSIG> is raised when a new I/O event occurs."
6634 #: build/C/man7/socket.7:673
6636 "Argument is an integer boolean flag. (This operation is synonymous with the "
6637 "use of B<fcntl>(2) to set the B<O_ASYNC> flag.)"
6641 #: build/C/man7/socket.7:673
6643 msgid "B<SIOCGPGRP>"
6647 #: build/C/man7/socket.7:682
6649 "Get the current process or process group that receives B<SIGIO> or B<SIGURG> "
6650 "signals, or 0 when none is set."
6654 #: build/C/man7/socket.7:686
6655 msgid "Valid B<fcntl>(2) operations:"
6659 #: build/C/man7/socket.7:686
6661 msgid "B<FIOGETOWN>"
6665 #: build/C/man7/socket.7:691
6666 msgid "The same as the B<SIOCGPGRP> B<ioctl>(2)."
6670 #: build/C/man7/socket.7:691
6672 msgid "B<FIOSETOWN>"
6676 #: build/C/man7/socket.7:696
6677 msgid "The same as the B<SIOCSPGRP> B<ioctl>(2)."
6681 #: build/C/man7/socket.7:710
6683 "B<SO_BINDTODEVICE> was introduced in Linux 2.0.30. B<SO_PASSCRED> is new in "
6684 "Linux 2.2. The I</proc> interfaces was introduced in Linux 2.2. "
6685 "B<SO_RCVTIMEO> and B<SO_SNDTIMEO> are supported since Linux 2.3.41. "
6686 "Earlier, timeouts were fixed to a protocol-specific setting, and could not "
6687 "be read or written."
6691 #: build/C/man7/socket.7:715
6693 "Linux assumes that half of the send/receive buffer is used for internal "
6694 "kernel structures; thus the values in the corresponding I</proc> files are "
6695 "twice what can be observed on the wire."
6699 #: build/C/man7/socket.7:728
6701 "Linux will only allow port reuse with the B<SO_REUSEADDR> option when this "
6702 "option was set both in the previous program that performed a B<bind>(2) to "
6703 "the port and in the program that wants to reuse the port. This differs from "
6704 "some implementations (e.g., FreeBSD) where only the later program needs to "
6705 "set the B<SO_REUSEADDR> option. Typically this difference is invisible, "
6706 "since, for example, a server program is designed to always set this option."
6709 #. FIXME Document SO_ATTACH_FILTER and SO_DETACH_FILTER
6711 #. This man page was written by Andi Kleen.
6713 #: build/C/man7/socket.7:741
6715 "The B<CONFIG_FILTER> socket options B<SO_ATTACH_FILTER> and "
6716 "B<SO_DETACH_FILTER> are not documented. The suggested interface to use them "
6717 "is via the libpcap library."
6721 #: build/C/man7/socket.7:752
6723 "B<getsockopt>(2), B<setsockopt>(2), B<socket>(2), B<capabilities>(7), "
6724 "B<ddp>(7), B<ip>(7), B<packet>(7), B<tcp>(7), B<udp>(7), B<unix>(7)"
6728 #: build/C/man2/socketcall.2:26
6734 #: build/C/man2/socketcall.2:26
6740 #: build/C/man2/socketcall.2:29
6741 msgid "socketcall - socket system calls"
6745 #: build/C/man2/socketcall.2:31
6746 msgid "B<int socketcall(int >I<call>B<, unsigned long *>I<args>B<);>"
6750 #: build/C/man2/socketcall.2:39
6752 "B<socketcall>() is a common kernel entry point for the socket system "
6753 "calls. I<call> determines which socket function to invoke. I<args> points "
6754 "to a block containing the actual arguments, which are passed through to the "
6759 #: build/C/man2/socketcall.2:43
6761 "User programs should call the appropriate functions by their usual names. "
6762 "Only standard library implementors and kernel hackers need to know about "
6767 #: build/C/man2/socketcall.2:46
6769 "This call is specific to Linux, and should not be used in programs intended "
6774 #: build/C/man2/socketcall.2:54
6776 "On a few architectures, for example ia64, there is no B<socketcall>() "
6777 "system call; instead B<socket>(2), B<accept>(2), B<bind>(2), and so on "
6778 "really are implemented as separate system calls."
6782 #: build/C/man2/socketcall.2:72
6784 "B<accept>(2), B<bind>(2), B<connect>(2), B<getpeername>(2), "
6785 "B<getsockname>(2), B<getsockopt>(2), B<listen>(2), B<recv>(2), "
6786 "B<recvfrom>(2), B<recvmsg>(2), B<send>(2), B<sendmsg>(2), B<sendto>(2), "
6787 "B<setsockopt>(2), B<shutdown>(2), B<socket>(2), B<socketpair>(2)"
6791 #: build/C/man2/socketpair.2:40
6797 #: build/C/man2/socketpair.2:40
6803 #: build/C/man2/socketpair.2:43
6804 msgid "socketpair - create a pair of connected sockets"
6808 #: build/C/man2/socketpair.2:50
6810 "B<int socketpair(int >I<domain>B<, int >I<type>B<, int >I<protocol>B<, int "
6815 #: build/C/man2/socketpair.2:61
6817 "The B<socketpair>() call creates an unnamed pair of connected sockets in "
6818 "the specified I<domain>, of the specified I<type>, and using the optionally "
6819 "specified I<protocol>. For further details of these arguments, see "
6824 #: build/C/man2/socketpair.2:67
6826 "The descriptors used in referencing the new sockets are returned in I<sv>[0] "
6827 "and I<sv>[1]. The two sockets are indistinguishable."
6831 #: build/C/man2/socketpair.2:76
6832 msgid "The specified address family is not supported on this machine."
6836 #: build/C/man2/socketpair.2:81
6838 "The address I<sv> does not specify a valid part of the process address "
6843 #: build/C/man2/socketpair.2:84
6844 msgid "Too many descriptors are in use by this process."
6848 #: build/C/man2/socketpair.2:90
6849 msgid "The specified protocol does not support creation of socket pairs."
6853 #: build/C/man2/socketpair.2:93
6854 msgid "The specified protocol is not supported on this machine."
6858 #: build/C/man2/socketpair.2:101
6860 "4.4BSD, POSIX.1-2001. The B<socketpair>() function call appeared in "
6861 "4.2BSD. It is generally portable to/from non-BSD systems supporting clones "
6862 "of the BSD socket layer (including System V variants)."
6866 #: build/C/man2/socketpair.2:107
6868 "On Linux, the only supported domain for this call is B<AF_UNIX> (or "
6869 "synonymously, B<AF_LOCAL>). (Most implementations have the same "
6874 #: build/C/man2/socketpair.2:116
6876 "Since Linux 2.6.27, B<socketpair>() supports the B<SOCK_NONBLOCK> and "
6877 "B<SOCK_CLOEXEC> flags described in B<socket>(2)."
6881 #: build/C/man2/socketpair.2:129
6882 msgid "B<pipe>(2), B<read>(2), B<socket>(2), B<write>(2), B<socket>(7), B<unix>(7)"