]>
Commit | Line | Data |
---|---|---|
28f540f4 | 1 | @node Sockets, Low-Level Terminal Interface, Pipes and FIFOs, Top |
7a68c94a | 2 | @c %MENU% A more complicated IPC mechanism, with networking support |
28f540f4 RM |
3 | @chapter Sockets |
4 | ||
5 | This chapter describes the GNU facilities for interprocess | |
6 | communication using sockets. | |
7 | ||
8 | @cindex socket | |
9 | @cindex interprocess communication, with sockets | |
10 | A @dfn{socket} is a generalized interprocess communication channel. | |
04b9968b UD |
11 | Like a pipe, a socket is represented as a file descriptor. Unlike pipes |
12 | sockets support communication between unrelated processes, and even | |
13 | between processes running on different machines that communicate over a | |
14 | network. Sockets are the primary means of communicating with other | |
15 | machines; @code{telnet}, @code{rlogin}, @code{ftp}, @code{talk} and the | |
16 | other familiar network programs use sockets. | |
28f540f4 | 17 | |
1f77f049 | 18 | Not all operating systems support sockets. In @theglibc{}, the |
28f540f4 RM |
19 | header file @file{sys/socket.h} exists regardless of the operating |
20 | system, and the socket functions always exist, but if the system does | |
04b9968b | 21 | not really support sockets these functions always fail. |
28f540f4 RM |
22 | |
23 | @strong{Incomplete:} We do not currently document the facilities for | |
4bca4c17 UD |
24 | broadcast messages or for configuring Internet interfaces. The |
25 | reentrant functions and some newer functions that are related to IPv6 | |
26 | aren't documented either so far. | |
28f540f4 RM |
27 | |
28 | @menu | |
29 | * Socket Concepts:: Basic concepts you need to know about. | |
04b9968b | 30 | * Communication Styles::Stream communication, datagrams and other styles. |
28f540f4 | 31 | * Socket Addresses:: How socket names (``addresses'') work. |
4bca4c17 UD |
32 | * Interface Naming:: Identifying specific network interfaces. |
33 | * Local Namespace:: Details about the local namespace. | |
28f540f4 RM |
34 | * Internet Namespace:: Details about the Internet namespace. |
35 | * Misc Namespaces:: Other namespaces not documented fully here. | |
36 | * Open/Close Sockets:: Creating sockets and destroying them. | |
37 | * Connections:: Operations on sockets with connection state. | |
38 | * Datagrams:: Operations on datagram sockets. | |
39 | * Inetd:: Inetd is a daemon that starts servers on request. | |
40 | The most convenient way to write a server | |
41 | is to make it work with Inetd. | |
42 | * Socket Options:: Miscellaneous low-level socket options. | |
43 | * Networks Database:: Accessing the database of network names. | |
44 | @end menu | |
45 | ||
46 | @node Socket Concepts | |
47 | @section Socket Concepts | |
48 | ||
49 | @cindex communication style (of a socket) | |
50 | @cindex style of communication (of a socket) | |
51 | When you create a socket, you must specify the style of communication | |
52 | you want to use and the type of protocol that should implement it. | |
53 | The @dfn{communication style} of a socket defines the user-level | |
54 | semantics of sending and receiving data on the socket. Choosing a | |
55 | communication style specifies the answers to questions such as these: | |
56 | ||
57 | @itemize @bullet | |
58 | @item | |
59 | @cindex packet | |
60 | @cindex byte stream | |
61 | @cindex stream (sockets) | |
62 | @strong{What are the units of data transmission?} Some communication | |
04b9968b | 63 | styles regard the data as a sequence of bytes with no larger |
28f540f4 RM |
64 | structure; others group the bytes into records (which are known in |
65 | this context as @dfn{packets}). | |
66 | ||
67 | @item | |
68 | @cindex loss of data on sockets | |
69 | @cindex data loss on sockets | |
70 | @strong{Can data be lost during normal operation?} Some communication | |
71 | styles guarantee that all the data sent arrives in the order it was | |
72 | sent (barring system or network crashes); other styles occasionally | |
73 | lose data as a normal part of operation, and may sometimes deliver | |
74 | packets more than once or in the wrong order. | |
75 | ||
76 | Designing a program to use unreliable communication styles usually | |
77 | involves taking precautions to detect lost or misordered packets and | |
78 | to retransmit data as needed. | |
79 | ||
80 | @item | |
81 | @strong{Is communication entirely with one partner?} Some | |
82 | communication styles are like a telephone call---you make a | |
04b9968b | 83 | @dfn{connection} with one remote socket and then exchange data |
28f540f4 RM |
84 | freely. Other styles are like mailing letters---you specify a |
85 | destination address for each message you send. | |
86 | @end itemize | |
87 | ||
88 | @cindex namespace (of socket) | |
89 | @cindex domain (of socket) | |
90 | @cindex socket namespace | |
91 | @cindex socket domain | |
92 | You must also choose a @dfn{namespace} for naming the socket. A socket | |
93 | name (``address'') is meaningful only in the context of a particular | |
94 | namespace. In fact, even the data type to use for a socket name may | |
95 | depend on the namespace. Namespaces are also called ``domains'', but we | |
96 | avoid that word as it can be confused with other usage of the same | |
97 | term. Each namespace has a symbolic name that starts with @samp{PF_}. | |
98 | A corresponding symbolic name starting with @samp{AF_} designates the | |
99 | address format for that namespace. | |
100 | ||
101 | @cindex network protocol | |
102 | @cindex protocol (of socket) | |
103 | @cindex socket protocol | |
104 | @cindex protocol family | |
105 | Finally you must choose the @dfn{protocol} to carry out the | |
106 | communication. The protocol determines what low-level mechanism is used | |
107 | to transmit and receive data. Each protocol is valid for a particular | |
108 | namespace and communication style; a namespace is sometimes called a | |
109 | @dfn{protocol family} because of this, which is why the namespace names | |
110 | start with @samp{PF_}. | |
111 | ||
112 | The rules of a protocol apply to the data passing between two programs, | |
113 | perhaps on different computers; most of these rules are handled by the | |
04b9968b | 114 | operating system and you need not know about them. What you do need to |
28f540f4 RM |
115 | know about protocols is this: |
116 | ||
117 | @itemize @bullet | |
118 | @item | |
119 | In order to have communication between two sockets, they must specify | |
120 | the @emph{same} protocol. | |
121 | ||
122 | @item | |
123 | Each protocol is meaningful with particular style/namespace | |
124 | combinations and cannot be used with inappropriate combinations. For | |
125 | example, the TCP protocol fits only the byte stream style of | |
126 | communication and the Internet namespace. | |
127 | ||
128 | @item | |
04b9968b UD |
129 | For each combination of style and namespace there is a @dfn{default |
130 | protocol}, which you can request by specifying 0 as the protocol | |
28f540f4 RM |
131 | number. And that's what you should normally do---use the default. |
132 | @end itemize | |
133 | ||
55c14926 UD |
134 | Throughout the following description at various places |
135 | variables/parameters to denote sizes are required. And here the trouble | |
136 | starts. In the first implementations the type of these variables was | |
04b9968b UD |
137 | simply @code{int}. On most machines at that time an @code{int} was 32 |
138 | bits wide, which created a @emph{de facto} standard requiring 32-bit | |
139 | variables. This is important since references to variables of this type | |
140 | are passed to the kernel. | |
141 | ||
142 | Then the POSIX people came and unified the interface with the words "all | |
143 | size values are of type @code{size_t}". On 64-bit machines | |
144 | @code{size_t} is 64 bits wide, so pointers to variables were no longer | |
55c14926 UD |
145 | possible. |
146 | ||
8163845f UD |
147 | The Unix98 specification provides a solution by introducing a type |
148 | @code{socklen_t}. This type is used in all of the cases that POSIX | |
149 | changed to use @code{size_t}. The only requirement of this type is that | |
150 | it be an unsigned type of at least 32 bits. Therefore, implementations | |
04b9968b UD |
151 | which require that references to 32-bit variables be passed can be as |
152 | happy as implementations which use 64-bit values. | |
55c14926 UD |
153 | |
154 | ||
28f540f4 RM |
155 | @node Communication Styles |
156 | @section Communication Styles | |
157 | ||
1f77f049 | 158 | @Theglibc{} includes support for several different kinds of sockets, |
28f540f4 RM |
159 | each with different characteristics. This section describes the |
160 | supported socket types. The symbolic constants listed here are | |
161 | defined in @file{sys/socket.h}. | |
162 | @pindex sys/socket.h | |
163 | ||
164 | @comment sys/socket.h | |
165 | @comment BSD | |
166 | @deftypevr Macro int SOCK_STREAM | |
04b9968b UD |
167 | The @code{SOCK_STREAM} style is like a pipe (@pxref{Pipes and FIFOs}). |
168 | It operates over a connection with a particular remote socket and | |
28f540f4 RM |
169 | transmits data reliably as a stream of bytes. |
170 | ||
171 | Use of this style is covered in detail in @ref{Connections}. | |
172 | @end deftypevr | |
173 | ||
174 | @comment sys/socket.h | |
175 | @comment BSD | |
176 | @deftypevr Macro int SOCK_DGRAM | |
177 | The @code{SOCK_DGRAM} style is used for sending | |
04b9968b | 178 | individually-addressed packets unreliably. |
28f540f4 RM |
179 | It is the diametrical opposite of @code{SOCK_STREAM}. |
180 | ||
181 | Each time you write data to a socket of this kind, that data becomes | |
182 | one packet. Since @code{SOCK_DGRAM} sockets do not have connections, | |
183 | you must specify the recipient address with each packet. | |
184 | ||
185 | The only guarantee that the system makes about your requests to | |
186 | transmit data is that it will try its best to deliver each packet you | |
187 | send. It may succeed with the sixth packet after failing with the | |
188 | fourth and fifth packets; the seventh packet may arrive before the | |
189 | sixth, and may arrive a second time after the sixth. | |
190 | ||
191 | The typical use for @code{SOCK_DGRAM} is in situations where it is | |
04b9968b | 192 | acceptable to simply re-send a packet if no response is seen in a |
28f540f4 RM |
193 | reasonable amount of time. |
194 | ||
195 | @xref{Datagrams}, for detailed information about how to use datagram | |
196 | sockets. | |
197 | @end deftypevr | |
198 | ||
199 | @ignore | |
200 | @c This appears to be only for the NS domain, which we aren't | |
201 | @c discussing and probably won't support either. | |
202 | @comment sys/socket.h | |
203 | @comment BSD | |
204 | @deftypevr Macro int SOCK_SEQPACKET | |
04b9968b | 205 | This style is like @code{SOCK_STREAM} except that the data are |
28f540f4 RM |
206 | structured into packets. |
207 | ||
208 | A program that receives data over a @code{SOCK_SEQPACKET} socket | |
209 | should be prepared to read the entire message packet in a single call | |
210 | to @code{read}; if it only reads part of the message, the remainder of | |
211 | the message is simply discarded instead of being available for | |
212 | subsequent calls to @code{read}. | |
213 | ||
214 | Many protocols do not support this communication style. | |
215 | @end deftypevr | |
216 | @end ignore | |
217 | ||
218 | @ignore | |
219 | @comment sys/socket.h | |
220 | @comment BSD | |
221 | @deftypevr Macro int SOCK_RDM | |
222 | This style is a reliable version of @code{SOCK_DGRAM}: it sends | |
223 | individually addressed packets, but guarantees that each packet sent | |
224 | arrives exactly once. | |
225 | ||
226 | @strong{Warning:} It is not clear this is actually supported | |
227 | by any operating system. | |
228 | @end deftypevr | |
229 | @end ignore | |
230 | ||
231 | @comment sys/socket.h | |
232 | @comment BSD | |
233 | @deftypevr Macro int SOCK_RAW | |
234 | This style provides access to low-level network protocols and | |
235 | interfaces. Ordinary user programs usually have no need to use this | |
236 | style. | |
237 | @end deftypevr | |
238 | ||
239 | @node Socket Addresses | |
240 | @section Socket Addresses | |
241 | ||
242 | @cindex address of socket | |
243 | @cindex name of socket | |
244 | @cindex binding a socket address | |
245 | @cindex socket address (name) binding | |
246 | The name of a socket is normally called an @dfn{address}. The | |
247 | functions and symbols for dealing with socket addresses were named | |
248 | inconsistently, sometimes using the term ``name'' and sometimes using | |
249 | ``address''. You can regard these terms as synonymous where sockets | |
250 | are concerned. | |
251 | ||
252 | A socket newly created with the @code{socket} function has no | |
253 | address. Other processes can find it for communication only if you | |
254 | give it an address. We call this @dfn{binding} the address to the | |
255 | socket, and the way to do it is with the @code{bind} function. | |
256 | ||
257 | You need be concerned with the address of a socket if other processes | |
258 | are to find it and start communicating with it. You can specify an | |
259 | address for other sockets, but this is usually pointless; the first time | |
260 | you send data from a socket, or use it to initiate a connection, the | |
261 | system assigns an address automatically if you have not specified one. | |
262 | ||
263 | Occasionally a client needs to specify an address because the server | |
04b9968b | 264 | discriminates based on address; for example, the rsh and rlogin |
4bca4c17 UD |
265 | protocols look at the client's socket address and only bypass password |
266 | checking if it is less than @code{IPPORT_RESERVED} (@pxref{Ports}). | |
28f540f4 RM |
267 | |
268 | The details of socket addresses vary depending on what namespace you are | |
4bca4c17 | 269 | using. @xref{Local Namespace}, or @ref{Internet Namespace}, for specific |
28f540f4 RM |
270 | information. |
271 | ||
272 | Regardless of the namespace, you use the same functions @code{bind} and | |
273 | @code{getsockname} to set and examine a socket's address. These | |
274 | functions use a phony data type, @code{struct sockaddr *}, to accept the | |
275 | address. In practice, the address lives in a structure of some other | |
276 | data type appropriate to the address format you are using, but you cast | |
277 | its address to @code{struct sockaddr *} when you pass it to | |
278 | @code{bind}. | |
279 | ||
280 | @menu | |
281 | * Address Formats:: About @code{struct sockaddr}. | |
282 | * Setting Address:: Binding an address to a socket. | |
283 | * Reading Address:: Reading the address of a socket. | |
284 | @end menu | |
285 | ||
286 | @node Address Formats | |
287 | @subsection Address Formats | |
288 | ||
289 | The functions @code{bind} and @code{getsockname} use the generic data | |
290 | type @code{struct sockaddr *} to represent a pointer to a socket | |
291 | address. You can't use this data type effectively to interpret an | |
292 | address or construct one; for that, you must use the proper data type | |
293 | for the socket's namespace. | |
294 | ||
04b9968b | 295 | Thus, the usual practice is to construct an address of the proper |
28f540f4 RM |
296 | namespace-specific type, then cast a pointer to @code{struct sockaddr *} |
297 | when you call @code{bind} or @code{getsockname}. | |
298 | ||
299 | The one piece of information that you can get from the @code{struct | |
04b9968b | 300 | sockaddr} data type is the @dfn{address format designator}. This tells |
28f540f4 RM |
301 | you which data type to use to understand the address fully. |
302 | ||
303 | @pindex sys/socket.h | |
304 | The symbols in this section are defined in the header file | |
305 | @file{sys/socket.h}. | |
306 | ||
307 | @comment sys/socket.h | |
308 | @comment BSD | |
4bca4c17 | 309 | @deftp {Data Type} {struct sockaddr} |
28f540f4 RM |
310 | The @code{struct sockaddr} type itself has the following members: |
311 | ||
312 | @table @code | |
313 | @item short int sa_family | |
314 | This is the code for the address format of this address. It | |
315 | identifies the format of the data which follows. | |
316 | ||
317 | @item char sa_data[14] | |
318 | This is the actual socket address data, which is format-dependent. Its | |
319 | length also depends on the format, and may well be more than 14. The | |
320 | length 14 of @code{sa_data} is essentially arbitrary. | |
321 | @end table | |
322 | @end deftp | |
323 | ||
324 | Each address format has a symbolic name which starts with @samp{AF_}. | |
325 | Each of them corresponds to a @samp{PF_} symbol which designates the | |
326 | corresponding namespace. Here is a list of address format names: | |
327 | ||
328 | @table @code | |
329 | @comment sys/socket.h | |
356d7100 UD |
330 | @comment POSIX |
331 | @item AF_LOCAL | |
332 | @vindex AF_LOCAL | |
333 | This designates the address format that goes with the local namespace. | |
334 | (@code{PF_LOCAL} is the name of that namespace.) @xref{Local Namespace | |
28f540f4 RM |
335 | Details}, for information about this address format. |
336 | ||
337 | @comment sys/socket.h | |
fc4de705 | 338 | @comment BSD, Unix98 |
28f540f4 RM |
339 | @item AF_UNIX |
340 | @vindex AF_UNIX | |
fc4de705 UD |
341 | This is a synonym for @code{AF_LOCAL}. Although @code{AF_LOCAL} is |
342 | mandated by POSIX.1g, @code{AF_UNIX} is portable to more systems. | |
343 | @code{AF_UNIX} was the traditional name stemming from BSD, so even most | |
344 | POSIX systems support it. It is also the name of choice in the Unix98 | |
345 | specification. (The same is true for @code{PF_UNIX} | |
346 | vs. @code{PF_LOCAL}). | |
28f540f4 | 347 | |
4bca4c17 | 348 | @comment sys/socket.h |
356d7100 UD |
349 | @comment GNU |
350 | @item AF_FILE | |
351 | @vindex AF_FILE | |
352 | This is another synonym for @code{AF_LOCAL}, for compatibility. | |
353 | (@code{PF_FILE} is likewise a synonym for @code{PF_LOCAL}.) | |
4bca4c17 | 354 | |
28f540f4 RM |
355 | @comment sys/socket.h |
356 | @comment BSD | |
357 | @item AF_INET | |
358 | @vindex AF_INET | |
359 | This designates the address format that goes with the Internet | |
360 | namespace. (@code{PF_INET} is the name of that namespace.) | |
3996f34b UD |
361 | @xref{Internet Address Formats}. |
362 | ||
363 | @comment sys/socket.h | |
364 | @comment IPv6 Basic API | |
365 | @item AF_INET6 | |
366 | This is similar to @code{AF_INET}, but refers to the IPv6 protocol. | |
367 | (@code{PF_INET6} is the name of the corresponding namespace.) | |
28f540f4 RM |
368 | |
369 | @comment sys/socket.h | |
370 | @comment BSD | |
371 | @item AF_UNSPEC | |
372 | @vindex AF_UNSPEC | |
373 | This designates no particular address format. It is used only in rare | |
374 | cases, such as to clear out the default destination address of a | |
375 | ``connected'' datagram socket. @xref{Sending Datagrams}. | |
376 | ||
377 | The corresponding namespace designator symbol @code{PF_UNSPEC} exists | |
378 | for completeness, but there is no reason to use it in a program. | |
379 | @end table | |
380 | ||
381 | @file{sys/socket.h} defines symbols starting with @samp{AF_} for many | |
04b9968b UD |
382 | different kinds of networks, most or all of which are not actually |
383 | implemented. We will document those that really work as we receive | |
28f540f4 RM |
384 | information about how to use them. |
385 | ||
386 | @node Setting Address | |
387 | @subsection Setting the Address of a Socket | |
388 | ||
389 | @pindex sys/socket.h | |
390 | Use the @code{bind} function to assign an address to a socket. The | |
391 | prototype for @code{bind} is in the header file @file{sys/socket.h}. | |
4bca4c17 | 392 | For examples of use, see @ref{Local Socket Example}, or see @ref{Inet Example}. |
28f540f4 RM |
393 | |
394 | @comment sys/socket.h | |
395 | @comment BSD | |
55c14926 | 396 | @deftypefun int bind (int @var{socket}, struct sockaddr *@var{addr}, socklen_t @var{length}) |
973f180b AO |
397 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
398 | @c Direct syscall, except on Hurd. | |
28f540f4 RM |
399 | The @code{bind} function assigns an address to the socket |
400 | @var{socket}. The @var{addr} and @var{length} arguments specify the | |
401 | address; the detailed format of the address depends on the namespace. | |
402 | The first part of the address is always the format designator, which | |
04b9968b | 403 | specifies a namespace, and says that the address is in the format of |
28f540f4 RM |
404 | that namespace. |
405 | ||
406 | The return value is @code{0} on success and @code{-1} on failure. The | |
407 | following @code{errno} error conditions are defined for this function: | |
408 | ||
409 | @table @code | |
410 | @item EBADF | |
411 | The @var{socket} argument is not a valid file descriptor. | |
412 | ||
413 | @item ENOTSOCK | |
414 | The descriptor @var{socket} is not a socket. | |
415 | ||
416 | @item EADDRNOTAVAIL | |
417 | The specified address is not available on this machine. | |
418 | ||
419 | @item EADDRINUSE | |
420 | Some other socket is already using the specified address. | |
421 | ||
422 | @item EINVAL | |
423 | The socket @var{socket} already has an address. | |
424 | ||
425 | @item EACCES | |
426 | You do not have permission to access the requested address. (In the | |
427 | Internet domain, only the super-user is allowed to specify a port number | |
428 | in the range 0 through @code{IPPORT_RESERVED} minus one; see | |
429 | @ref{Ports}.) | |
430 | @end table | |
431 | ||
432 | Additional conditions may be possible depending on the particular namespace | |
433 | of the socket. | |
434 | @end deftypefun | |
435 | ||
436 | @node Reading Address | |
437 | @subsection Reading the Address of a Socket | |
438 | ||
439 | @pindex sys/socket.h | |
440 | Use the function @code{getsockname} to examine the address of an | |
441 | Internet socket. The prototype for this function is in the header file | |
442 | @file{sys/socket.h}. | |
443 | ||
444 | @comment sys/socket.h | |
445 | @comment BSD | |
55c14926 | 446 | @deftypefun int getsockname (int @var{socket}, struct sockaddr *@var{addr}, socklen_t *@var{length-ptr}) |
973f180b AO |
447 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsmem{/hurd}}} |
448 | @c Direct syscall, except on Hurd, where it seems like it might leak | |
449 | @c VM if cancelled. | |
28f540f4 RM |
450 | The @code{getsockname} function returns information about the |
451 | address of the socket @var{socket} in the locations specified by the | |
452 | @var{addr} and @var{length-ptr} arguments. Note that the | |
453 | @var{length-ptr} is a pointer; you should initialize it to be the | |
454 | allocation size of @var{addr}, and on return it contains the actual | |
455 | size of the address data. | |
456 | ||
457 | The format of the address data depends on the socket namespace. The | |
458 | length of the information is usually fixed for a given namespace, so | |
459 | normally you can know exactly how much space is needed and can provide | |
460 | that much. The usual practice is to allocate a place for the value | |
461 | using the proper data type for the socket's namespace, then cast its | |
462 | address to @code{struct sockaddr *} to pass it to @code{getsockname}. | |
463 | ||
464 | The return value is @code{0} on success and @code{-1} on error. The | |
465 | following @code{errno} error conditions are defined for this function: | |
466 | ||
467 | @table @code | |
468 | @item EBADF | |
469 | The @var{socket} argument is not a valid file descriptor. | |
470 | ||
471 | @item ENOTSOCK | |
472 | The descriptor @var{socket} is not a socket. | |
473 | ||
474 | @item ENOBUFS | |
475 | There are not enough internal buffers available for the operation. | |
476 | @end table | |
477 | @end deftypefun | |
478 | ||
479 | You can't read the address of a socket in the file namespace. This is | |
480 | consistent with the rest of the system; in general, there's no way to | |
481 | find a file's name from a descriptor for that file. | |
482 | ||
4bca4c17 UD |
483 | @node Interface Naming |
484 | @section Interface Naming | |
485 | ||
486 | Each network interface has a name. This usually consists of a few | |
487 | letters that relate to the type of interface, which may be followed by a | |
488 | number if there is more than one interface of that type. Examples | |
489 | might be @code{lo} (the loopback interface) and @code{eth0} (the first | |
490 | Ethernet interface). | |
491 | ||
492 | Although such names are convenient for humans, it would be clumsy to | |
356d7100 | 493 | have to use them whenever a program needs to refer to an interface. In |
4bca4c17 UD |
494 | such situations an interface is referred to by its @dfn{index}, which is |
495 | an arbitrarily-assigned small positive integer. | |
496 | ||
497 | The following functions, constants and data types are declared in the | |
498 | header file @file{net/if.h}. | |
499 | ||
500 | @comment net/if.h | |
501 | @deftypevr Constant size_t IFNAMSIZ | |
502 | This constant defines the maximum buffer size needed to hold an | |
503 | interface name, including its terminating zero byte. | |
504 | @end deftypevr | |
505 | ||
506 | @comment net/if.h | |
507 | @comment IPv6 basic API | |
cc6e48bc | 508 | @deftypefun {unsigned int} if_nametoindex (const char *@var{ifname}) |
973f180b AO |
509 | @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{}}} |
510 | @c It opens a socket to use ioctl on the fd to get the index. | |
511 | @c opensock may call socket and access multiple times until it finds a | |
512 | @c socket family that works. The Linux implementation has a potential | |
513 | @c concurrency issue WRT last_type and last_family not being updated | |
514 | @c atomically, but it is harmless; the generic implementation, OTOH, | |
515 | @c takes a lock, which makes all callers AS- and AC-Unsafe. | |
516 | @c opensock @asulock @aculock @acsfd | |
4bca4c17 UD |
517 | This function yields the interface index corresponding to a particular |
518 | name. If no interface exists with the name given, it returns 0. | |
519 | @end deftypefun | |
520 | ||
521 | @comment net/if.h | |
522 | @comment IPv6 basic API | |
cc6e48bc | 523 | @deftypefun {char *} if_indextoname (unsigned int @var{ifindex}, char *@var{ifname}) |
973f180b AO |
524 | @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{}}} |
525 | @c It opens a socket with opensock to use ioctl on the fd to get the | |
526 | @c name from the index. | |
4bca4c17 UD |
527 | This function maps an interface index to its corresponding name. The |
528 | returned name is placed in the buffer pointed to by @code{ifname}, which | |
acdacef9 | 529 | must be at least @code{IFNAMSIZ} bytes in length. If the index was |
4bca4c17 UD |
530 | invalid, the function's return value is a null pointer, otherwise it is |
531 | @code{ifname}. | |
532 | @end deftypefun | |
533 | ||
534 | @comment net/if.h | |
535 | @comment IPv6 basic API | |
536 | @deftp {Data Type} {struct if_nameindex} | |
537 | This data type is used to hold the information about a single | |
538 | interface. It has the following members: | |
539 | ||
540 | @table @code | |
541 | @item unsigned int if_index; | |
542 | This is the interface index. | |
543 | ||
544 | @item char *if_name | |
545 | This is the null-terminated index name. | |
546 | ||
547 | @end table | |
548 | @end deftp | |
549 | ||
550 | @comment net/if.h | |
551 | @comment IPv6 basic API | |
310b3460 | 552 | @deftypefun {struct if_nameindex *} if_nameindex (void) |
973f180b AO |
553 | @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{/hurd}}@acunsafe{@aculock{/hurd} @acsfd{} @acsmem{}}} |
554 | @c if_nameindex @ascuheap @asulock/hurd @aculock/hurd @acsfd @acsmem | |
555 | @c [linux] | |
556 | @c netlink_open @acsfd @acsmem/hurd | |
557 | @c socket dup @acsfd | |
558 | @c memset dup ok | |
559 | @c bind dup ok | |
560 | @c netlink_close dup @acsfd | |
561 | @c getsockname dup @acsmem/hurd | |
562 | @c netlink_request @ascuheap @acsmem | |
563 | @c getpagesize dup ok | |
564 | @c malloc dup @ascuheap @acsmem | |
565 | @c netlink_sendreq ok | |
566 | @c memset dup ok | |
567 | @c sendto dup ok | |
568 | @c recvmsg dup ok | |
569 | @c memcpy dup ok | |
570 | @c free dup @ascuheap @acsmem | |
571 | @c netlink_free_handle @ascuheap @acsmem | |
572 | @c free dup @ascuheap @acsmem | |
573 | @c netlink_close @acsfd | |
574 | @c close dup @acsfd | |
575 | @c malloc dup @asuheap @acsmem | |
576 | @c strndup @ascuheap @acsmem | |
577 | @c if_freenameindex @ascuheap @acsmem | |
578 | @c [hurd] | |
579 | @c opensock dup @asulock @aculock @acsfd | |
580 | @c hurd_socket_server ok | |
581 | @c pfinet_siocgifconf ok | |
582 | @c malloc @ascuheap @acsmem | |
583 | @c strdup @ascuheap @acsmem | |
584 | @c ioctl dup ok | |
585 | @c free @ascuheap @acsmem | |
4bca4c17 UD |
586 | This function returns an array of @code{if_nameindex} structures, one |
587 | for every interface that is present. The end of the list is indicated | |
588 | by a structure with an interface of 0 and a null name pointer. If an | |
589 | error occurs, this function returns a null pointer. | |
590 | ||
591 | The returned structure must be freed with @code{if_freenameindex} after | |
592 | use. | |
593 | @end deftypefun | |
594 | ||
595 | @comment net/if.h | |
596 | @comment IPv6 basic API | |
cc6e48bc | 597 | @deftypefun void if_freenameindex (struct if_nameindex *@var{ptr}) |
973f180b AO |
598 | @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} |
599 | @c if_freenameindex @ascuheap @acsmem | |
600 | @c free dup @ascuheap @acsmem | |
4bca4c17 UD |
601 | This function frees the structure returned by an earlier call to |
602 | @code{if_nameindex}. | |
603 | @end deftypefun | |
604 | ||
605 | @node Local Namespace | |
606 | @section The Local Namespace | |
607 | @cindex local namespace, for sockets | |
28f540f4 | 608 | |
4bca4c17 UD |
609 | This section describes the details of the local namespace, whose |
610 | symbolic name (required when you create a socket) is @code{PF_LOCAL}. | |
611 | The local namespace is also known as ``Unix domain sockets''. Another | |
612 | name is file namespace since socket addresses are normally implemented | |
613 | as file names. | |
28f540f4 RM |
614 | |
615 | @menu | |
4bca4c17 UD |
616 | * Concepts: Local Namespace Concepts. What you need to understand. |
617 | * Details: Local Namespace Details. Address format, symbolic names, etc. | |
618 | * Example: Local Socket Example. Example of creating a socket. | |
28f540f4 RM |
619 | @end menu |
620 | ||
4bca4c17 UD |
621 | @node Local Namespace Concepts |
622 | @subsection Local Namespace Concepts | |
28f540f4 | 623 | |
04b9968b | 624 | In the local namespace socket addresses are file names. You can specify |
28f540f4 | 625 | any file name you want as the address of the socket, but you must have |
59a8849d UD |
626 | write permission on the directory containing it. |
627 | @c XXX The following was said to be wrong. | |
628 | @c In order to connect to a socket you must have read permission for it. | |
629 | It's common to put these files in the @file{/tmp} directory. | |
28f540f4 | 630 | |
04b9968b UD |
631 | One peculiarity of the local namespace is that the name is only used |
632 | when opening the connection; once open the address is not meaningful and | |
633 | may not exist. | |
28f540f4 RM |
634 | |
635 | Another peculiarity is that you cannot connect to such a socket from | |
636 | another machine--not even if the other machine shares the file system | |
637 | which contains the name of the socket. You can see the socket in a | |
638 | directory listing, but connecting to it never succeeds. Some programs | |
639 | take advantage of this, such as by asking the client to send its own | |
640 | process ID, and using the process IDs to distinguish between clients. | |
04b9968b | 641 | However, we recommend you not use this method in protocols you design, |
28f540f4 RM |
642 | as we might someday permit connections from other machines that mount |
643 | the same file systems. Instead, send each new client an identifying | |
644 | number if you want it to have one. | |
645 | ||
4bca4c17 | 646 | After you close a socket in the local namespace, you should delete the |
28f540f4 RM |
647 | file name from the file system. Use @code{unlink} or @code{remove} to |
648 | do this; see @ref{Deleting Files}. | |
649 | ||
4bca4c17 | 650 | The local namespace supports just one protocol for any communication |
28f540f4 RM |
651 | style; it is protocol number @code{0}. |
652 | ||
4bca4c17 UD |
653 | @node Local Namespace Details |
654 | @subsection Details of Local Namespace | |
28f540f4 RM |
655 | |
656 | @pindex sys/socket.h | |
4bca4c17 UD |
657 | To create a socket in the local namespace, use the constant |
658 | @code{PF_LOCAL} as the @var{namespace} argument to @code{socket} or | |
28f540f4 RM |
659 | @code{socketpair}. This constant is defined in @file{sys/socket.h}. |
660 | ||
661 | @comment sys/socket.h | |
4bca4c17 UD |
662 | @comment POSIX |
663 | @deftypevr Macro int PF_LOCAL | |
664 | This designates the local namespace, in which socket addresses are local | |
665 | names, and its associated family of protocols. @code{PF_Local} is the | |
666 | macro used by Posix.1g. | |
28f540f4 RM |
667 | @end deftypevr |
668 | ||
669 | @comment sys/socket.h | |
670 | @comment BSD | |
671 | @deftypevr Macro int PF_UNIX | |
4bca4c17 | 672 | This is a synonym for @code{PF_LOCAL}, for compatibility's sake. |
28f540f4 RM |
673 | @end deftypevr |
674 | ||
4bca4c17 UD |
675 | @comment sys/socket.h |
676 | @comment GNU | |
677 | @deftypevr Macro int PF_FILE | |
678 | This is a synonym for @code{PF_LOCAL}, for compatibility's sake. | |
679 | @end deftypevr | |
680 | ||
681 | The structure for specifying socket names in the local namespace is | |
28f540f4 RM |
682 | defined in the header file @file{sys/un.h}: |
683 | @pindex sys/un.h | |
684 | ||
685 | @comment sys/un.h | |
686 | @comment BSD | |
687 | @deftp {Data Type} {struct sockaddr_un} | |
4bca4c17 | 688 | This structure is used to specify local namespace socket addresses. It has |
28f540f4 RM |
689 | the following members: |
690 | ||
691 | @table @code | |
692 | @item short int sun_family | |
693 | This identifies the address family or format of the socket address. | |
4bca4c17 | 694 | You should store the value @code{AF_LOCAL} to designate the local |
28f540f4 RM |
695 | namespace. @xref{Socket Addresses}. |
696 | ||
697 | @item char sun_path[108] | |
698 | This is the file name to use. | |
699 | ||
700 | @strong{Incomplete:} Why is 108 a magic number? RMS suggests making | |
04b9968b | 701 | this a zero-length array and tweaking the following example to use |
28f540f4 RM |
702 | @code{alloca} to allocate an appropriate amount of storage based on |
703 | the length of the filename. | |
704 | @end table | |
705 | @end deftp | |
706 | ||
707 | You should compute the @var{length} parameter for a socket address in | |
4bca4c17 | 708 | the local namespace as the sum of the size of the @code{sun_family} |
28f540f4 | 709 | component and the string length (@emph{not} the allocation size!) of |
4bca4c17 | 710 | the file name string. This can be done using the macro @code{SUN_LEN}: |
28f540f4 | 711 | |
4bca4c17 UD |
712 | @comment sys/un.h |
713 | @comment BSD | |
73237de3 | 714 | @deftypefn {Macro} int SUN_LEN (@emph{struct sockaddr_un *} @var{ptr}) |
973f180b | 715 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
4bca4c17 UD |
716 | The macro computes the length of socket address in the local namespace. |
717 | @end deftypefn | |
28f540f4 | 718 | |
4bca4c17 UD |
719 | @node Local Socket Example |
720 | @subsection Example of Local-Namespace Sockets | |
721 | ||
722 | Here is an example showing how to create and name a socket in the local | |
28f540f4 RM |
723 | namespace. |
724 | ||
725 | @smallexample | |
726 | @include mkfsock.c.texi | |
727 | @end smallexample | |
728 | ||
729 | @node Internet Namespace | |
730 | @section The Internet Namespace | |
731 | @cindex Internet namespace, for sockets | |
732 | ||
4bca4c17 | 733 | This section describes the details of the protocols and socket naming |
28f540f4 RM |
734 | conventions used in the Internet namespace. |
735 | ||
04b9968b | 736 | Originally the Internet namespace used only IP version 4 (IPv4). With |
4bca4c17 | 737 | the growing number of hosts on the Internet, a new protocol with a |
04b9968b UD |
738 | larger address space was necessary: IP version 6 (IPv6). IPv6 |
739 | introduces 128-bit addresses (IPv4 has 32-bit addresses) and other | |
740 | features, and will eventually replace IPv4. | |
4bca4c17 UD |
741 | |
742 | To create a socket in the IPv4 Internet namespace, use the symbolic name | |
28f540f4 | 743 | @code{PF_INET} of this namespace as the @var{namespace} argument to |
04b9968b | 744 | @code{socket} or @code{socketpair}. For IPv6 addresses you need the |
cf822e3c | 745 | macro @code{PF_INET6}. These macros are defined in @file{sys/socket.h}. |
28f540f4 RM |
746 | @pindex sys/socket.h |
747 | ||
748 | @comment sys/socket.h | |
749 | @comment BSD | |
750 | @deftypevr Macro int PF_INET | |
4bca4c17 UD |
751 | This designates the IPv4 Internet namespace and associated family of |
752 | protocols. | |
753 | @end deftypevr | |
754 | ||
04b9968b UD |
755 | @comment sys/socket.h |
756 | @comment X/Open | |
757 | @deftypevr Macro int PF_INET6 | |
4bca4c17 | 758 | This designates the IPv6 Internet namespace and associated family of |
28f540f4 RM |
759 | protocols. |
760 | @end deftypevr | |
761 | ||
762 | A socket address for the Internet namespace includes the following components: | |
763 | ||
764 | @itemize @bullet | |
765 | @item | |
766 | The address of the machine you want to connect to. Internet addresses | |
767 | can be specified in several ways; these are discussed in @ref{Internet | |
04b9968b | 768 | Address Formats}, @ref{Host Addresses} and @ref{Host Names}. |
28f540f4 RM |
769 | |
770 | @item | |
771 | A port number for that machine. @xref{Ports}. | |
772 | @end itemize | |
773 | ||
774 | You must ensure that the address and port number are represented in a | |
775 | canonical format called @dfn{network byte order}. @xref{Byte Order}, | |
776 | for information about this. | |
777 | ||
778 | @menu | |
3996f34b | 779 | * Internet Address Formats:: How socket addresses are specified in the |
28f540f4 | 780 | Internet namespace. |
04b9968b | 781 | * Host Addresses:: All about host addresses of Internet host. |
28f540f4 RM |
782 | * Ports:: Internet port numbers. |
783 | * Services Database:: Ports may have symbolic names. | |
784 | * Byte Order:: Different hosts may use different byte | |
785 | ordering conventions; you need to | |
6e953631 | 786 | canonicalize host address and port number. |
faf6f8bc | 787 | * Protocols Database:: Referring to protocols by name. |
28f540f4 RM |
788 | * Inet Example:: Putting it all together. |
789 | @end menu | |
790 | ||
3996f34b UD |
791 | @node Internet Address Formats |
792 | @subsection Internet Socket Address Formats | |
28f540f4 | 793 | |
3996f34b UD |
794 | In the Internet namespace, for both IPv4 (@code{AF_INET}) and IPv6 |
795 | (@code{AF_INET6}), a socket address consists of a host address | |
28f540f4 RM |
796 | and a port on that host. In addition, the protocol you choose serves |
797 | effectively as a part of the address because local port numbers are | |
798 | meaningful only within a particular protocol. | |
799 | ||
3996f34b UD |
800 | The data types for representing socket addresses in the Internet namespace |
801 | are defined in the header file @file{netinet/in.h}. | |
28f540f4 RM |
802 | @pindex netinet/in.h |
803 | ||
804 | @comment netinet/in.h | |
805 | @comment BSD | |
806 | @deftp {Data Type} {struct sockaddr_in} | |
807 | This is the data type used to represent socket addresses in the | |
808 | Internet namespace. It has the following members: | |
809 | ||
810 | @table @code | |
4bca4c17 | 811 | @item sa_family_t sin_family |
28f540f4 | 812 | This identifies the address family or format of the socket address. |
04b9968b | 813 | You should store the value @code{AF_INET} in this member. |
28f540f4 RM |
814 | @xref{Socket Addresses}. |
815 | ||
816 | @item struct in_addr sin_addr | |
817 | This is the Internet address of the host machine. @xref{Host | |
818 | Addresses}, and @ref{Host Names}, for how to get a value to store | |
819 | here. | |
820 | ||
821 | @item unsigned short int sin_port | |
822 | This is the port number. @xref{Ports}. | |
823 | @end table | |
824 | @end deftp | |
825 | ||
826 | When you call @code{bind} or @code{getsockname}, you should specify | |
827 | @code{sizeof (struct sockaddr_in)} as the @var{length} parameter if | |
4bca4c17 | 828 | you are using an IPv4 Internet namespace socket address. |
28f540f4 | 829 | |
3996f34b UD |
830 | @deftp {Data Type} {struct sockaddr_in6} |
831 | This is the data type used to represent socket addresses in the IPv6 | |
832 | namespace. It has the following members: | |
833 | ||
834 | @table @code | |
4bca4c17 | 835 | @item sa_family_t sin6_family |
3996f34b UD |
836 | This identifies the address family or format of the socket address. |
837 | You should store the value of @code{AF_INET6} in this member. | |
838 | @xref{Socket Addresses}. | |
839 | ||
840 | @item struct in6_addr sin6_addr | |
841 | This is the IPv6 address of the host machine. @xref{Host | |
842 | Addresses}, and @ref{Host Names}, for how to get a value to store | |
843 | here. | |
844 | ||
845 | @item uint32_t sin6_flowinfo | |
846 | This is a currently unimplemented field. | |
847 | ||
848 | @item uint16_t sin6_port | |
849 | This is the port number. @xref{Ports}. | |
850 | ||
851 | @end table | |
852 | @end deftp | |
853 | ||
28f540f4 RM |
854 | @node Host Addresses |
855 | @subsection Host Addresses | |
856 | ||
857 | Each computer on the Internet has one or more @dfn{Internet addresses}, | |
858 | numbers which identify that computer among all those on the Internet. | |
3996f34b UD |
859 | Users typically write IPv4 numeric host addresses as sequences of four |
860 | numbers, separated by periods, as in @samp{128.52.46.32}, and IPv6 | |
f2ea0f5b | 861 | numeric host addresses as sequences of up to eight numbers separated by |
3996f34b | 862 | colons, as in @samp{5f03:1200:836f:c100::1}. |
28f540f4 RM |
863 | |
864 | Each computer also has one or more @dfn{host names}, which are strings | |
1d3c8572 | 865 | of words separated by periods, as in @samp{www.gnu.org}. |
28f540f4 RM |
866 | |
867 | Programs that let the user specify a host typically accept both numeric | |
04b9968b UD |
868 | addresses and host names. To open a connection a program needs a |
869 | numeric address, and so must convert a host name to the numeric address | |
870 | it stands for. | |
28f540f4 RM |
871 | |
872 | @menu | |
873 | * Abstract Host Addresses:: What a host number consists of. | |
874 | * Data type: Host Address Data Type. Data type for a host number. | |
875 | * Functions: Host Address Functions. Functions to operate on them. | |
876 | * Names: Host Names. Translating host names to host numbers. | |
877 | @end menu | |
878 | ||
6e953631 | 879 | @node Abstract Host Addresses |
28f540f4 RM |
880 | @subsubsection Internet Host Addresses |
881 | @cindex host address, Internet | |
882 | @cindex Internet host address | |
883 | ||
884 | @ifinfo | |
885 | Each computer on the Internet has one or more Internet addresses, | |
886 | numbers which identify that computer among all those on the Internet. | |
887 | @end ifinfo | |
888 | ||
889 | @cindex network number | |
890 | @cindex local network address number | |
4bca4c17 UD |
891 | An IPv4 Internet host address is a number containing four bytes of data. |
892 | Historically these are divided into two parts, a @dfn{network number} and a | |
893 | @dfn{local network address number} within that network. In the | |
04b9968b | 894 | mid-1990s classless addresses were introduced which changed this |
0bc93a2f | 895 | behavior. Since some functions implicitly expect the old definitions, |
04b9968b UD |
896 | we first describe the class-based network and will then describe |
897 | classless addresses. IPv6 uses only classless addresses and therefore | |
4bca4c17 UD |
898 | the following paragraphs don't apply. |
899 | ||
04b9968b | 900 | The class-based IPv4 network number consists of the first one, two or |
4bca4c17 UD |
901 | three bytes; the rest of the bytes are the local address. |
902 | ||
903 | IPv4 network numbers are registered with the Network Information Center | |
04b9968b | 904 | (NIC), and are divided into three classes---A, B and C. The local |
28f540f4 RM |
905 | network address numbers of individual machines are registered with the |
906 | administrator of the particular network. | |
907 | ||
908 | Class A networks have single-byte numbers in the range 0 to 127. There | |
909 | are only a small number of Class A networks, but they can each support a | |
910 | very large number of hosts. Medium-sized Class B networks have two-byte | |
911 | network numbers, with the first byte in the range 128 to 191. Class C | |
912 | networks are the smallest; they have three-byte network numbers, with | |
913 | the first byte in the range 192-255. Thus, the first 1, 2, or 3 bytes | |
04b9968b | 914 | of an Internet address specify a network. The remaining bytes of the |
28f540f4 RM |
915 | Internet address specify the address within that network. |
916 | ||
917 | The Class A network 0 is reserved for broadcast to all networks. In | |
6e953631 | 918 | addition, the host number 0 within each network is reserved for broadcast |
04b9968b | 919 | to all hosts in that network. These uses are obsolete now but for |
4bca4c17 | 920 | compatibility reasons you shouldn't use network 0 and host number 0. |
28f540f4 RM |
921 | |
922 | The Class A network 127 is reserved for loopback; you can always use | |
923 | the Internet address @samp{127.0.0.1} to refer to the host machine. | |
924 | ||
925 | Since a single machine can be a member of multiple networks, it can | |
926 | have multiple Internet host addresses. However, there is never | |
927 | supposed to be more than one machine with the same host address. | |
928 | ||
929 | @c !!! this section could document the IN_CLASS* macros in <netinet/in.h>. | |
4bca4c17 | 930 | @c No, it shouldn't since they're obsolete. |
28f540f4 RM |
931 | |
932 | @cindex standard dot notation, for Internet addresses | |
933 | @cindex dot notation, for Internet addresses | |
934 | There are four forms of the @dfn{standard numbers-and-dots notation} | |
935 | for Internet addresses: | |
936 | ||
937 | @table @code | |
938 | @item @var{a}.@var{b}.@var{c}.@var{d} | |
4bca4c17 UD |
939 | This specifies all four bytes of the address individually and is the |
940 | commonly used representation. | |
28f540f4 RM |
941 | |
942 | @item @var{a}.@var{b}.@var{c} | |
943 | The last part of the address, @var{c}, is interpreted as a 2-byte quantity. | |
944 | This is useful for specifying host addresses in a Class B network with | |
945 | network address number @code{@var{a}.@var{b}}. | |
946 | ||
947 | @item @var{a}.@var{b} | |
4bca4c17 | 948 | The last part of the address, @var{b}, is interpreted as a 3-byte quantity. |
28f540f4 RM |
949 | This is useful for specifying host addresses in a Class A network with |
950 | network address number @var{a}. | |
951 | ||
952 | @item @var{a} | |
953 | If only one part is given, this corresponds directly to the host address | |
954 | number. | |
955 | @end table | |
956 | ||
957 | Within each part of the address, the usual C conventions for specifying | |
958 | the radix apply. In other words, a leading @samp{0x} or @samp{0X} implies | |
959 | hexadecimal radix; a leading @samp{0} implies octal; and otherwise decimal | |
960 | radix is assumed. | |
961 | ||
4bca4c17 UD |
962 | @subsubheading Classless Addresses |
963 | ||
04b9968b UD |
964 | IPv4 addresses (and IPv6 addresses also) are now considered classless; |
965 | the distinction between classes A, B and C can be ignored. Instead an | |
966 | IPv4 host address consists of a 32-bit address and a 32-bit mask. The | |
967 | mask contains set bits for the network part and cleared bits for the | |
968 | host part. The network part is contiguous from the left, with the | |
969 | remaining bits representing the host. As a consequence, the netmask can | |
970 | simply be specified as the number of set bits. Classes A, B and C are | |
971 | just special cases of this general rule. For example, class A addresses | |
972 | have a netmask of @samp{255.0.0.0} or a prefix length of 8. | |
4bca4c17 UD |
973 | |
974 | Classless IPv4 network addresses are written in numbers-and-dots | |
975 | notation with the prefix length appended and a slash as separator. For | |
976 | example the class A network 10 is written as @samp{10.0.0.0/8}. | |
977 | ||
978 | @subsubheading IPv6 Addresses | |
979 | ||
980 | IPv6 addresses contain 128 bits (IPv4 has 32 bits) of data. A host | |
981 | address is usually written as eight 16-bit hexadecimal numbers that are | |
73237de3 | 982 | separated by colons. Two colons are used to abbreviate strings of |
04b9968b UD |
983 | consecutive zeros. For example, the IPv6 loopback address |
984 | @samp{0:0:0:0:0:0:0:1} can just be written as @samp{::1}. | |
4bca4c17 | 985 | |
28f540f4 RM |
986 | @node Host Address Data Type |
987 | @subsubsection Host Address Data Type | |
988 | ||
4bca4c17 UD |
989 | IPv4 Internet host addresses are represented in some contexts as integers |
990 | (type @code{uint32_t}). In other contexts, the integer is | |
28f540f4 RM |
991 | packaged inside a structure of type @code{struct in_addr}. It would |
992 | be better if the usage were made consistent, but it is not hard to extract | |
993 | the integer from the structure or put the integer into a structure. | |
994 | ||
4bca4c17 UD |
995 | You will find older code that uses @code{unsigned long int} for |
996 | IPv4 Internet host addresses instead of @code{uint32_t} or @code{struct | |
04b9968b UD |
997 | in_addr}. Historically @code{unsigned long int} was a 32-bit number but |
998 | with 64-bit machines this has changed. Using @code{unsigned long int} | |
4bca4c17 UD |
999 | might break the code if it is used on machines where this type doesn't |
1000 | have 32 bits. @code{uint32_t} is specified by Unix98 and guaranteed to have | |
1001 | 32 bits. | |
1002 | ||
1003 | IPv6 Internet host addresses have 128 bits and are packaged inside a | |
1004 | structure of type @code{struct in6_addr}. | |
1005 | ||
9afc8a59 UD |
1006 | The following basic definitions for Internet addresses are declared in |
1007 | the header file @file{netinet/in.h}: | |
28f540f4 RM |
1008 | @pindex netinet/in.h |
1009 | ||
1010 | @comment netinet/in.h | |
1011 | @comment BSD | |
1012 | @deftp {Data Type} {struct in_addr} | |
4bca4c17 UD |
1013 | This data type is used in certain contexts to contain an IPv4 Internet |
1014 | host address. It has just one field, named @code{s_addr}, which records | |
1015 | the host address number as an @code{uint32_t}. | |
28f540f4 RM |
1016 | @end deftp |
1017 | ||
1018 | @comment netinet/in.h | |
1019 | @comment BSD | |
4bca4c17 | 1020 | @deftypevr Macro {uint32_t} INADDR_LOOPBACK |
28f540f4 | 1021 | You can use this constant to stand for ``the address of this machine,'' |
4bca4c17 | 1022 | instead of finding its actual address. It is the IPv4 Internet address |
28f540f4 RM |
1023 | @samp{127.0.0.1}, which is usually called @samp{localhost}. This |
1024 | special constant saves you the trouble of looking up the address of your | |
1025 | own machine. Also, the system usually implements @code{INADDR_LOOPBACK} | |
1026 | specially, avoiding any network traffic for the case of one machine | |
1027 | talking to itself. | |
1028 | @end deftypevr | |
1029 | ||
1030 | @comment netinet/in.h | |
1031 | @comment BSD | |
4bca4c17 | 1032 | @deftypevr Macro {uint32_t} INADDR_ANY |
04b9968b | 1033 | You can use this constant to stand for ``any incoming address'' when |
28f540f4 RM |
1034 | binding to an address. @xref{Setting Address}. This is the usual |
1035 | address to give in the @code{sin_addr} member of @w{@code{struct | |
1036 | sockaddr_in}} when you want to accept Internet connections. | |
1037 | @end deftypevr | |
1038 | ||
1039 | @comment netinet/in.h | |
1040 | @comment BSD | |
4bca4c17 | 1041 | @deftypevr Macro {uint32_t} INADDR_BROADCAST |
28f540f4 RM |
1042 | This constant is the address you use to send a broadcast message. |
1043 | @c !!! broadcast needs further documented | |
1044 | @end deftypevr | |
1045 | ||
1046 | @comment netinet/in.h | |
1047 | @comment BSD | |
4bca4c17 | 1048 | @deftypevr Macro {uint32_t} INADDR_NONE |
28f540f4 RM |
1049 | This constant is returned by some functions to indicate an error. |
1050 | @end deftypevr | |
1051 | ||
3996f34b UD |
1052 | @comment netinet/in.h |
1053 | @comment IPv6 basic API | |
1054 | @deftp {Data Type} {struct in6_addr} | |
1055 | This data type is used to store an IPv6 address. It stores 128 bits of | |
1056 | data, which can be accessed (via a union) in a variety of ways. | |
1057 | @end deftp | |
1058 | ||
1059 | @comment netinet/in.h | |
1060 | @comment IPv6 basic API | |
310b3460 | 1061 | @deftypevr Constant {struct in6_addr} in6addr_loopback |
3996f34b UD |
1062 | This constant is the IPv6 address @samp{::1}, the loopback address. See |
1063 | above for a description of what this means. The macro | |
04b9968b | 1064 | @code{IN6ADDR_LOOPBACK_INIT} is provided to allow you to initialize your |
3996f34b UD |
1065 | own variables to this value. |
1066 | @end deftypevr | |
1067 | ||
1068 | @comment netinet/in.h | |
1069 | @comment IPv6 basic API | |
1070 | @deftypevr Constant {struct in6_addr} in6addr_any | |
1071 | This constant is the IPv6 address @samp{::}, the unspecified address. See | |
1072 | above for a description of what this means. The macro | |
04b9968b | 1073 | @code{IN6ADDR_ANY_INIT} is provided to allow you to initialize your |
3996f34b UD |
1074 | own variables to this value. |
1075 | @end deftypevr | |
1076 | ||
28f540f4 RM |
1077 | @node Host Address Functions |
1078 | @subsubsection Host Address Functions | |
1079 | ||
1080 | @pindex arpa/inet.h | |
838e5ffe | 1081 | @noindent |
28f540f4 | 1082 | These additional functions for manipulating Internet addresses are |
9afc8a59 | 1083 | declared in the header file @file{arpa/inet.h}. They represent Internet |
04b9968b | 1084 | addresses in network byte order, and network numbers and |
9afc8a59 UD |
1085 | local-address-within-network numbers in host byte order. @xref{Byte |
1086 | Order}, for an explanation of network and host byte order. | |
28f540f4 RM |
1087 | |
1088 | @comment arpa/inet.h | |
1089 | @comment BSD | |
8f2ece69 | 1090 | @deftypefun int inet_aton (const char *@var{name}, struct in_addr *@var{addr}) |
973f180b AO |
1091 | @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} |
1092 | @c inet_aton @mtslocale | |
1093 | @c isdigit dup @mtslocale | |
1094 | @c strtoul dup @mtslocale | |
1095 | @c isascii dup @mtslocale | |
1096 | @c isspace dup @mtslocale | |
1097 | @c htonl dup ok | |
4bca4c17 | 1098 | This function converts the IPv4 Internet host address @var{name} |
28f540f4 RM |
1099 | from the standard numbers-and-dots notation into binary data and stores |
1100 | it in the @code{struct in_addr} that @var{addr} points to. | |
1101 | @code{inet_aton} returns nonzero if the address is valid, zero if not. | |
1102 | @end deftypefun | |
1103 | ||
1104 | @comment arpa/inet.h | |
1105 | @comment BSD | |
4bca4c17 | 1106 | @deftypefun {uint32_t} inet_addr (const char *@var{name}) |
973f180b AO |
1107 | @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} |
1108 | @c inet_addr @mtslocale | |
1109 | @c inet_aton dup @mtslocale | |
4bca4c17 | 1110 | This function converts the IPv4 Internet host address @var{name} from the |
28f540f4 RM |
1111 | standard numbers-and-dots notation into binary data. If the input is |
1112 | not valid, @code{inet_addr} returns @code{INADDR_NONE}. This is an | |
cf822e3c | 1113 | obsolete interface to @code{inet_aton}, described immediately above. It |
28f540f4 RM |
1114 | is obsolete because @code{INADDR_NONE} is a valid address |
1115 | (255.255.255.255), and @code{inet_aton} provides a cleaner way to | |
1116 | indicate error return. | |
1117 | @end deftypefun | |
1118 | ||
1119 | @comment arpa/inet.h | |
1120 | @comment BSD | |
4bca4c17 | 1121 | @deftypefun {uint32_t} inet_network (const char *@var{name}) |
973f180b AO |
1122 | @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} |
1123 | @c inet_network @mtslocale | |
1124 | @c isdigit dup @mtslocale | |
1125 | @c isxdigit dup @mtslocale | |
1126 | @c tolower dup @mtslocale | |
1127 | @c isspace dup @mtslocale | |
28f540f4 | 1128 | This function extracts the network number from the address @var{name}, |
cf822e3c OB |
1129 | given in the standard numbers-and-dots notation. The returned address is |
1130 | in host order. If the input is not valid, @code{inet_network} returns | |
da2d1bc5 | 1131 | @code{-1}. |
4bca4c17 | 1132 | |
73237de3 | 1133 | The function works only with traditional IPv4 class A, B and C network |
4bca4c17 UD |
1134 | types. It doesn't work with classless addresses and shouldn't be used |
1135 | anymore. | |
28f540f4 RM |
1136 | @end deftypefun |
1137 | ||
1138 | @comment arpa/inet.h | |
1139 | @comment BSD | |
1140 | @deftypefun {char *} inet_ntoa (struct in_addr @var{addr}) | |
973f180b AO |
1141 | @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asurace{}}@acsafe{}} |
1142 | @c inet_ntoa @mtslocale @asurace | |
1143 | @c writes to a thread-local static buffer | |
1144 | @c snprintf @mtslocale [no @ascuheap or @acsmem] | |
4bca4c17 | 1145 | This function converts the IPv4 Internet host address @var{addr} to a |
28f540f4 RM |
1146 | string in the standard numbers-and-dots notation. The return value is |
1147 | a pointer into a statically-allocated buffer. Subsequent calls will | |
1148 | overwrite the same buffer, so you should copy the string if you need | |
1149 | to save it. | |
fe7bdd63 UD |
1150 | |
1151 | In multi-threaded programs each thread has an own statically-allocated | |
1152 | buffer. But still subsequent calls of @code{inet_ntoa} in the same | |
1153 | thread will overwrite the result of the last call. | |
4bca4c17 UD |
1154 | |
1155 | Instead of @code{inet_ntoa} the newer function @code{inet_ntop} which is | |
1156 | described below should be used since it handles both IPv4 and IPv6 | |
1157 | addresses. | |
28f540f4 RM |
1158 | @end deftypefun |
1159 | ||
1160 | @comment arpa/inet.h | |
1161 | @comment BSD | |
4bca4c17 | 1162 | @deftypefun {struct in_addr} inet_makeaddr (uint32_t @var{net}, uint32_t @var{local}) |
973f180b AO |
1163 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
1164 | @c inet_makeaddr ok | |
1165 | @c htonl dup ok | |
4bca4c17 | 1166 | This function makes an IPv4 Internet host address by combining the network |
28f540f4 RM |
1167 | number @var{net} with the local-address-within-network number |
1168 | @var{local}. | |
1169 | @end deftypefun | |
1170 | ||
1171 | @comment arpa/inet.h | |
1172 | @comment BSD | |
4bca4c17 | 1173 | @deftypefun uint32_t inet_lnaof (struct in_addr @var{addr}) |
973f180b AO |
1174 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
1175 | @c inet_lnaof ok | |
1176 | @c ntohl dup ok | |
1177 | @c IN_CLASSA ok | |
1178 | @c IN_CLASSB ok | |
28f540f4 RM |
1179 | This function returns the local-address-within-network part of the |
1180 | Internet host address @var{addr}. | |
4bca4c17 | 1181 | |
73237de3 | 1182 | The function works only with traditional IPv4 class A, B and C network |
4bca4c17 UD |
1183 | types. It doesn't work with classless addresses and shouldn't be used |
1184 | anymore. | |
28f540f4 RM |
1185 | @end deftypefun |
1186 | ||
1187 | @comment arpa/inet.h | |
1188 | @comment BSD | |
4bca4c17 | 1189 | @deftypefun uint32_t inet_netof (struct in_addr @var{addr}) |
973f180b AO |
1190 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
1191 | @c inet_netof ok | |
1192 | @c ntohl dup ok | |
1193 | @c IN_CLASSA ok | |
1194 | @c IN_CLASSB ok | |
28f540f4 RM |
1195 | This function returns the network number part of the Internet host |
1196 | address @var{addr}. | |
4bca4c17 | 1197 | |
73237de3 | 1198 | The function works only with traditional IPv4 class A, B and C network |
4bca4c17 UD |
1199 | types. It doesn't work with classless addresses and shouldn't be used |
1200 | anymore. | |
28f540f4 RM |
1201 | @end deftypefun |
1202 | ||
3996f34b UD |
1203 | @comment arpa/inet.h |
1204 | @comment IPv6 basic API | |
8f2ece69 | 1205 | @deftypefun int inet_pton (int @var{af}, const char *@var{cp}, void *@var{buf}) |
973f180b AO |
1206 | @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} |
1207 | @c inet_pton @mtslocale | |
1208 | @c inet_pton4 ok | |
1209 | @c memcpy dup ok | |
1210 | @c inet_pton6 @mtslocale | |
1211 | @c memset dup ok | |
1212 | @c tolower dup @mtslocale | |
1213 | @c strchr dup ok | |
1214 | @c inet_pton4 dup ok | |
1215 | @c memcpy dup ok | |
3996f34b UD |
1216 | This function converts an Internet address (either IPv4 or IPv6) from |
1217 | presentation (textual) to network (binary) format. @var{af} should be | |
1218 | either @code{AF_INET} or @code{AF_INET6}, as appropriate for the type of | |
1219 | address being converted. @var{cp} is a pointer to the input string, and | |
1220 | @var{buf} is a pointer to a buffer for the result. It is the caller's | |
1221 | responsibility to make sure the buffer is large enough. | |
1222 | @end deftypefun | |
1223 | ||
1224 | @comment arpa/inet.h | |
1225 | @comment IPv6 basic API | |
8ded91fb | 1226 | @deftypefun {const char *} inet_ntop (int @var{af}, const void *@var{cp}, char *@var{buf}, socklen_t @var{len}) |
973f180b AO |
1227 | @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} |
1228 | @c inet_ntop @mtslocale | |
1229 | @c inet_ntop4 @mtslocale | |
1230 | @c sprintf dup @mtslocale [no @ascuheap or @acsmem] | |
1231 | @c strcpy dup ok | |
1232 | @c inet_ntop6 @mtslocale | |
1233 | @c memset dup ok | |
1234 | @c inet_ntop4 dup @mtslocale | |
1235 | @c sprintf dup @mtslocale [no @ascuheap or @acsmem] | |
1236 | @c strcpy dup ok | |
3996f34b UD |
1237 | This function converts an Internet address (either IPv4 or IPv6) from |
1238 | network (binary) to presentation (textual) form. @var{af} should be | |
1239 | either @code{AF_INET} or @code{AF_INET6}, as appropriate. @var{cp} is a | |
1240 | pointer to the address to be converted. @var{buf} should be a pointer | |
1241 | to a buffer to hold the result, and @var{len} is the length of this | |
1242 | buffer. The return value from the function will be this buffer address. | |
1243 | @end deftypefun | |
1244 | ||
28f540f4 RM |
1245 | @node Host Names |
1246 | @subsubsection Host Names | |
1247 | @cindex hosts database | |
1248 | @cindex converting host name to address | |
1249 | @cindex converting host address to name | |
1250 | ||
1251 | Besides the standard numbers-and-dots notation for Internet addresses, | |
1252 | you can also refer to a host by a symbolic name. The advantage of a | |
1253 | symbolic name is that it is usually easier to remember. For example, | |
4bca4c17 UD |
1254 | the machine with Internet address @samp{158.121.106.19} is also known as |
1255 | @samp{alpha.gnu.org}; and other machines in the @samp{gnu.org} | |
1256 | domain can refer to it simply as @samp{alpha}. | |
28f540f4 RM |
1257 | |
1258 | @pindex /etc/hosts | |
1259 | @pindex netdb.h | |
1260 | Internally, the system uses a database to keep track of the mapping | |
1261 | between host names and host numbers. This database is usually either | |
1262 | the file @file{/etc/hosts} or an equivalent provided by a name server. | |
1263 | The functions and other symbols for accessing this database are declared | |
1264 | in @file{netdb.h}. They are BSD features, defined unconditionally if | |
1265 | you include @file{netdb.h}. | |
1266 | ||
1267 | @comment netdb.h | |
1268 | @comment BSD | |
1269 | @deftp {Data Type} {struct hostent} | |
1270 | This data type is used to represent an entry in the hosts database. It | |
1271 | has the following members: | |
1272 | ||
1273 | @table @code | |
1274 | @item char *h_name | |
1275 | This is the ``official'' name of the host. | |
1276 | ||
1277 | @item char **h_aliases | |
1278 | These are alternative names for the host, represented as a null-terminated | |
1279 | vector of strings. | |
1280 | ||
1281 | @item int h_addrtype | |
3996f34b UD |
1282 | This is the host address type; in practice, its value is always either |
1283 | @code{AF_INET} or @code{AF_INET6}, with the latter being used for IPv6 | |
1284 | hosts. In principle other kinds of addresses could be represented in | |
04b9968b | 1285 | the database as well as Internet addresses; if this were done, you |
3996f34b UD |
1286 | might find a value in this field other than @code{AF_INET} or |
1287 | @code{AF_INET6}. @xref{Socket Addresses}. | |
28f540f4 RM |
1288 | |
1289 | @item int h_length | |
1290 | This is the length, in bytes, of each address. | |
1291 | ||
1292 | @item char **h_addr_list | |
1293 | This is the vector of addresses for the host. (Recall that the host | |
1294 | might be connected to multiple networks and have different addresses on | |
1295 | each one.) The vector is terminated by a null pointer. | |
1296 | ||
1297 | @item char *h_addr | |
1298 | This is a synonym for @code{h_addr_list[0]}; in other words, it is the | |
1299 | first host address. | |
1300 | @end table | |
1301 | @end deftp | |
1302 | ||
1303 | As far as the host database is concerned, each address is just a block | |
1304 | of memory @code{h_length} bytes long. But in other contexts there is an | |
4bca4c17 UD |
1305 | implicit assumption that you can convert IPv4 addresses to a |
1306 | @code{struct in_addr} or an @code{uint32_t}. Host addresses in | |
1307 | a @code{struct hostent} structure are always given in network byte | |
1308 | order; see @ref{Byte Order}. | |
28f540f4 | 1309 | |
3996f34b UD |
1310 | You can use @code{gethostbyname}, @code{gethostbyname2} or |
1311 | @code{gethostbyaddr} to search the hosts database for information about | |
1312 | a particular host. The information is returned in a | |
1313 | statically-allocated structure; you must copy the information if you | |
1314 | need to save it across calls. You can also use @code{getaddrinfo} and | |
1315 | @code{getnameinfo} to obtain this information. | |
28f540f4 RM |
1316 | |
1317 | @comment netdb.h | |
1318 | @comment BSD | |
1319 | @deftypefun {struct hostent *} gethostbyname (const char *@var{name}) | |
973f180b AO |
1320 | @safety{@prelim{}@mtunsafe{@mtasurace{:hostbyname} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @asucorrupt{} @ascuheap{} @asulock{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{} @acsfd{}}} |
1321 | @c gethostbyname @mtasurace:hostbyname @mtsenv @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @aculock @acucorrupt @acsmem @acsfd | |
1322 | @c libc_lock_lock dup @asulock @aculock | |
1323 | @c malloc dup @ascuheap @acsmem | |
1324 | @c nss_hostname_digits_dots @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd | |
1325 | @c res_maybe_init(!preinit) @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd | |
1326 | @c res_iclose @acsuheap @acsmem @acsfd | |
1327 | @c close_not_cancel_no_status dup @acsfd | |
1328 | @c free dup @acsuheap @acsmem | |
1329 | @c res_vinit @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd | |
1330 | @c res_randomid ok | |
1331 | @c getpid dup ok | |
1332 | @c getenv dup @mtsenv | |
1333 | @c strncpy dup ok | |
1334 | @c fopen dup @ascuheap @asulock @acsmem @acsfd @aculock | |
1335 | @c fsetlocking dup ok [no concurrent uses] | |
1336 | @c fgets_unlocked dup ok [no concurrent uses] | |
1337 | @c MATCH ok | |
1338 | @c strncmp dup ok | |
1339 | @c strpbrk dup ok | |
1340 | @c strchr dup ok | |
1341 | @c inet_aton dup @mtslocale | |
1342 | @c htons dup | |
1343 | @c inet_pton dup @mtslocale | |
1344 | @c malloc dup @ascuheap @acsmem | |
1345 | @c IN6_IS_ADDR_LINKLOCAL ok | |
1346 | @c htonl dup ok | |
1347 | @c IN6_IS_ADDR_MC_LINKLOCAL ok | |
1348 | @c if_nametoindex dup @asulock @aculock @acsfd | |
1349 | @c strtoul dup @mtslocale | |
1350 | @c ISSORTMASK ok | |
1351 | @c strchr dup ok | |
1352 | @c isascii dup @mtslocale | |
1353 | @c isspace dup @mtslocale | |
1354 | @c net_mask ok | |
1355 | @c ntohl dup ok | |
1356 | @c IN_CLASSA dup ok | |
1357 | @c htonl dup ok | |
1358 | @c IN_CLASSB dup ok | |
1359 | @c res_setoptions @mtslocale | |
1360 | @c strncmp dup ok | |
1361 | @c atoi dup @mtslocale | |
1362 | @c fclose dup @ascuheap @asulock @aculock @acsmem @acsfd | |
1363 | @c inet_makeaddr dup ok | |
1364 | @c gethostname dup ok | |
1365 | @c strcpy dup ok | |
1366 | @c rawmemchr dup ok | |
1367 | @c res_ninit @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd | |
1368 | @c res_vinit dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd | |
1369 | @c isdigit dup @mtslocale | |
1370 | @c isxdigit dup @mtslocale | |
1371 | @c strlen dup ok | |
1372 | @c realloc dup @ascuheap @acsmem | |
1373 | @c free dup @ascuheap @acsmem | |
1374 | @c memset dup ok | |
1375 | @c inet_aton dup @mtslocale | |
1376 | @c inet_pton dup @mtslocale | |
1377 | @c strcpy dup ok | |
1378 | @c memcpy dup ok | |
1379 | @c strchr dup ok | |
1380 | @c gethostbyname_r dup @mtsenv @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @aculock @acucorrupt @acsmem @acsfd | |
1381 | @c realloc dup @ascuheap @acsmem | |
1382 | @c free dup @ascuheap @acsmem | |
1383 | @c libc_lock_unlock dup @aculock | |
1384 | @c set_h_errno ok | |
28f540f4 RM |
1385 | The @code{gethostbyname} function returns information about the host |
1386 | named @var{name}. If the lookup fails, it returns a null pointer. | |
1387 | @end deftypefun | |
1388 | ||
3996f34b UD |
1389 | @comment netdb.h |
1390 | @comment IPv6 Basic API | |
1391 | @deftypefun {struct hostent *} gethostbyname2 (const char *@var{name}, int @var{af}) | |
973f180b AO |
1392 | @safety{@prelim{}@mtunsafe{@mtasurace{:hostbyname2} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @asucorrupt{} @ascuheap{} @asulock{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{} @acsfd{}}} |
1393 | @c gethostbyname2 @mtasurace:hostbyname2 @mtsenv @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @aculock @acucorrupt @acsmem @acsfd | |
1394 | @c libc_lock_lock dup @asulock @aculock | |
1395 | @c malloc dup @ascuheap @acsmem | |
1396 | @c nss_hostname_digits_dots dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd | |
1397 | @c gethostbyname2_r dup @mtsenv @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @aculock @acucorrupt @acsmem @acsfd | |
1398 | @c realloc dup @ascuheap @acsmem | |
1399 | @c free dup @ascuheap @acsmem | |
1400 | @c libc_lock_unlock dup @aculock | |
1401 | @c set_h_errno dup ok | |
3996f34b UD |
1402 | The @code{gethostbyname2} function is like @code{gethostbyname}, but |
1403 | allows the caller to specify the desired address family (e.g.@: | |
04b9968b | 1404 | @code{AF_INET} or @code{AF_INET6}) of the result. |
3996f34b UD |
1405 | @end deftypefun |
1406 | ||
28f540f4 RM |
1407 | @comment netdb.h |
1408 | @comment BSD | |
8ded91fb | 1409 | @deftypefun {struct hostent *} gethostbyaddr (const void *@var{addr}, socklen_t @var{length}, int @var{format}) |
973f180b AO |
1410 | @safety{@prelim{}@mtunsafe{@mtasurace{:hostbyaddr} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @asucorrupt{} @ascuheap{} @asulock{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{} @acsfd{}}} |
1411 | @c gethostbyaddr @mtasurace:hostbyaddr @mtsenv @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @aculock @acucorrupt @acsmem @acsfd | |
1412 | @c libc_lock_lock dup @asulock @aculock | |
1413 | @c malloc dup @ascuheap @acsmem | |
1414 | @c gethostbyaddr_r dup @mtsenv @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @aculock @acucorrupt @acsmem @acsfd | |
1415 | @c realloc dup @ascuheap @acsmem | |
1416 | @c free dup @ascuheap @acsmem | |
1417 | @c libc_lock_unlock dup @aculock | |
1418 | @c set_h_errno dup ok | |
28f540f4 | 1419 | The @code{gethostbyaddr} function returns information about the host |
4bca4c17 UD |
1420 | with Internet address @var{addr}. The parameter @var{addr} is not |
1421 | really a pointer to char - it can be a pointer to an IPv4 or an IPv6 | |
cf822e3c | 1422 | address. The @var{length} argument is the size (in bytes) of the address |
4bca4c17 UD |
1423 | at @var{addr}. @var{format} specifies the address format; for an IPv4 |
1424 | Internet address, specify a value of @code{AF_INET}; for an IPv6 | |
1425 | Internet address, use @code{AF_INET6}. | |
28f540f4 RM |
1426 | |
1427 | If the lookup fails, @code{gethostbyaddr} returns a null pointer. | |
1428 | @end deftypefun | |
1429 | ||
1430 | @vindex h_errno | |
1431 | If the name lookup by @code{gethostbyname} or @code{gethostbyaddr} | |
1432 | fails, you can find out the reason by looking at the value of the | |
1433 | variable @code{h_errno}. (It would be cleaner design for these | |
1434 | functions to set @code{errno}, but use of @code{h_errno} is compatible | |
b99a8a11 | 1435 | with other systems.) |
28f540f4 RM |
1436 | |
1437 | Here are the error codes that you may find in @code{h_errno}: | |
1438 | ||
1439 | @table @code | |
1440 | @comment netdb.h | |
1441 | @comment BSD | |
1442 | @item HOST_NOT_FOUND | |
1443 | @vindex HOST_NOT_FOUND | |
04b9968b | 1444 | No such host is known in the database. |
28f540f4 RM |
1445 | |
1446 | @comment netdb.h | |
1447 | @comment BSD | |
1448 | @item TRY_AGAIN | |
1449 | @vindex TRY_AGAIN | |
1450 | This condition happens when the name server could not be contacted. If | |
1451 | you try again later, you may succeed then. | |
1452 | ||
1453 | @comment netdb.h | |
6e953631 UD |
1454 | @comment BSD |
1455 | @item NO_RECOVERY | |
1456 | @vindex NO_RECOVERY | |
28f540f4 RM |
1457 | A non-recoverable error occurred. |
1458 | ||
1459 | @comment netdb.h | |
1460 | @comment BSD | |
1461 | @item NO_ADDRESS | |
1462 | @vindex NO_ADDRESS | |
1463 | The host database contains an entry for the name, but it doesn't have an | |
1464 | associated Internet address. | |
1465 | @end table | |
1466 | ||
1670698f UD |
1467 | The lookup functions above all have one in common: they are not |
1468 | reentrant and therefore unusable in multi-threaded applications. | |
1f77f049 | 1469 | Therefore provides @theglibc{} a new set of functions which can be |
1670698f UD |
1470 | used in this context. |
1471 | ||
1472 | @comment netdb.h | |
1473 | @comment GNU | |
1474 | @deftypefun int gethostbyname_r (const char *restrict @var{name}, struct hostent *restrict @var{result_buf}, char *restrict @var{buf}, size_t @var{buflen}, struct hostent **restrict @var{result}, int *restrict @var{h_errnop}) | |
973f180b AO |
1475 | @safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @asucorrupt{} @ascuheap{} @asulock{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{} @acsfd{}}} |
1476 | @c gethostbyname_r @mtsenv @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @aculock @acucorrupt @acsmem @acsfd | |
1477 | @c nss_hostname_digits_dots dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd | |
1478 | @c nscd_gethostbyname_r @mtsenv @ascuheap @acsfd @acsmem | |
1479 | @c nscd_gethst_r @mtsenv @ascuheap @acsfd @acsmem | |
1480 | @c getenv dup @mtsenv | |
1481 | @c nscd_get_map_ref dup @ascuheap @acsfd @acsmem | |
1482 | @c nscd_cache_search dup ok | |
1483 | @c memcpy dup ok | |
1484 | @c nscd_open_socket dup @acsfd | |
1485 | @c readvall dup ok | |
1486 | @c readall dup ok | |
1487 | @c close_not_cancel_no_status dup @acsfd | |
1488 | @c nscd_drop_map_ref dup @ascuheap @acsmem | |
1489 | @c nscd_unmap dup @ascuheap @acsmem | |
1490 | @c res_maybe_init(!preinit) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd | |
1491 | @c res_hconf_init @mtsenv @mtslocale @asucorrupt @ascuheap @aculock @acucorrupt @acsmem [no @asuinit:reshconf @acuinit:reshconf, conditionally called] | |
1492 | @c res_hconf.c:do_init @mtsenv @mtslocale @asucorrupt @ascuheap @aculock @acucorrupt @acsmem | |
1493 | @c memset dup ok | |
1494 | @c getenv dup @mtsenv | |
1495 | @c fopen dup @ascuheap @asulock @acsmem @acsfd @aculock | |
1496 | @c fsetlocking dup ok [no concurrent uses] | |
1497 | @c fgets_unlocked dup ok [no concurrent uses] | |
1498 | @c strchrnul dup ok | |
1499 | @c res_hconf.c:parse_line @mtslocale @asucorrupt @ascuheap @aculock @acucorrupt @acsmem | |
1500 | @c skip_ws dup @mtslocale | |
1501 | @c skip_string dup @mtslocale | |
1502 | @c strncasecmp dup @mtslocale | |
1503 | @c strlen dup ok | |
1504 | @c asprintf dup @mtslocale @ascuheap @acsmem | |
1505 | @c fxprintf dup @asucorrupt @aculock @acucorrupt | |
1506 | @c free dup @ascuheap @acsmem | |
1507 | @c arg_trimdomain_list dup @mtslocale @asucorrupt @ascuheap @aculock @acucorrupt @acsmem | |
1508 | @c arg_spoof dup @mtslocale | |
1509 | @c arg_bool dup @mtslocale @asucorrupt @ascuheap @aculock @acucorrupt @acsmem | |
1510 | @c isspace dup @mtslocale | |
1511 | @c fclose dup @ascuheap @asulock @acsmem @acsfd @aculock | |
1512 | @c arg_spoof @mtslocale | |
1513 | @c skip_string @mtslocale | |
1514 | @c isspace dup @mtslocale | |
1515 | @c strncasecmp dup @mtslocale | |
1516 | @c arg_bool @mtslocale @asucorrupt @ascuheap @aculock @acucorrupt @acsmem | |
1517 | @c strncasecmp dup @mtslocale | |
1518 | @c asprintf dup @mtslocale @ascuheap @acsmem | |
1519 | @c fxprintf dup @asucorrupt @aculock @acucorrupt | |
1520 | @c free dup @ascuheap @acsmem | |
1521 | @c arg_trimdomain_list @mtslocale @asucorrupt @ascuheap @aculock @acucorrupt @acsmem | |
1522 | @c skip_string dup @mtslocale | |
1523 | @c asprintf dup @mtslocale @ascuheap @acsmem | |
1524 | @c fxprintf dup @asucorrupt @aculock @acucorrupt | |
1525 | @c free dup @ascuheap @acsmem | |
1526 | @c strndup dup @ascuheap @acsmem | |
1527 | @c skip_ws @mtslocale | |
1528 | @c isspace dup @mtslocale | |
1529 | @c nss_hosts_lookup2 @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
1530 | @c nss_database_lookup dup @mtslocale @ascuheap @asulock @acucorrupt @acsmem @acsfd @aculock | |
1531 | @c nss_lookup dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
1532 | @c *fct.l -> _nss_*_gethostbyname_r @ascuplugin | |
1533 | @c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
1534 | @c res_hconf_reorder_addrs @asulock @ascuheap @aculock @acsmem @acsfd | |
1535 | @c socket dup @acsfd | |
1536 | @c libc_lock_lock dup @asulock @aculock | |
1537 | @c ifreq @ascuheap @acsmem | |
1538 | @c malloc dup @ascuheap @acsmem | |
1539 | @c if_nextreq dup ok | |
1540 | @c ioctl dup ok | |
1541 | @c realloc dup @ascuheap @acsmem | |
1542 | @c if_freereq dup @acsmem | |
1543 | @c libc_lock_unlock dup @aculock | |
1544 | @c close dup @acsfd | |
1670698f UD |
1545 | The @code{gethostbyname_r} function returns information about the host |
1546 | named @var{name}. The caller must pass a pointer to an object of type | |
1547 | @code{struct hostent} in the @var{result_buf} parameter. In addition | |
1548 | the function may need extra buffer space and the caller must pass an | |
1549 | pointer and the size of the buffer in the @var{buf} and @var{buflen} | |
1550 | parameters. | |
1551 | ||
1552 | A pointer to the buffer, in which the result is stored, is available in | |
cf822e3c | 1553 | @code{*@var{result}} after the function call successfully returned. The |
b86835ca YC |
1554 | buffer passed as the @var{buf} parameter can be freed only once the caller |
1555 | has finished with the result hostent struct, or has copied it including all | |
cf822e3c OB |
1556 | the other memory that it points to. If an error occurs or if no entry is |
1557 | found, the pointer @code{*@var{result}} is a null pointer. Success is | |
b86835ca YC |
1558 | signalled by a zero return value. If the function failed the return value |
1559 | is an error number. In addition to the errors defined for | |
cf822e3c OB |
1560 | @code{gethostbyname} it can also be @code{ERANGE}. In this case the call |
1561 | should be repeated with a larger buffer. Additional error information is | |
b86835ca YC |
1562 | not stored in the global variable @code{h_errno} but instead in the object |
1563 | pointed to by @var{h_errnop}. | |
0ea5db4f UD |
1564 | |
1565 | Here's a small example: | |
1566 | @smallexample | |
1567 | struct hostent * | |
1568 | gethostname (char *host) | |
1569 | @{ | |
151659f6 | 1570 | struct hostent *hostbuf, *hp; |
0ea5db4f UD |
1571 | size_t hstbuflen; |
1572 | char *tmphstbuf; | |
1573 | int res; | |
1574 | int herr; | |
1575 | ||
151659f6 | 1576 | hostbuf = malloc (sizeof (struct hostent)); |
0ea5db4f UD |
1577 | hstbuflen = 1024; |
1578 | tmphstbuf = malloc (hstbuflen); | |
1579 | ||
151659f6 | 1580 | while ((res = gethostbyname_r (host, hostbuf, tmphstbuf, hstbuflen, |
0ea5db4f UD |
1581 | &hp, &herr)) == ERANGE) |
1582 | @{ | |
1583 | /* Enlarge the buffer. */ | |
1584 | hstbuflen *= 2; | |
1585 | tmphstbuf = realloc (tmphstbuf, hstbuflen); | |
1586 | @} | |
151659f6 OB |
1587 | |
1588 | free (tmphstbuf); | |
0ea5db4f UD |
1589 | /* Check for errors. */ |
1590 | if (res || hp == NULL) | |
1591 | return NULL; | |
9d8525f2 | 1592 | return hp; |
0ea5db4f UD |
1593 | @} |
1594 | @end smallexample | |
1670698f UD |
1595 | @end deftypefun |
1596 | ||
1597 | @comment netdb.h | |
1598 | @comment GNU | |
1599 | @deftypefun int gethostbyname2_r (const char *@var{name}, int @var{af}, struct hostent *restrict @var{result_buf}, char *restrict @var{buf}, size_t @var{buflen}, struct hostent **restrict @var{result}, int *restrict @var{h_errnop}) | |
973f180b AO |
1600 | @safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @asucorrupt{} @ascuheap{} @asulock{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{} @acsfd{}}} |
1601 | @c gethostbyname2_r @mtsenv @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @aculock @acucorrupt @acsmem @acsfd | |
1602 | @c nss_hostname_digits_dots dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd | |
1603 | @c nscd_gethostbyname2_r @mtsenv @ascuheap @asulock @aculock @acsfd @acsmem | |
1604 | @c nscd_gethst_r dup @mtsenv @ascuheap @asulock @aculock @acsfd @acsmem | |
1605 | @c res_maybe_init(!preinit) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd | |
1606 | @c res_hconf_init dup @mtsenv @mtslocale @asucorrupt @ascuheap @aculock @acucorrupt @acsmem [no @asuinit:reshconf @acuinit:reshconf, conditionally called] | |
1607 | @c nss_hosts_lookup2 dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
1608 | @c *fct.l -> _nss_*_gethostbyname2_r @ascuplugin | |
1609 | @c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
1610 | @c res_hconf_reorder_addrs dup @asulock @ascuheap @aculock @acsmem @acsfd | |
1670698f UD |
1611 | The @code{gethostbyname2_r} function is like @code{gethostbyname_r}, but |
1612 | allows the caller to specify the desired address family (e.g.@: | |
1613 | @code{AF_INET} or @code{AF_INET6}) for the result. | |
1614 | @end deftypefun | |
1615 | ||
1616 | @comment netdb.h | |
1617 | @comment GNU | |
8ded91fb | 1618 | @deftypefun int gethostbyaddr_r (const void *@var{addr}, socklen_t @var{length}, int @var{format}, struct hostent *restrict @var{result_buf}, char *restrict @var{buf}, size_t @var{buflen}, struct hostent **restrict @var{result}, int *restrict @var{h_errnop}) |
973f180b AO |
1619 | @safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @asucorrupt{} @ascuheap{} @asulock{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{} @acsfd{}}} |
1620 | @c gethostbyaddr_r @mtsenv @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @aculock @acucorrupt @acsmem @acsfd | |
1621 | @c memcmp dup ok | |
1622 | @c nscd_gethostbyaddr_r @mtsenv @ascuheap @asulock @aculock @acsfd @acsmem | |
1623 | @c nscd_gethst_r dup @mtsenv @ascuheap @asulock @aculock @acsfd @acsmem | |
1624 | @c res_maybe_init(!preinit) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd | |
1625 | @c res_hconf_init dup @mtsenv @mtslocale @asucorrupt @ascuheap @aculock @acucorrupt @acsmem [no @asuinit:reshconf @acuinit:reshconf, conditionally called] | |
1626 | @c nss_hosts_lookup2 dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
1627 | @c *fct.l -> _nss_*_gethostbyaddr_r @ascuplugin | |
1628 | @c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
1629 | @c res_hconf_reorder_addrs dup @asulock @ascuheap @aculock @acsmem @acsfd | |
1630 | @c res_hconf_trim_domains @mtslocale | |
1631 | @c res_hconf_trim_domain @mtslocale | |
1632 | @c strlen dup ok | |
1633 | @c strcasecmp dup @mtslocale | |
1670698f UD |
1634 | The @code{gethostbyaddr_r} function returns information about the host |
1635 | with Internet address @var{addr}. The parameter @var{addr} is not | |
1636 | really a pointer to char - it can be a pointer to an IPv4 or an IPv6 | |
cf822e3c | 1637 | address. The @var{length} argument is the size (in bytes) of the address |
1670698f UD |
1638 | at @var{addr}. @var{format} specifies the address format; for an IPv4 |
1639 | Internet address, specify a value of @code{AF_INET}; for an IPv6 | |
1640 | Internet address, use @code{AF_INET6}. | |
1641 | ||
1642 | Similar to the @code{gethostbyname_r} function, the caller must provide | |
1643 | buffers for the result and memory used internally. In case of success | |
0ea5db4f | 1644 | the function returns zero. Otherwise the value is an error number where |
1670698f UD |
1645 | @code{ERANGE} has the special meaning that the caller-provided buffer is |
1646 | too small. | |
1647 | @end deftypefun | |
1648 | ||
28f540f4 | 1649 | You can also scan the entire hosts database one entry at a time using |
04b9968b UD |
1650 | @code{sethostent}, @code{gethostent} and @code{endhostent}. Be careful |
1651 | when using these functions because they are not reentrant. | |
28f540f4 RM |
1652 | |
1653 | @comment netdb.h | |
1654 | @comment BSD | |
1655 | @deftypefun void sethostent (int @var{stayopen}) | |
973f180b AO |
1656 | @safety{@prelim{}@mtunsafe{@mtasurace{:hostent} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} |
1657 | @c sethostent @mtasurace:hostent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
1658 | @c libc_lock_lock dup @asulock @aculock | |
1659 | @c nss_setent(nss_hosts_lookup2) @mtasurace:hostent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
1660 | @c res_maybe_init(!preinit) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd | |
1661 | @c set_h_errno dup ok | |
1662 | @c setup(nss_hosts_lookup2) @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
1663 | @c *lookup_fct = nss_hosts_lookup2 dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
1664 | @c nss_lookup dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
1665 | @c *fct.f @mtasurace:hostent @ascuplugin | |
1666 | @c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
1667 | @c libc_lock_unlock dup @aculock | |
28f540f4 RM |
1668 | This function opens the hosts database to begin scanning it. You can |
1669 | then call @code{gethostent} to read the entries. | |
1670 | ||
1671 | @c There was a rumor that this flag has different meaning if using the DNS, | |
1672 | @c but it appears this description is accurate in that case also. | |
1673 | If the @var{stayopen} argument is nonzero, this sets a flag so that | |
1674 | subsequent calls to @code{gethostbyname} or @code{gethostbyaddr} will | |
1675 | not close the database (as they usually would). This makes for more | |
1676 | efficiency if you call those functions several times, by avoiding | |
1677 | reopening the database for each call. | |
1678 | @end deftypefun | |
1679 | ||
1680 | @comment netdb.h | |
1681 | @comment BSD | |
4bca4c17 | 1682 | @deftypefun {struct hostent *} gethostent (void) |
973f180b AO |
1683 | @safety{@prelim{}@mtunsafe{@mtasurace{:hostent} @mtasurace{:hostentbuf} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} |
1684 | @c gethostent @mtasurace:hostent @mtasurace:hostentbuf @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
1685 | @c libc_lock_lock dup @asulock @aculock | |
1686 | @c nss_getent(gethostent_r) @mtasurace:hostent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
1687 | @c malloc dup @ascuheap @acsmem | |
1688 | @c *func = gethostent_r dup @mtasurace:hostent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
1689 | @c realloc dup @ascuheap @acsmem | |
1690 | @c free dup @ascuheap @acsmem | |
1691 | @c libc_lock_unlock dup @aculock | |
1692 | @c | |
1693 | @c gethostent_r @mtasurace:hostent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
1694 | @c libc_lock_lock dup @asulock @aculock | |
1695 | @c nss_getent_r(nss_hosts_lookup2) @mtasurace:hostent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
1696 | @c res_maybe_init(!preinit) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd | |
1697 | @c setup(nss_hosts_lookup2) dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
1698 | @c *fct.f @mtasurace:hostent @ascuplugin | |
1699 | @c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
1700 | @c nss_lookup dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
1701 | @c *sfct.f @mtasurace:hostent @ascuplugin | |
1702 | @c libc_lock_unlock dup @aculock | |
1703 | ||
28f540f4 RM |
1704 | This function returns the next entry in the hosts database. It |
1705 | returns a null pointer if there are no more entries. | |
1706 | @end deftypefun | |
1707 | ||
1708 | @comment netdb.h | |
1709 | @comment BSD | |
4bca4c17 | 1710 | @deftypefun void endhostent (void) |
973f180b AO |
1711 | @safety{@prelim{}@mtunsafe{@mtasurace{:hostent} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} |
1712 | @c endhostent @mtasurace:hostent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
1713 | @c libc_lock_lock @asulock @aculock | |
1714 | @c nss_endent(nss_hosts_lookup2) @mtasurace:hostent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
1715 | @c res_maybe_init(!preinit) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd | |
1716 | @c setup(nss_passwd_lookup2) dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
1717 | @c *fct.f @mtasurace:hostent @ascuplugin | |
1718 | @c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
1719 | @c libc_lock_unlock @aculock | |
28f540f4 RM |
1720 | This function closes the hosts database. |
1721 | @end deftypefun | |
1722 | ||
1723 | @node Ports | |
1724 | @subsection Internet Ports | |
1725 | @cindex port number | |
1726 | ||
1727 | A socket address in the Internet namespace consists of a machine's | |
1728 | Internet address plus a @dfn{port number} which distinguishes the | |
1729 | sockets on a given machine (for a given protocol). Port numbers range | |
1730 | from 0 to 65,535. | |
1731 | ||
1732 | Port numbers less than @code{IPPORT_RESERVED} are reserved for standard | |
1733 | servers, such as @code{finger} and @code{telnet}. There is a database | |
1734 | that keeps track of these, and you can use the @code{getservbyname} | |
1735 | function to map a service name onto a port number; see @ref{Services | |
1736 | Database}. | |
1737 | ||
1738 | If you write a server that is not one of the standard ones defined in | |
1739 | the database, you must choose a port number for it. Use a number | |
1740 | greater than @code{IPPORT_USERRESERVED}; such numbers are reserved for | |
1741 | servers and won't ever be generated automatically by the system. | |
1742 | Avoiding conflicts with servers being run by other users is up to you. | |
1743 | ||
1744 | When you use a socket without specifying its address, the system | |
1745 | generates a port number for it. This number is between | |
1746 | @code{IPPORT_RESERVED} and @code{IPPORT_USERRESERVED}. | |
1747 | ||
1748 | On the Internet, it is actually legitimate to have two different | |
1749 | sockets with the same port number, as long as they never both try to | |
1750 | communicate with the same socket address (host address plus port | |
1751 | number). You shouldn't duplicate a port number except in special | |
1752 | circumstances where a higher-level protocol requires it. Normally, | |
1753 | the system won't let you do it; @code{bind} normally insists on | |
1754 | distinct port numbers. To reuse a port number, you must set the | |
1755 | socket option @code{SO_REUSEADDR}. @xref{Socket-Level Options}. | |
1756 | ||
1757 | @pindex netinet/in.h | |
1758 | These macros are defined in the header file @file{netinet/in.h}. | |
1759 | ||
1760 | @comment netinet/in.h | |
1761 | @comment BSD | |
1762 | @deftypevr Macro int IPPORT_RESERVED | |
1763 | Port numbers less than @code{IPPORT_RESERVED} are reserved for | |
1764 | superuser use. | |
1765 | @end deftypevr | |
1766 | ||
1767 | @comment netinet/in.h | |
1768 | @comment BSD | |
1769 | @deftypevr Macro int IPPORT_USERRESERVED | |
1770 | Port numbers greater than or equal to @code{IPPORT_USERRESERVED} are | |
1771 | reserved for explicit use; they will never be allocated automatically. | |
1772 | @end deftypevr | |
1773 | ||
1774 | @node Services Database | |
1775 | @subsection The Services Database | |
1776 | @cindex services database | |
1777 | @cindex converting service name to port number | |
1778 | @cindex converting port number to service name | |
1779 | ||
1780 | @pindex /etc/services | |
1781 | The database that keeps track of ``well-known'' services is usually | |
1782 | either the file @file{/etc/services} or an equivalent from a name server. | |
1783 | You can use these utilities, declared in @file{netdb.h}, to access | |
1784 | the services database. | |
1785 | @pindex netdb.h | |
1786 | ||
1787 | @comment netdb.h | |
1788 | @comment BSD | |
1789 | @deftp {Data Type} {struct servent} | |
1790 | This data type holds information about entries from the services database. | |
1791 | It has the following members: | |
1792 | ||
1793 | @table @code | |
1794 | @item char *s_name | |
1795 | This is the ``official'' name of the service. | |
1796 | ||
1797 | @item char **s_aliases | |
1798 | These are alternate names for the service, represented as an array of | |
1799 | strings. A null pointer terminates the array. | |
1800 | ||
1801 | @item int s_port | |
1802 | This is the port number for the service. Port numbers are given in | |
1803 | network byte order; see @ref{Byte Order}. | |
1804 | ||
1805 | @item char *s_proto | |
1806 | This is the name of the protocol to use with this service. | |
1807 | @xref{Protocols Database}. | |
1808 | @end table | |
1809 | @end deftp | |
1810 | ||
1811 | To get information about a particular service, use the | |
1812 | @code{getservbyname} or @code{getservbyport} functions. The information | |
1813 | is returned in a statically-allocated structure; you must copy the | |
1814 | information if you need to save it across calls. | |
1815 | ||
1816 | @comment netdb.h | |
1817 | @comment BSD | |
1818 | @deftypefun {struct servent *} getservbyname (const char *@var{name}, const char *@var{proto}) | |
973f180b AO |
1819 | @safety{@prelim{}@mtunsafe{@mtasurace{:servbyname} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} |
1820 | @c getservbyname =~ getpwuid @mtasurace:servbyname @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
1821 | @c libc_lock_lock dup @asulock @aculock | |
1822 | @c malloc dup @ascuheap @acsmem | |
1823 | @c getservbyname_r dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
1824 | @c realloc dup @ascuheap @acsmem | |
1825 | @c free dup @ascuheap @acsmem | |
1826 | @c libc_lock_unlock dup @aculock | |
1827 | @c | |
1828 | @c getservbyname_r =~ getpwuid_r @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
1829 | @c nscd_getservbyname_r @ascuheap @acsfd @acsmem | |
1830 | @c nscd_getserv_r @ascuheap @acsfd @acsmem | |
1831 | @c nscd_get_map_ref dup @ascuheap @acsfd @acsmem | |
1832 | @c strlen dup ok | |
1833 | @c malloc dup @ascuheap @acsmem | |
1834 | @c mempcpy dup ok | |
1835 | @c memcpy dup ok | |
1836 | @c nscd_cache_search dup ok | |
1837 | @c nscd_open_socket dup @acsfd | |
1838 | @c readvall dup ok | |
1839 | @c readall dup ok | |
1840 | @c close_not_cancel_no_status dup @acsfd | |
1841 | @c nscd_drop_map_ref dup @ascuheap @acsmem | |
1842 | @c nscd_unmap dup @ascuheap @acsmem | |
1843 | @c free dup @ascuheap @acsmem | |
1844 | @c nss_services_lookup2 =~ nss_passwd_lookup2 @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
1845 | @c *fct.l -> _nss_*_getservbyname_r @ascuplugin | |
1846 | @c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
28f540f4 RM |
1847 | The @code{getservbyname} function returns information about the |
1848 | service named @var{name} using protocol @var{proto}. If it can't find | |
1849 | such a service, it returns a null pointer. | |
1850 | ||
1851 | This function is useful for servers as well as for clients; servers | |
1852 | use it to determine which port they should listen on (@pxref{Listening}). | |
1853 | @end deftypefun | |
1854 | ||
1855 | @comment netdb.h | |
1856 | @comment BSD | |
1857 | @deftypefun {struct servent *} getservbyport (int @var{port}, const char *@var{proto}) | |
973f180b AO |
1858 | @safety{@prelim{}@mtunsafe{@mtasurace{:servbyport} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} |
1859 | @c getservbyport =~ getservbyname @mtasurace:servbyport @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
1860 | @c libc_lock_lock dup @asulock @aculock | |
1861 | @c malloc dup @ascuheap @acsmem | |
1862 | @c getservbyport_r dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
1863 | @c realloc dup @ascuheap @acsmem | |
1864 | @c free dup @ascuheap @acsmem | |
1865 | @c libc_lock_unlock dup @aculock | |
1866 | @c | |
1867 | @c getservbyport_r =~ getservbyname_r @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
1868 | @c nscd_getservbyport_r @ascuheap @acsfd @acsmem | |
1869 | @c nscd_getserv_r dup @ascuheap @acsfd @acsmem | |
1870 | @c nss_services_lookup2 =~ nss_passwd_lookup2 @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
1871 | @c *fct.l -> _nss_*_getservbyport_r @ascuplugin | |
1872 | @c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
28f540f4 RM |
1873 | The @code{getservbyport} function returns information about the |
1874 | service at port @var{port} using protocol @var{proto}. If it can't | |
1875 | find such a service, it returns a null pointer. | |
1876 | @end deftypefun | |
1877 | ||
838e5ffe | 1878 | @noindent |
28f540f4 | 1879 | You can also scan the services database using @code{setservent}, |
04b9968b UD |
1880 | @code{getservent} and @code{endservent}. Be careful when using these |
1881 | functions because they are not reentrant. | |
28f540f4 RM |
1882 | |
1883 | @comment netdb.h | |
1884 | @comment BSD | |
1885 | @deftypefun void setservent (int @var{stayopen}) | |
973f180b AO |
1886 | @safety{@prelim{}@mtunsafe{@mtasurace{:servent} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} |
1887 | @c setservent @mtasurace:servent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
1888 | @c libc_lock_lock dup @asulock @aculock | |
1889 | @c nss_setent(nss_services_lookup2) @mtasurace:servenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
1890 | @c setup(nss_services_lookup2) @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
1891 | @c *lookup_fct = nss_services_lookup2 dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
1892 | @c nss_lookup dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
1893 | @c *fct.f @mtasurace:servent @ascuplugin | |
1894 | @c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
1895 | @c libc_lock_unlock dup @aculock | |
28f540f4 RM |
1896 | This function opens the services database to begin scanning it. |
1897 | ||
1898 | If the @var{stayopen} argument is nonzero, this sets a flag so that | |
1899 | subsequent calls to @code{getservbyname} or @code{getservbyport} will | |
1900 | not close the database (as they usually would). This makes for more | |
1901 | efficiency if you call those functions several times, by avoiding | |
1902 | reopening the database for each call. | |
1903 | @end deftypefun | |
1904 | ||
1905 | @comment netdb.h | |
1906 | @comment BSD | |
1907 | @deftypefun {struct servent *} getservent (void) | |
973f180b AO |
1908 | @safety{@prelim{}@mtunsafe{@mtasurace{:servent} @mtasurace{:serventbuf} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} |
1909 | @c getservent @mtasurace:servent @mtasurace:serventbuf @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
1910 | @c libc_lock_lock dup @asulock @aculock | |
1911 | @c nss_getent(getservent_r) @mtasurace:servent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
1912 | @c malloc dup @ascuheap @acsmem | |
1913 | @c *func = getservent_r dup @mtasurace:servent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
1914 | @c realloc dup @ascuheap @acsmem | |
1915 | @c free dup @ascuheap @acsmem | |
1916 | @c libc_lock_unlock dup @aculock | |
1917 | @c | |
1918 | @c getservent_r @mtasurace:servent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
1919 | @c libc_lock_lock dup @asulock @aculock | |
1920 | @c nss_getent_r(nss_services_lookup2) @mtasurace:servent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
1921 | @c setup(nss_services_lookup2) dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
1922 | @c *fct.f @mtasurace:servent @ascuplugin | |
1923 | @c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
1924 | @c nss_lookup dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
1925 | @c *sfct.f @mtasurace:servent @ascuplugin | |
1926 | @c libc_lock_unlock dup @aculock | |
28f540f4 RM |
1927 | This function returns the next entry in the services database. If |
1928 | there are no more entries, it returns a null pointer. | |
1929 | @end deftypefun | |
1930 | ||
1931 | @comment netdb.h | |
1932 | @comment BSD | |
1933 | @deftypefun void endservent (void) | |
973f180b AO |
1934 | @safety{@prelim{}@mtunsafe{@mtasurace{:servent} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} |
1935 | @c endservent @mtasurace:servent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
1936 | @c libc_lock_lock @asulock @aculock | |
1937 | @c nss_endent(nss_services_lookup2) @mtasurace:servent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
1938 | @c setup(nss_services_lookup2) dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
1939 | @c *fct.f @mtasurace:servent @ascuplugin | |
1940 | @c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
1941 | @c libc_lock_unlock @aculock | |
28f540f4 RM |
1942 | This function closes the services database. |
1943 | @end deftypefun | |
1944 | ||
1945 | @node Byte Order | |
1946 | @subsection Byte Order Conversion | |
1947 | @cindex byte order conversion, for socket | |
1948 | @cindex converting byte order | |
1949 | ||
1950 | @cindex big-endian | |
1951 | @cindex little-endian | |
1952 | Different kinds of computers use different conventions for the | |
1953 | ordering of bytes within a word. Some computers put the most | |
1954 | significant byte within a word first (this is called ``big-endian'' | |
1955 | order), and others put it last (``little-endian'' order). | |
1956 | ||
1957 | @cindex network byte order | |
1958 | So that machines with different byte order conventions can | |
1959 | communicate, the Internet protocols specify a canonical byte order | |
1960 | convention for data transmitted over the network. This is known | |
04b9968b | 1961 | as @dfn{network byte order}. |
28f540f4 RM |
1962 | |
1963 | When establishing an Internet socket connection, you must make sure that | |
1964 | the data in the @code{sin_port} and @code{sin_addr} members of the | |
04b9968b | 1965 | @code{sockaddr_in} structure are represented in network byte order. |
28f540f4 RM |
1966 | If you are encoding integer data in the messages sent through the |
1967 | socket, you should convert this to network byte order too. If you don't | |
1968 | do this, your program may fail when running on or talking to other kinds | |
1969 | of machines. | |
1970 | ||
1971 | If you use @code{getservbyname} and @code{gethostbyname} or | |
1972 | @code{inet_addr} to get the port number and host address, the values are | |
04b9968b | 1973 | already in network byte order, and you can copy them directly into |
28f540f4 RM |
1974 | the @code{sockaddr_in} structure. |
1975 | ||
4bca4c17 UD |
1976 | Otherwise, you have to convert the values explicitly. Use @code{htons} |
1977 | and @code{ntohs} to convert values for the @code{sin_port} member. Use | |
1978 | @code{htonl} and @code{ntohl} to convert IPv4 addresses for the | |
28f540f4 | 1979 | @code{sin_addr} member. (Remember, @code{struct in_addr} is equivalent |
4bca4c17 | 1980 | to @code{uint32_t}.) These functions are declared in |
28f540f4 RM |
1981 | @file{netinet/in.h}. |
1982 | @pindex netinet/in.h | |
1983 | ||
1984 | @comment netinet/in.h | |
1985 | @comment BSD | |
4bca4c17 | 1986 | @deftypefun {uint16_t} htons (uint16_t @var{hostshort}) |
973f180b AO |
1987 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
1988 | @c htons ok | |
1989 | @c bswap_16 ok | |
1990 | @c bswap_constant_16 ok | |
1991 | ||
4bca4c17 | 1992 | This function converts the @code{uint16_t} integer @var{hostshort} from |
28f540f4 RM |
1993 | host byte order to network byte order. |
1994 | @end deftypefun | |
1995 | ||
1996 | @comment netinet/in.h | |
1997 | @comment BSD | |
4bca4c17 | 1998 | @deftypefun {uint16_t} ntohs (uint16_t @var{netshort}) |
973f180b AO |
1999 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
2000 | @c Alias to htons. | |
4bca4c17 | 2001 | This function converts the @code{uint16_t} integer @var{netshort} from |
28f540f4 RM |
2002 | network byte order to host byte order. |
2003 | @end deftypefun | |
2004 | ||
2005 | @comment netinet/in.h | |
2006 | @comment BSD | |
4bca4c17 | 2007 | @deftypefun {uint32_t} htonl (uint32_t @var{hostlong}) |
973f180b AO |
2008 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
2009 | @c htonl ok | |
2010 | @c bswap_32 dup ok | |
4bca4c17 | 2011 | This function converts the @code{uint32_t} integer @var{hostlong} from |
28f540f4 | 2012 | host byte order to network byte order. |
4bca4c17 | 2013 | |
04b9968b | 2014 | This is used for IPv4 Internet addresses. |
28f540f4 RM |
2015 | @end deftypefun |
2016 | ||
2017 | @comment netinet/in.h | |
2018 | @comment BSD | |
4bca4c17 | 2019 | @deftypefun {uint32_t} ntohl (uint32_t @var{netlong}) |
973f180b AO |
2020 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
2021 | @c Alias to htonl. | |
4bca4c17 | 2022 | This function converts the @code{uint32_t} integer @var{netlong} from |
28f540f4 | 2023 | network byte order to host byte order. |
4bca4c17 | 2024 | |
04b9968b | 2025 | This is used for IPv4 Internet addresses. |
28f540f4 RM |
2026 | @end deftypefun |
2027 | ||
2028 | @node Protocols Database | |
2029 | @subsection Protocols Database | |
2030 | @cindex protocols database | |
2031 | ||
2032 | The communications protocol used with a socket controls low-level | |
04b9968b | 2033 | details of how data are exchanged. For example, the protocol implements |
28f540f4 RM |
2034 | things like checksums to detect errors in transmissions, and routing |
2035 | instructions for messages. Normal user programs have little reason to | |
2036 | mess with these details directly. | |
2037 | ||
2038 | @cindex TCP (Internet protocol) | |
2039 | The default communications protocol for the Internet namespace depends on | |
2040 | the communication style. For stream communication, the default is TCP | |
2041 | (``transmission control protocol''). For datagram communication, the | |
2042 | default is UDP (``user datagram protocol''). For reliable datagram | |
2043 | communication, the default is RDP (``reliable datagram protocol''). | |
2044 | You should nearly always use the default. | |
2045 | ||
2046 | @pindex /etc/protocols | |
2047 | Internet protocols are generally specified by a name instead of a | |
2048 | number. The network protocols that a host knows about are stored in a | |
2049 | database. This is usually either derived from the file | |
2050 | @file{/etc/protocols}, or it may be an equivalent provided by a name | |
2051 | server. You look up the protocol number associated with a named | |
2052 | protocol in the database using the @code{getprotobyname} function. | |
2053 | ||
2054 | Here are detailed descriptions of the utilities for accessing the | |
2055 | protocols database. These are declared in @file{netdb.h}. | |
2056 | @pindex netdb.h | |
2057 | ||
2058 | @comment netdb.h | |
2059 | @comment BSD | |
2060 | @deftp {Data Type} {struct protoent} | |
2061 | This data type is used to represent entries in the network protocols | |
2062 | database. It has the following members: | |
2063 | ||
2064 | @table @code | |
2065 | @item char *p_name | |
2066 | This is the official name of the protocol. | |
2067 | ||
2068 | @item char **p_aliases | |
2069 | These are alternate names for the protocol, specified as an array of | |
2070 | strings. The last element of the array is a null pointer. | |
2071 | ||
2072 | @item int p_proto | |
2073 | This is the protocol number (in host byte order); use this member as the | |
2074 | @var{protocol} argument to @code{socket}. | |
2075 | @end table | |
2076 | @end deftp | |
2077 | ||
2078 | You can use @code{getprotobyname} and @code{getprotobynumber} to search | |
2079 | the protocols database for a specific protocol. The information is | |
2080 | returned in a statically-allocated structure; you must copy the | |
2081 | information if you need to save it across calls. | |
2082 | ||
2083 | @comment netdb.h | |
2084 | @comment BSD | |
2085 | @deftypefun {struct protoent *} getprotobyname (const char *@var{name}) | |
973f180b AO |
2086 | @safety{@prelim{}@mtunsafe{@mtasurace{:protobyname} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} |
2087 | @c getprotobyname =~ getpwuid @mtasurace:protobyname @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
2088 | @c libc_lock_lock dup @asulock @aculock | |
2089 | @c malloc dup @ascuheap @acsmem | |
2090 | @c getprotobyname_r dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
2091 | @c realloc dup @ascuheap @acsmem | |
2092 | @c free dup @ascuheap @acsmem | |
2093 | @c libc_lock_unlock dup @aculock | |
2094 | @c | |
2095 | @c getprotobyname_r =~ getpwuid_r @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
2096 | @c no nscd support | |
2097 | @c nss_protocols_lookup2 =~ nss_passwd_lookup2 @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
2098 | @c *fct.l -> _nss_*_getprotobyname_r @ascuplugin | |
2099 | @c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
28f540f4 RM |
2100 | The @code{getprotobyname} function returns information about the |
2101 | network protocol named @var{name}. If there is no such protocol, it | |
2102 | returns a null pointer. | |
2103 | @end deftypefun | |
2104 | ||
2105 | @comment netdb.h | |
2106 | @comment BSD | |
2107 | @deftypefun {struct protoent *} getprotobynumber (int @var{protocol}) | |
973f180b AO |
2108 | @safety{@prelim{}@mtunsafe{@mtasurace{:protobynumber} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} |
2109 | @c getprotobynumber =~ getpwuid @mtasurace:protobynumber @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
2110 | @c libc_lock_lock dup @asulock @aculock | |
2111 | @c malloc dup @ascuheap @acsmem | |
2112 | @c getprotobynumber_r dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
2113 | @c realloc dup @ascuheap @acsmem | |
2114 | @c free dup @ascuheap @acsmem | |
2115 | @c libc_lock_unlock dup @aculock | |
2116 | @c | |
2117 | @c getprotobynumber_r =~ getpwuid_r @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
2118 | @c no nscd support | |
2119 | @c nss_protocols_lookup2 =~ nss_passwd_lookup2 @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
2120 | @c *fct.l -> _nss_*_getprotobynumber_r @ascuplugin | |
2121 | @c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
28f540f4 RM |
2122 | The @code{getprotobynumber} function returns information about the |
2123 | network protocol with number @var{protocol}. If there is no such | |
2124 | protocol, it returns a null pointer. | |
2125 | @end deftypefun | |
2126 | ||
2127 | You can also scan the whole protocols database one protocol at a time by | |
04b9968b UD |
2128 | using @code{setprotoent}, @code{getprotoent} and @code{endprotoent}. |
2129 | Be careful when using these functions because they are not reentrant. | |
28f540f4 RM |
2130 | |
2131 | @comment netdb.h | |
2132 | @comment BSD | |
2133 | @deftypefun void setprotoent (int @var{stayopen}) | |
973f180b AO |
2134 | @safety{@prelim{}@mtunsafe{@mtasurace{:protoent} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} |
2135 | @c setprotoent @mtasurace:protoent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
2136 | @c libc_lock_lock dup @asulock @aculock | |
2137 | @c nss_setent(nss_protocols_lookup2) @mtasurace:protoent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
2138 | @c setup(nss_protocols_lookup2) @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
2139 | @c *lookup_fct = nss_protocols_lookup2 dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
2140 | @c nss_lookup dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
2141 | @c *fct.f @mtasurace:protoent @ascuplugin | |
2142 | @c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
2143 | @c libc_lock_unlock dup @aculock | |
28f540f4 RM |
2144 | This function opens the protocols database to begin scanning it. |
2145 | ||
2146 | If the @var{stayopen} argument is nonzero, this sets a flag so that | |
2147 | subsequent calls to @code{getprotobyname} or @code{getprotobynumber} will | |
2148 | not close the database (as they usually would). This makes for more | |
2149 | efficiency if you call those functions several times, by avoiding | |
2150 | reopening the database for each call. | |
2151 | @end deftypefun | |
2152 | ||
2153 | @comment netdb.h | |
2154 | @comment BSD | |
2155 | @deftypefun {struct protoent *} getprotoent (void) | |
973f180b AO |
2156 | @safety{@prelim{}@mtunsafe{@mtasurace{:protoent} @mtasurace{:protoentbuf} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} |
2157 | @c getprotoent @mtasurace:protoent @mtasurace:protoentbuf @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
2158 | @c libc_lock_lock dup @asulock @aculock | |
2159 | @c nss_getent(getprotoent_r) @mtasurace:protoent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
2160 | @c malloc dup @ascuheap @acsmem | |
2161 | @c *func = getprotoent_r dup @mtasurace:protoent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
2162 | @c realloc dup @ascuheap @acsmem | |
2163 | @c free dup @ascuheap @acsmem | |
2164 | @c libc_lock_unlock dup @aculock | |
2165 | @c | |
2166 | @c getprotoent_r @mtasurace:protoent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
2167 | @c libc_lock_lock dup @asulock @aculock | |
2168 | @c nss_getent_r(nss_protocols_lookup2) @mtasurace:protoent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
2169 | @c setup(nss_protocols_lookup2) dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
2170 | @c *fct.f @mtasurace:servent @ascuplugin | |
2171 | @c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
2172 | @c nss_lookup dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
2173 | @c *sfct.f @mtasurace:protoent @ascuplugin | |
2174 | @c libc_lock_unlock dup @aculock | |
28f540f4 RM |
2175 | This function returns the next entry in the protocols database. It |
2176 | returns a null pointer if there are no more entries. | |
2177 | @end deftypefun | |
2178 | ||
2179 | @comment netdb.h | |
2180 | @comment BSD | |
2181 | @deftypefun void endprotoent (void) | |
973f180b AO |
2182 | @safety{@prelim{}@mtunsafe{@mtasurace{:protoent} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} |
2183 | @c endprotoent @mtasurace:protoent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
2184 | @c libc_lock_lock @asulock @aculock | |
2185 | @c nss_endent(nss_protocols_lookup2) @mtasurace:protoent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
2186 | @c setup(nss_protocols_lookup2) dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
2187 | @c *fct.f @mtasurace:protoent @ascuplugin | |
2188 | @c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
2189 | @c libc_lock_unlock @aculock | |
28f540f4 RM |
2190 | This function closes the protocols database. |
2191 | @end deftypefun | |
2192 | ||
2193 | @node Inet Example | |
2194 | @subsection Internet Socket Example | |
2195 | ||
2196 | Here is an example showing how to create and name a socket in the | |
2197 | Internet namespace. The newly created socket exists on the machine that | |
2198 | the program is running on. Rather than finding and using the machine's | |
2199 | Internet address, this example specifies @code{INADDR_ANY} as the host | |
2200 | address; the system replaces that with the machine's actual address. | |
2201 | ||
2202 | @smallexample | |
2203 | @include mkisock.c.texi | |
2204 | @end smallexample | |
2205 | ||
2206 | Here is another example, showing how you can fill in a @code{sockaddr_in} | |
2207 | structure, given a host name string and a port number: | |
2208 | ||
2209 | @smallexample | |
2210 | @include isockad.c.texi | |
2211 | @end smallexample | |
2212 | ||
2213 | @node Misc Namespaces | |
2214 | @section Other Namespaces | |
2215 | ||
2216 | @vindex PF_NS | |
2217 | @vindex PF_ISO | |
2218 | @vindex PF_CCITT | |
2219 | @vindex PF_IMPLINK | |
2220 | @vindex PF_ROUTE | |
2221 | Certain other namespaces and associated protocol families are supported | |
2222 | but not documented yet because they are not often used. @code{PF_NS} | |
2223 | refers to the Xerox Network Software protocols. @code{PF_ISO} stands | |
2224 | for Open Systems Interconnect. @code{PF_CCITT} refers to protocols from | |
2225 | CCITT. @file{socket.h} defines these symbols and others naming protocols | |
2226 | not actually implemented. | |
2227 | ||
2228 | @code{PF_IMPLINK} is used for communicating between hosts and Internet | |
04b9968b | 2229 | Message Processors. For information on this and @code{PF_ROUTE}, an |
28f540f4 RM |
2230 | occasionally-used local area routing protocol, see the GNU Hurd Manual |
2231 | (to appear in the future). | |
2232 | ||
2233 | @node Open/Close Sockets | |
2234 | @section Opening and Closing Sockets | |
2235 | ||
2236 | This section describes the actual library functions for opening and | |
2237 | closing sockets. The same functions work for all namespaces and | |
2238 | connection styles. | |
2239 | ||
2240 | @menu | |
2241 | * Creating a Socket:: How to open a socket. | |
2242 | * Closing a Socket:: How to close a socket. | |
2243 | * Socket Pairs:: These are created like pipes. | |
2244 | @end menu | |
2245 | ||
2246 | @node Creating a Socket | |
2247 | @subsection Creating a Socket | |
2248 | @cindex creating a socket | |
2249 | @cindex socket, creating | |
2250 | @cindex opening a socket | |
2251 | ||
2252 | The primitive for creating a socket is the @code{socket} function, | |
2253 | declared in @file{sys/socket.h}. | |
2254 | @pindex sys/socket.h | |
2255 | ||
2256 | @comment sys/socket.h | |
2257 | @comment BSD | |
2258 | @deftypefun int socket (int @var{namespace}, int @var{style}, int @var{protocol}) | |
973f180b | 2259 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}} |
28f540f4 RM |
2260 | This function creates a socket and specifies communication style |
2261 | @var{style}, which should be one of the socket styles listed in | |
2262 | @ref{Communication Styles}. The @var{namespace} argument specifies | |
4bca4c17 | 2263 | the namespace; it must be @code{PF_LOCAL} (@pxref{Local Namespace}) or |
28f540f4 RM |
2264 | @code{PF_INET} (@pxref{Internet Namespace}). @var{protocol} |
2265 | designates the specific protocol (@pxref{Socket Concepts}); zero is | |
2266 | usually right for @var{protocol}. | |
2267 | ||
2268 | The return value from @code{socket} is the file descriptor for the new | |
2269 | socket, or @code{-1} in case of error. The following @code{errno} error | |
2270 | conditions are defined for this function: | |
2271 | ||
2272 | @table @code | |
2273 | @item EPROTONOSUPPORT | |
2274 | The @var{protocol} or @var{style} is not supported by the | |
2275 | @var{namespace} specified. | |
2276 | ||
2277 | @item EMFILE | |
2278 | The process already has too many file descriptors open. | |
2279 | ||
2280 | @item ENFILE | |
2281 | The system already has too many file descriptors open. | |
2282 | ||
0bc93a2f | 2283 | @item EACCES |
04b9968b | 2284 | The process does not have the privilege to create a socket of the specified |
28f540f4 RM |
2285 | @var{style} or @var{protocol}. |
2286 | ||
2287 | @item ENOBUFS | |
2288 | The system ran out of internal buffer space. | |
2289 | @end table | |
2290 | ||
2291 | The file descriptor returned by the @code{socket} function supports both | |
04b9968b | 2292 | read and write operations. However, like pipes, sockets do not support file |
28f540f4 RM |
2293 | positioning operations. |
2294 | @end deftypefun | |
2295 | ||
6e953631 | 2296 | For examples of how to call the @code{socket} function, |
4bca4c17 | 2297 | see @ref{Local Socket Example}, or @ref{Inet Example}. |
28f540f4 RM |
2298 | |
2299 | ||
2300 | @node Closing a Socket | |
2301 | @subsection Closing a Socket | |
2302 | @cindex socket, closing | |
2303 | @cindex closing a socket | |
2304 | @cindex shutting down a socket | |
2305 | @cindex socket shutdown | |
2306 | ||
04b9968b | 2307 | When you have finished using a socket, you can simply close its |
28f540f4 RM |
2308 | file descriptor with @code{close}; see @ref{Opening and Closing Files}. |
2309 | If there is still data waiting to be transmitted over the connection, | |
2310 | normally @code{close} tries to complete this transmission. You | |
2311 | can control this behavior using the @code{SO_LINGER} socket option to | |
2312 | specify a timeout period; see @ref{Socket Options}. | |
2313 | ||
2314 | @pindex sys/socket.h | |
04b9968b | 2315 | You can also shut down only reception or transmission on a |
28f540f4 RM |
2316 | connection by calling @code{shutdown}, which is declared in |
2317 | @file{sys/socket.h}. | |
2318 | ||
2319 | @comment sys/socket.h | |
2320 | @comment BSD | |
2321 | @deftypefun int shutdown (int @var{socket}, int @var{how}) | |
973f180b | 2322 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
28f540f4 RM |
2323 | The @code{shutdown} function shuts down the connection of socket |
2324 | @var{socket}. The argument @var{how} specifies what action to | |
2325 | perform: | |
2326 | ||
2327 | @table @code | |
2328 | @item 0 | |
2329 | Stop receiving data for this socket. If further data arrives, | |
2330 | reject it. | |
2331 | ||
2332 | @item 1 | |
2333 | Stop trying to transmit data from this socket. Discard any data | |
2334 | waiting to be sent. Stop looking for acknowledgement of data already | |
2335 | sent; don't retransmit it if it is lost. | |
2336 | ||
2337 | @item 2 | |
2338 | Stop both reception and transmission. | |
2339 | @end table | |
2340 | ||
2341 | The return value is @code{0} on success and @code{-1} on failure. The | |
2342 | following @code{errno} error conditions are defined for this function: | |
2343 | ||
2344 | @table @code | |
2345 | @item EBADF | |
2346 | @var{socket} is not a valid file descriptor. | |
2347 | ||
2348 | @item ENOTSOCK | |
2349 | @var{socket} is not a socket. | |
2350 | ||
2351 | @item ENOTCONN | |
2352 | @var{socket} is not connected. | |
2353 | @end table | |
2354 | @end deftypefun | |
2355 | ||
2356 | @node Socket Pairs | |
2357 | @subsection Socket Pairs | |
2358 | @cindex creating a socket pair | |
2359 | @cindex socket pair | |
2360 | @cindex opening a socket pair | |
2361 | ||
2362 | @pindex sys/socket.h | |
2363 | A @dfn{socket pair} consists of a pair of connected (but unnamed) | |
2364 | sockets. It is very similar to a pipe and is used in much the same | |
2365 | way. Socket pairs are created with the @code{socketpair} function, | |
2366 | declared in @file{sys/socket.h}. A socket pair is much like a pipe; the | |
2367 | main difference is that the socket pair is bidirectional, whereas the | |
2368 | pipe has one input-only end and one output-only end (@pxref{Pipes and | |
2369 | FIFOs}). | |
2370 | ||
2371 | @comment sys/socket.h | |
2372 | @comment BSD | |
2373 | @deftypefun int socketpair (int @var{namespace}, int @var{style}, int @var{protocol}, int @var{filedes}@t{[2]}) | |
973f180b | 2374 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}} |
28f540f4 RM |
2375 | This function creates a socket pair, returning the file descriptors in |
2376 | @code{@var{filedes}[0]} and @code{@var{filedes}[1]}. The socket pair | |
2377 | is a full-duplex communications channel, so that both reading and writing | |
2378 | may be performed at either end. | |
2379 | ||
04b9968b | 2380 | The @var{namespace}, @var{style} and @var{protocol} arguments are |
28f540f4 RM |
2381 | interpreted as for the @code{socket} function. @var{style} should be |
2382 | one of the communication styles listed in @ref{Communication Styles}. | |
2383 | The @var{namespace} argument specifies the namespace, which must be | |
4bca4c17 | 2384 | @code{AF_LOCAL} (@pxref{Local Namespace}); @var{protocol} specifies the |
28f540f4 RM |
2385 | communications protocol, but zero is the only meaningful value. |
2386 | ||
2387 | If @var{style} specifies a connectionless communication style, then | |
2388 | the two sockets you get are not @emph{connected}, strictly speaking, | |
2389 | but each of them knows the other as the default destination address, | |
2390 | so they can send packets to each other. | |
2391 | ||
2392 | The @code{socketpair} function returns @code{0} on success and @code{-1} | |
2393 | on failure. The following @code{errno} error conditions are defined | |
2394 | for this function: | |
2395 | ||
2396 | @table @code | |
2397 | @item EMFILE | |
2398 | The process has too many file descriptors open. | |
2399 | ||
2400 | @item EAFNOSUPPORT | |
2401 | The specified namespace is not supported. | |
2402 | ||
2403 | @item EPROTONOSUPPORT | |
2404 | The specified protocol is not supported. | |
2405 | ||
2406 | @item EOPNOTSUPP | |
2407 | The specified protocol does not support the creation of socket pairs. | |
2408 | @end table | |
2409 | @end deftypefun | |
2410 | ||
2411 | @node Connections | |
2412 | @section Using Sockets with Connections | |
2413 | ||
2414 | @cindex connection | |
2415 | @cindex client | |
2416 | @cindex server | |
2417 | The most common communication styles involve making a connection to a | |
2418 | particular other socket, and then exchanging data with that socket | |
2419 | over and over. Making a connection is asymmetric; one side (the | |
2420 | @dfn{client}) acts to request a connection, while the other side (the | |
2421 | @dfn{server}) makes a socket and waits for the connection request. | |
2422 | ||
2423 | @iftex | |
2424 | @itemize @bullet | |
2425 | @item | |
2426 | @ref{Connecting}, describes what the client program must do to | |
2427 | initiate a connection with a server. | |
2428 | ||
2429 | @item | |
04b9968b | 2430 | @ref{Listening} and @ref{Accepting Connections} describe what the |
28f540f4 RM |
2431 | server program must do to wait for and act upon connection requests |
2432 | from clients. | |
2433 | ||
2434 | @item | |
04b9968b | 2435 | @ref{Transferring Data}, describes how data are transferred through the |
28f540f4 RM |
2436 | connected socket. |
2437 | @end itemize | |
2438 | @end iftex | |
2439 | ||
2440 | @menu | |
2441 | * Connecting:: What the client program must do. | |
2442 | * Listening:: How a server program waits for requests. | |
2443 | * Accepting Connections:: What the server does when it gets a request. | |
2444 | * Who is Connected:: Getting the address of the | |
2445 | other side of a connection. | |
2446 | * Transferring Data:: How to send and receive data. | |
2447 | * Byte Stream Example:: An example program: a client for communicating | |
2448 | over a byte stream socket in the Internet namespace. | |
2449 | * Server Example:: A corresponding server program. | |
2450 | * Out-of-Band Data:: This is an advanced feature. | |
2451 | @end menu | |
2452 | ||
2453 | @node Connecting | |
2454 | @subsection Making a Connection | |
2455 | @cindex connecting a socket | |
2456 | @cindex socket, connecting | |
2457 | @cindex socket, initiating a connection | |
2458 | @cindex socket, client actions | |
2459 | ||
2460 | In making a connection, the client makes a connection while the server | |
2461 | waits for and accepts the connection. Here we discuss what the client | |
04b9968b | 2462 | program must do with the @code{connect} function, which is declared in |
28f540f4 RM |
2463 | @file{sys/socket.h}. |
2464 | ||
2465 | @comment sys/socket.h | |
2466 | @comment BSD | |
55c14926 | 2467 | @deftypefun int connect (int @var{socket}, struct sockaddr *@var{addr}, socklen_t @var{length}) |
973f180b | 2468 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
28f540f4 RM |
2469 | The @code{connect} function initiates a connection from the socket |
2470 | with file descriptor @var{socket} to the socket whose address is | |
2471 | specified by the @var{addr} and @var{length} arguments. (This socket | |
2472 | is typically on another machine, and it must be already set up as a | |
2473 | server.) @xref{Socket Addresses}, for information about how these | |
2474 | arguments are interpreted. | |
2475 | ||
2476 | Normally, @code{connect} waits until the server responds to the request | |
2477 | before it returns. You can set nonblocking mode on the socket | |
2478 | @var{socket} to make @code{connect} return immediately without waiting | |
2479 | for the response. @xref{File Status Flags}, for information about | |
2480 | nonblocking mode. | |
2481 | @c !!! how do you tell when it has finished connecting? I suspect the | |
2482 | @c way you do it is select for writing. | |
2483 | ||
2484 | The normal return value from @code{connect} is @code{0}. If an error | |
2485 | occurs, @code{connect} returns @code{-1}. The following @code{errno} | |
2486 | error conditions are defined for this function: | |
2487 | ||
2488 | @table @code | |
2489 | @item EBADF | |
2490 | The socket @var{socket} is not a valid file descriptor. | |
2491 | ||
2492 | @item ENOTSOCK | |
6e953631 | 2493 | File descriptor @var{socket} is not a socket. |
28f540f4 RM |
2494 | |
2495 | @item EADDRNOTAVAIL | |
2496 | The specified address is not available on the remote machine. | |
2497 | ||
2498 | @item EAFNOSUPPORT | |
2499 | The namespace of the @var{addr} is not supported by this socket. | |
2500 | ||
2501 | @item EISCONN | |
2502 | The socket @var{socket} is already connected. | |
2503 | ||
2504 | @item ETIMEDOUT | |
2505 | The attempt to establish the connection timed out. | |
2506 | ||
2507 | @item ECONNREFUSED | |
2508 | The server has actively refused to establish the connection. | |
2509 | ||
2510 | @item ENETUNREACH | |
2511 | The network of the given @var{addr} isn't reachable from this host. | |
2512 | ||
2513 | @item EADDRINUSE | |
2514 | The socket address of the given @var{addr} is already in use. | |
2515 | ||
2516 | @item EINPROGRESS | |
2517 | The socket @var{socket} is non-blocking and the connection could not be | |
2518 | established immediately. You can determine when the connection is | |
2519 | completely established with @code{select}; @pxref{Waiting for I/O}. | |
2520 | Another @code{connect} call on the same socket, before the connection is | |
2521 | completely established, will fail with @code{EALREADY}. | |
2522 | ||
2523 | @item EALREADY | |
2524 | The socket @var{socket} is non-blocking and already has a pending | |
2525 | connection in progress (see @code{EINPROGRESS} above). | |
2526 | @end table | |
dd7d45e8 | 2527 | |
04b9968b UD |
2528 | This function is defined as a cancellation point in multi-threaded |
2529 | programs, so one has to be prepared for this and make sure that | |
2530 | allocated resources (like memory, files descriptors, semaphores or | |
2531 | whatever) are freed even if the thread is canceled. | |
dd7d45e8 | 2532 | @c @xref{pthread_cleanup_push}, for a method how to do this. |
28f540f4 RM |
2533 | @end deftypefun |
2534 | ||
2535 | @node Listening | |
2536 | @subsection Listening for Connections | |
2537 | @cindex listening (sockets) | |
2538 | @cindex sockets, server actions | |
2539 | @cindex sockets, listening | |
2540 | ||
2541 | Now let us consider what the server process must do to accept | |
2542 | connections on a socket. First it must use the @code{listen} function | |
2543 | to enable connection requests on the socket, and then accept each | |
2544 | incoming connection with a call to @code{accept} (@pxref{Accepting | |
2545 | Connections}). Once connection requests are enabled on a server socket, | |
2546 | the @code{select} function reports when the socket has a connection | |
2547 | ready to be accepted (@pxref{Waiting for I/O}). | |
2548 | ||
2549 | The @code{listen} function is not allowed for sockets using | |
2550 | connectionless communication styles. | |
2551 | ||
2552 | You can write a network server that does not even start running until a | |
2553 | connection to it is requested. @xref{Inetd Servers}. | |
2554 | ||
2555 | In the Internet namespace, there are no special protection mechanisms | |
04b9968b | 2556 | for controlling access to a port; any process on any machine |
28f540f4 RM |
2557 | can make a connection to your server. If you want to restrict access to |
2558 | your server, make it examine the addresses associated with connection | |
2559 | requests or implement some other handshaking or identification | |
2560 | protocol. | |
2561 | ||
4bca4c17 | 2562 | In the local namespace, the ordinary file protection bits control who has |
28f540f4 RM |
2563 | access to connect to the socket. |
2564 | ||
2565 | @comment sys/socket.h | |
2566 | @comment BSD | |
88197030 | 2567 | @deftypefun int listen (int @var{socket}, int @var{n}) |
973f180b | 2568 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}} |
28f540f4 RM |
2569 | The @code{listen} function enables the socket @var{socket} to accept |
2570 | connections, thus making it a server socket. | |
2571 | ||
2572 | The argument @var{n} specifies the length of the queue for pending | |
2573 | connections. When the queue fills, new clients attempting to connect | |
2574 | fail with @code{ECONNREFUSED} until the server calls @code{accept} to | |
2575 | accept a connection from the queue. | |
2576 | ||
2577 | The @code{listen} function returns @code{0} on success and @code{-1} | |
2578 | on failure. The following @code{errno} error conditions are defined | |
2579 | for this function: | |
2580 | ||
2581 | @table @code | |
2582 | @item EBADF | |
2583 | The argument @var{socket} is not a valid file descriptor. | |
2584 | ||
2585 | @item ENOTSOCK | |
2586 | The argument @var{socket} is not a socket. | |
2587 | ||
2588 | @item EOPNOTSUPP | |
2589 | The socket @var{socket} does not support this operation. | |
2590 | @end table | |
2591 | @end deftypefun | |
2592 | ||
2593 | @node Accepting Connections | |
2594 | @subsection Accepting Connections | |
2595 | @cindex sockets, accepting connections | |
2596 | @cindex accepting connections | |
2597 | ||
2598 | When a server receives a connection request, it can complete the | |
2599 | connection by accepting the request. Use the function @code{accept} | |
2600 | to do this. | |
2601 | ||
2602 | A socket that has been established as a server can accept connection | |
2603 | requests from multiple clients. The server's original socket | |
04b9968b | 2604 | @emph{does not become part of the connection}; instead, @code{accept} |
28f540f4 RM |
2605 | makes a new socket which participates in the connection. |
2606 | @code{accept} returns the descriptor for this socket. The server's | |
2607 | original socket remains available for listening for further connection | |
2608 | requests. | |
2609 | ||
2610 | The number of pending connection requests on a server socket is finite. | |
2611 | If connection requests arrive from clients faster than the server can | |
2612 | act upon them, the queue can fill up and additional requests are refused | |
04b9968b | 2613 | with an @code{ECONNREFUSED} error. You can specify the maximum length of |
28f540f4 RM |
2614 | this queue as an argument to the @code{listen} function, although the |
2615 | system may also impose its own internal limit on the length of this | |
2616 | queue. | |
2617 | ||
2618 | @comment sys/socket.h | |
2619 | @comment BSD | |
29fe4d0d | 2620 | @deftypefun int accept (int @var{socket}, struct sockaddr *@var{addr}, socklen_t *@var{length_ptr}) |
973f180b | 2621 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}} |
28f540f4 RM |
2622 | This function is used to accept a connection request on the server |
2623 | socket @var{socket}. | |
2624 | ||
2625 | The @code{accept} function waits if there are no connections pending, | |
2626 | unless the socket @var{socket} has nonblocking mode set. (You can use | |
2627 | @code{select} to wait for a pending connection, with a nonblocking | |
2628 | socket.) @xref{File Status Flags}, for information about nonblocking | |
2629 | mode. | |
2630 | ||
2631 | The @var{addr} and @var{length-ptr} arguments are used to return | |
2632 | information about the name of the client socket that initiated the | |
2633 | connection. @xref{Socket Addresses}, for information about the format | |
2634 | of the information. | |
2635 | ||
2636 | Accepting a connection does not make @var{socket} part of the | |
2637 | connection. Instead, it creates a new socket which becomes | |
2638 | connected. The normal return value of @code{accept} is the file | |
2639 | descriptor for the new socket. | |
2640 | ||
2641 | After @code{accept}, the original socket @var{socket} remains open and | |
2642 | unconnected, and continues listening until you close it. You can | |
2643 | accept further connections with @var{socket} by calling @code{accept} | |
2644 | again. | |
2645 | ||
2646 | If an error occurs, @code{accept} returns @code{-1}. The following | |
2647 | @code{errno} error conditions are defined for this function: | |
2648 | ||
2649 | @table @code | |
2650 | @item EBADF | |
2651 | The @var{socket} argument is not a valid file descriptor. | |
2652 | ||
2653 | @item ENOTSOCK | |
2654 | The descriptor @var{socket} argument is not a socket. | |
2655 | ||
2656 | @item EOPNOTSUPP | |
2657 | The descriptor @var{socket} does not support this operation. | |
2658 | ||
2659 | @item EWOULDBLOCK | |
2660 | @var{socket} has nonblocking mode set, and there are no pending | |
2661 | connections immediately available. | |
2662 | @end table | |
dd7d45e8 | 2663 | |
04b9968b UD |
2664 | This function is defined as a cancellation point in multi-threaded |
2665 | programs, so one has to be prepared for this and make sure that | |
2666 | allocated resources (like memory, files descriptors, semaphores or | |
2667 | whatever) are freed even if the thread is canceled. | |
dd7d45e8 | 2668 | @c @xref{pthread_cleanup_push}, for a method how to do this. |
28f540f4 RM |
2669 | @end deftypefun |
2670 | ||
2671 | The @code{accept} function is not allowed for sockets using | |
2672 | connectionless communication styles. | |
2673 | ||
2674 | @node Who is Connected | |
2675 | @subsection Who is Connected to Me? | |
2676 | ||
2677 | @comment sys/socket.h | |
2678 | @comment BSD | |
4bca4c17 | 2679 | @deftypefun int getpeername (int @var{socket}, struct sockaddr *@var{addr}, socklen_t *@var{length-ptr}) |
973f180b | 2680 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
28f540f4 RM |
2681 | The @code{getpeername} function returns the address of the socket that |
2682 | @var{socket} is connected to; it stores the address in the memory space | |
2683 | specified by @var{addr} and @var{length-ptr}. It stores the length of | |
2684 | the address in @code{*@var{length-ptr}}. | |
2685 | ||
2686 | @xref{Socket Addresses}, for information about the format of the | |
2687 | address. In some operating systems, @code{getpeername} works only for | |
2688 | sockets in the Internet domain. | |
2689 | ||
2690 | The return value is @code{0} on success and @code{-1} on error. The | |
2691 | following @code{errno} error conditions are defined for this function: | |
2692 | ||
2693 | @table @code | |
2694 | @item EBADF | |
2695 | The argument @var{socket} is not a valid file descriptor. | |
2696 | ||
2697 | @item ENOTSOCK | |
2698 | The descriptor @var{socket} is not a socket. | |
2699 | ||
2700 | @item ENOTCONN | |
2701 | The socket @var{socket} is not connected. | |
2702 | ||
2703 | @item ENOBUFS | |
2704 | There are not enough internal buffers available. | |
2705 | @end table | |
2706 | @end deftypefun | |
2707 | ||
2708 | ||
2709 | @node Transferring Data | |
2710 | @subsection Transferring Data | |
2711 | @cindex reading from a socket | |
2712 | @cindex writing to a socket | |
2713 | ||
2714 | Once a socket has been connected to a peer, you can use the ordinary | |
2715 | @code{read} and @code{write} operations (@pxref{I/O Primitives}) to | |
2716 | transfer data. A socket is a two-way communications channel, so read | |
2717 | and write operations can be performed at either end. | |
2718 | ||
2719 | There are also some I/O modes that are specific to socket operations. | |
2720 | In order to specify these modes, you must use the @code{recv} and | |
2721 | @code{send} functions instead of the more generic @code{read} and | |
2722 | @code{write} functions. The @code{recv} and @code{send} functions take | |
2723 | an additional argument which you can use to specify various flags to | |
04b9968b | 2724 | control special I/O modes. For example, you can specify the |
28f540f4 RM |
2725 | @code{MSG_OOB} flag to read or write out-of-band data, the |
2726 | @code{MSG_PEEK} flag to peek at input, or the @code{MSG_DONTROUTE} flag | |
2727 | to control inclusion of routing information on output. | |
2728 | ||
2729 | @menu | |
2730 | * Sending Data:: Sending data with @code{send}. | |
2731 | * Receiving Data:: Reading data with @code{recv}. | |
2732 | * Socket Data Options:: Using @code{send} and @code{recv}. | |
2733 | @end menu | |
2734 | ||
2735 | @node Sending Data | |
2736 | @subsubsection Sending Data | |
2737 | ||
2738 | @pindex sys/socket.h | |
2739 | The @code{send} function is declared in the header file | |
2740 | @file{sys/socket.h}. If your @var{flags} argument is zero, you can just | |
2741 | as well use @code{write} instead of @code{send}; see @ref{I/O | |
2742 | Primitives}. If the socket was connected but the connection has broken, | |
2743 | you get a @code{SIGPIPE} signal for any use of @code{send} or | |
2744 | @code{write} (@pxref{Miscellaneous Signals}). | |
2745 | ||
2746 | @comment sys/socket.h | |
2747 | @comment BSD | |
8ded91fb | 2748 | @deftypefun ssize_t send (int @var{socket}, const void *@var{buffer}, size_t @var{size}, int @var{flags}) |
973f180b | 2749 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
28f540f4 RM |
2750 | The @code{send} function is like @code{write}, but with the additional |
2751 | flags @var{flags}. The possible values of @var{flags} are described | |
2752 | in @ref{Socket Data Options}. | |
2753 | ||
2754 | This function returns the number of bytes transmitted, or @code{-1} on | |
2755 | failure. If the socket is nonblocking, then @code{send} (like | |
2756 | @code{write}) can return after sending just part of the data. | |
2757 | @xref{File Status Flags}, for information about nonblocking mode. | |
2758 | ||
2759 | Note, however, that a successful return value merely indicates that | |
2760 | the message has been sent without error, not necessarily that it has | |
2761 | been received without error. | |
2762 | ||
2763 | The following @code{errno} error conditions are defined for this function: | |
2764 | ||
2765 | @table @code | |
2766 | @item EBADF | |
2767 | The @var{socket} argument is not a valid file descriptor. | |
2768 | ||
2769 | @item EINTR | |
2770 | The operation was interrupted by a signal before any data was sent. | |
2771 | @xref{Interrupted Primitives}. | |
2772 | ||
2773 | @item ENOTSOCK | |
2774 | The descriptor @var{socket} is not a socket. | |
2775 | ||
2776 | @item EMSGSIZE | |
2777 | The socket type requires that the message be sent atomically, but the | |
2778 | message is too large for this to be possible. | |
2779 | ||
2780 | @item EWOULDBLOCK | |
2781 | Nonblocking mode has been set on the socket, and the write operation | |
2782 | would block. (Normally @code{send} blocks until the operation can be | |
2783 | completed.) | |
2784 | ||
2785 | @item ENOBUFS | |
2786 | There is not enough internal buffer space available. | |
2787 | ||
2788 | @item ENOTCONN | |
2789 | You never connected this socket. | |
2790 | ||
2791 | @item EPIPE | |
2792 | This socket was connected but the connection is now broken. In this | |
2793 | case, @code{send} generates a @code{SIGPIPE} signal first; if that | |
2794 | signal is ignored or blocked, or if its handler returns, then | |
2795 | @code{send} fails with @code{EPIPE}. | |
2796 | @end table | |
dd7d45e8 | 2797 | |
04b9968b UD |
2798 | This function is defined as a cancellation point in multi-threaded |
2799 | programs, so one has to be prepared for this and make sure that | |
2800 | allocated resources (like memory, files descriptors, semaphores or | |
2801 | whatever) are freed even if the thread is canceled. | |
dd7d45e8 | 2802 | @c @xref{pthread_cleanup_push}, for a method how to do this. |
28f540f4 RM |
2803 | @end deftypefun |
2804 | ||
2805 | @node Receiving Data | |
2806 | @subsubsection Receiving Data | |
2807 | ||
2808 | @pindex sys/socket.h | |
2809 | The @code{recv} function is declared in the header file | |
2810 | @file{sys/socket.h}. If your @var{flags} argument is zero, you can | |
2811 | just as well use @code{read} instead of @code{recv}; see @ref{I/O | |
2812 | Primitives}. | |
2813 | ||
2814 | @comment sys/socket.h | |
2815 | @comment BSD | |
8ded91fb | 2816 | @deftypefun ssize_t recv (int @var{socket}, void *@var{buffer}, size_t @var{size}, int @var{flags}) |
973f180b | 2817 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
28f540f4 RM |
2818 | The @code{recv} function is like @code{read}, but with the additional |
2819 | flags @var{flags}. The possible values of @var{flags} are described | |
4bca4c17 | 2820 | in @ref{Socket Data Options}. |
28f540f4 | 2821 | |
04b9968b | 2822 | If nonblocking mode is set for @var{socket}, and no data are available to |
28f540f4 RM |
2823 | be read, @code{recv} fails immediately rather than waiting. @xref{File |
2824 | Status Flags}, for information about nonblocking mode. | |
2825 | ||
2826 | This function returns the number of bytes received, or @code{-1} on failure. | |
2827 | The following @code{errno} error conditions are defined for this function: | |
2828 | ||
2829 | @table @code | |
2830 | @item EBADF | |
2831 | The @var{socket} argument is not a valid file descriptor. | |
2832 | ||
2833 | @item ENOTSOCK | |
2834 | The descriptor @var{socket} is not a socket. | |
2835 | ||
2836 | @item EWOULDBLOCK | |
2837 | Nonblocking mode has been set on the socket, and the read operation | |
2838 | would block. (Normally, @code{recv} blocks until there is input | |
2839 | available to be read.) | |
2840 | ||
2841 | @item EINTR | |
2842 | The operation was interrupted by a signal before any data was read. | |
2843 | @xref{Interrupted Primitives}. | |
2844 | ||
2845 | @item ENOTCONN | |
2846 | You never connected this socket. | |
2847 | @end table | |
dd7d45e8 | 2848 | |
04b9968b UD |
2849 | This function is defined as a cancellation point in multi-threaded |
2850 | programs, so one has to be prepared for this and make sure that | |
2851 | allocated resources (like memory, files descriptors, semaphores or | |
2852 | whatever) are freed even if the thread is canceled. | |
dd7d45e8 | 2853 | @c @xref{pthread_cleanup_push}, for a method how to do this. |
28f540f4 RM |
2854 | @end deftypefun |
2855 | ||
2856 | @node Socket Data Options | |
2857 | @subsubsection Socket Data Options | |
2858 | ||
2859 | @pindex sys/socket.h | |
2860 | The @var{flags} argument to @code{send} and @code{recv} is a bit | |
2861 | mask. You can bitwise-OR the values of the following macros together | |
2862 | to obtain a value for this argument. All are defined in the header | |
2863 | file @file{sys/socket.h}. | |
2864 | ||
2865 | @comment sys/socket.h | |
2866 | @comment BSD | |
2867 | @deftypevr Macro int MSG_OOB | |
2868 | Send or receive out-of-band data. @xref{Out-of-Band Data}. | |
2869 | @end deftypevr | |
2870 | ||
2871 | @comment sys/socket.h | |
2872 | @comment BSD | |
2873 | @deftypevr Macro int MSG_PEEK | |
2874 | Look at the data but don't remove it from the input queue. This is | |
2875 | only meaningful with input functions such as @code{recv}, not with | |
2876 | @code{send}. | |
2877 | @end deftypevr | |
2878 | ||
2879 | @comment sys/socket.h | |
2880 | @comment BSD | |
2881 | @deftypevr Macro int MSG_DONTROUTE | |
2882 | Don't include routing information in the message. This is only | |
2883 | meaningful with output operations, and is usually only of interest for | |
2884 | diagnostic or routing programs. We don't try to explain it here. | |
2885 | @end deftypevr | |
2886 | ||
2887 | @node Byte Stream Example | |
2888 | @subsection Byte Stream Socket Example | |
2889 | ||
2890 | Here is an example client program that makes a connection for a byte | |
2891 | stream socket in the Internet namespace. It doesn't do anything | |
2892 | particularly interesting once it has connected to the server; it just | |
2893 | sends a text string to the server and exits. | |
2894 | ||
4bca4c17 UD |
2895 | This program uses @code{init_sockaddr} to set up the socket address; see |
2896 | @ref{Inet Example}. | |
2897 | ||
28f540f4 RM |
2898 | @smallexample |
2899 | @include inetcli.c.texi | |
2900 | @end smallexample | |
2901 | ||
2902 | @node Server Example | |
2903 | @subsection Byte Stream Connection Server Example | |
2904 | ||
2905 | The server end is much more complicated. Since we want to allow | |
2906 | multiple clients to be connected to the server at the same time, it | |
2907 | would be incorrect to wait for input from a single client by simply | |
2908 | calling @code{read} or @code{recv}. Instead, the right thing to do is | |
2909 | to use @code{select} (@pxref{Waiting for I/O}) to wait for input on | |
2910 | all of the open sockets. This also allows the server to deal with | |
2911 | additional connection requests. | |
2912 | ||
2913 | This particular server doesn't do anything interesting once it has | |
2914 | gotten a message from a client. It does close the socket for that | |
2915 | client when it detects an end-of-file condition (resulting from the | |
2916 | client shutting down its end of the connection). | |
2917 | ||
4bca4c17 UD |
2918 | This program uses @code{make_socket} to set up the socket address; see |
2919 | @ref{Inet Example}. | |
28f540f4 RM |
2920 | |
2921 | @smallexample | |
2922 | @include inetsrv.c.texi | |
2923 | @end smallexample | |
2924 | ||
2925 | @node Out-of-Band Data | |
2926 | @subsection Out-of-Band Data | |
2927 | ||
2928 | @cindex out-of-band data | |
2929 | @cindex high-priority data | |
2930 | Streams with connections permit @dfn{out-of-band} data that is | |
2931 | delivered with higher priority than ordinary data. Typically the | |
2932 | reason for sending out-of-band data is to send notice of an | |
04b9968b | 2933 | exceptional condition. To send out-of-band data use |
28f540f4 RM |
2934 | @code{send}, specifying the flag @code{MSG_OOB} (@pxref{Sending |
2935 | Data}). | |
2936 | ||
04b9968b | 2937 | Out-of-band data are received with higher priority because the |
28f540f4 RM |
2938 | receiving process need not read it in sequence; to read the next |
2939 | available out-of-band data, use @code{recv} with the @code{MSG_OOB} | |
2940 | flag (@pxref{Receiving Data}). Ordinary read operations do not read | |
04b9968b | 2941 | out-of-band data; they read only ordinary data. |
28f540f4 RM |
2942 | |
2943 | @cindex urgent socket condition | |
04b9968b | 2944 | When a socket finds that out-of-band data are on their way, it sends a |
28f540f4 RM |
2945 | @code{SIGURG} signal to the owner process or process group of the |
2946 | socket. You can specify the owner using the @code{F_SETOWN} command | |
2947 | to the @code{fcntl} function; see @ref{Interrupt Input}. You must | |
2948 | also establish a handler for this signal, as described in @ref{Signal | |
2949 | Handling}, in order to take appropriate action such as reading the | |
2950 | out-of-band data. | |
2951 | ||
2952 | Alternatively, you can test for pending out-of-band data, or wait | |
2953 | until there is out-of-band data, using the @code{select} function; it | |
2954 | can wait for an exceptional condition on the socket. @xref{Waiting | |
2955 | for I/O}, for more information about @code{select}. | |
2956 | ||
2957 | Notification of out-of-band data (whether with @code{SIGURG} or with | |
04b9968b | 2958 | @code{select}) indicates that out-of-band data are on the way; the data |
28f540f4 RM |
2959 | may not actually arrive until later. If you try to read the |
2960 | out-of-band data before it arrives, @code{recv} fails with an | |
2961 | @code{EWOULDBLOCK} error. | |
2962 | ||
2963 | Sending out-of-band data automatically places a ``mark'' in the stream | |
2964 | of ordinary data, showing where in the sequence the out-of-band data | |
2965 | ``would have been''. This is useful when the meaning of out-of-band | |
2966 | data is ``cancel everything sent so far''. Here is how you can test, | |
2967 | in the receiving process, whether any ordinary data was sent before | |
2968 | the mark: | |
2969 | ||
2970 | @smallexample | |
4bca4c17 | 2971 | success = ioctl (socket, SIOCATMARK, &atmark); |
28f540f4 RM |
2972 | @end smallexample |
2973 | ||
4bca4c17 UD |
2974 | The @code{integer} variable @var{atmark} is set to a nonzero value if |
2975 | the socket's read pointer has reached the ``mark''. | |
2976 | ||
2977 | @c Posix 1.g specifies sockatmark for this ioctl. sockatmark is not | |
2978 | @c implemented yet. | |
2979 | ||
28f540f4 RM |
2980 | Here's a function to discard any ordinary data preceding the |
2981 | out-of-band mark: | |
2982 | ||
2983 | @smallexample | |
2984 | int | |
2985 | discard_until_mark (int socket) | |
2986 | @{ | |
2987 | while (1) | |
2988 | @{ | |
2989 | /* @r{This is not an arbitrary limit; any size will do.} */ | |
2990 | char buffer[1024]; | |
4bca4c17 | 2991 | int atmark, success; |
28f540f4 RM |
2992 | |
2993 | /* @r{If we have reached the mark, return.} */ | |
4bca4c17 | 2994 | success = ioctl (socket, SIOCATMARK, &atmark); |
28f540f4 RM |
2995 | if (success < 0) |
2996 | perror ("ioctl"); | |
2997 | if (result) | |
2998 | return; | |
2999 | ||
3000 | /* @r{Otherwise, read a bunch of ordinary data and discard it.} | |
3001 | @r{This is guaranteed not to read past the mark} | |
3002 | @r{if it starts before the mark.} */ | |
3003 | success = read (socket, buffer, sizeof buffer); | |
3004 | if (success < 0) | |
3005 | perror ("read"); | |
3006 | @} | |
3007 | @} | |
3008 | @end smallexample | |
3009 | ||
3010 | If you don't want to discard the ordinary data preceding the mark, you | |
3011 | may need to read some of it anyway, to make room in internal system | |
3012 | buffers for the out-of-band data. If you try to read out-of-band data | |
3013 | and get an @code{EWOULDBLOCK} error, try reading some ordinary data | |
3014 | (saving it so that you can use it when you want it) and see if that | |
3015 | makes room. Here is an example: | |
3016 | ||
3017 | @smallexample | |
3018 | struct buffer | |
3019 | @{ | |
9133b79b | 3020 | char *buf; |
28f540f4 RM |
3021 | int size; |
3022 | struct buffer *next; | |
3023 | @}; | |
3024 | ||
3025 | /* @r{Read the out-of-band data from SOCKET and return it} | |
3026 | @r{as a `struct buffer', which records the address of the data} | |
3027 | @r{and its size.} | |
3028 | ||
3029 | @r{It may be necessary to read some ordinary data} | |
3030 | @r{in order to make room for the out-of-band data.} | |
04b9968b | 3031 | @r{If so, the ordinary data are saved as a chain of buffers} |
28f540f4 RM |
3032 | @r{found in the `next' field of the value.} */ |
3033 | ||
3034 | struct buffer * | |
3035 | read_oob (int socket) | |
3036 | @{ | |
3037 | struct buffer *tail = 0; | |
3038 | struct buffer *list = 0; | |
3039 | ||
3040 | while (1) | |
3041 | @{ | |
3042 | /* @r{This is an arbitrary limit.} | |
3043 | @r{Does anyone know how to do this without a limit?} */ | |
9133b79b UD |
3044 | #define BUF_SZ 1024 |
3045 | char *buf = (char *) xmalloc (BUF_SZ); | |
28f540f4 | 3046 | int success; |
4bca4c17 | 3047 | int atmark; |
28f540f4 RM |
3048 | |
3049 | /* @r{Try again to read the out-of-band data.} */ | |
9133b79b | 3050 | success = recv (socket, buf, BUF_SZ, MSG_OOB); |
28f540f4 RM |
3051 | if (success >= 0) |
3052 | @{ | |
3053 | /* @r{We got it, so return it.} */ | |
3054 | struct buffer *link | |
3055 | = (struct buffer *) xmalloc (sizeof (struct buffer)); | |
9133b79b | 3056 | link->buf = buf; |
28f540f4 RM |
3057 | link->size = success; |
3058 | link->next = list; | |
3059 | return link; | |
3060 | @} | |
3061 | ||
3062 | /* @r{If we fail, see if we are at the mark.} */ | |
4bca4c17 | 3063 | success = ioctl (socket, SIOCATMARK, &atmark); |
28f540f4 RM |
3064 | if (success < 0) |
3065 | perror ("ioctl"); | |
4bca4c17 | 3066 | if (atmark) |
28f540f4 RM |
3067 | @{ |
3068 | /* @r{At the mark; skipping past more ordinary data cannot help.} | |
3069 | @r{So just wait a while.} */ | |
3070 | sleep (1); | |
3071 | continue; | |
3072 | @} | |
3073 | ||
3074 | /* @r{Otherwise, read a bunch of ordinary data and save it.} | |
3075 | @r{This is guaranteed not to read past the mark} | |
3076 | @r{if it starts before the mark.} */ | |
9133b79b | 3077 | success = read (socket, buf, BUF_SZ); |
28f540f4 RM |
3078 | if (success < 0) |
3079 | perror ("read"); | |
3080 | ||
3081 | /* @r{Save this data in the buffer list.} */ | |
3082 | @{ | |
3083 | struct buffer *link | |
3084 | = (struct buffer *) xmalloc (sizeof (struct buffer)); | |
9133b79b | 3085 | link->buf = buf; |
28f540f4 RM |
3086 | link->size = success; |
3087 | ||
3088 | /* @r{Add the new link to the end of the list.} */ | |
3089 | if (tail) | |
3090 | tail->next = link; | |
3091 | else | |
3092 | list = link; | |
3093 | tail = link; | |
3094 | @} | |
3095 | @} | |
3096 | @} | |
3097 | @end smallexample | |
3098 | ||
3099 | @node Datagrams | |
3100 | @section Datagram Socket Operations | |
3101 | ||
3102 | @cindex datagram socket | |
3103 | This section describes how to use communication styles that don't use | |
3104 | connections (styles @code{SOCK_DGRAM} and @code{SOCK_RDM}). Using | |
3105 | these styles, you group data into packets and each packet is an | |
3106 | independent communication. You specify the destination for each | |
3107 | packet individually. | |
3108 | ||
04b9968b | 3109 | Datagram packets are like letters: you send each one independently |
28f540f4 RM |
3110 | with its own destination address, and they may arrive in the wrong |
3111 | order or not at all. | |
3112 | ||
3113 | The @code{listen} and @code{accept} functions are not allowed for | |
3114 | sockets using connectionless communication styles. | |
3115 | ||
3116 | @menu | |
3117 | * Sending Datagrams:: Sending packets on a datagram socket. | |
3118 | * Receiving Datagrams:: Receiving packets on a datagram socket. | |
3119 | * Datagram Example:: An example program: packets sent over a | |
4bca4c17 | 3120 | datagram socket in the local namespace. |
28f540f4 RM |
3121 | * Example Receiver:: Another program, that receives those packets. |
3122 | @end menu | |
3123 | ||
3124 | @node Sending Datagrams | |
3125 | @subsection Sending Datagrams | |
3126 | @cindex sending a datagram | |
3127 | @cindex transmitting datagrams | |
3128 | @cindex datagrams, transmitting | |
3129 | ||
3130 | @pindex sys/socket.h | |
3131 | The normal way of sending data on a datagram socket is by using the | |
3132 | @code{sendto} function, declared in @file{sys/socket.h}. | |
3133 | ||
3134 | You can call @code{connect} on a datagram socket, but this only | |
3135 | specifies a default destination for further data transmission on the | |
04b9968b | 3136 | socket. When a socket has a default destination you can use |
28f540f4 RM |
3137 | @code{send} (@pxref{Sending Data}) or even @code{write} (@pxref{I/O |
3138 | Primitives}) to send a packet there. You can cancel the default | |
3139 | destination by calling @code{connect} using an address format of | |
3140 | @code{AF_UNSPEC} in the @var{addr} argument. @xref{Connecting}, for | |
3141 | more information about the @code{connect} function. | |
3142 | ||
3143 | @comment sys/socket.h | |
3144 | @comment BSD | |
8ded91fb | 3145 | @deftypefun ssize_t sendto (int @var{socket}, const void *@var{buffer}, size_t @var{size}, int @var{flags}, struct sockaddr *@var{addr}, socklen_t @var{length}) |
973f180b | 3146 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
28f540f4 RM |
3147 | The @code{sendto} function transmits the data in the @var{buffer} |
3148 | through the socket @var{socket} to the destination address specified | |
3149 | by the @var{addr} and @var{length} arguments. The @var{size} argument | |
3150 | specifies the number of bytes to be transmitted. | |
3151 | ||
3152 | The @var{flags} are interpreted the same way as for @code{send}; see | |
3153 | @ref{Socket Data Options}. | |
3154 | ||
3155 | The return value and error conditions are also the same as for | |
3156 | @code{send}, but you cannot rely on the system to detect errors and | |
3157 | report them; the most common error is that the packet is lost or there | |
04b9968b | 3158 | is no-one at the specified address to receive it, and the operating |
28f540f4 RM |
3159 | system on your machine usually does not know this. |
3160 | ||
3161 | It is also possible for one call to @code{sendto} to report an error | |
04b9968b | 3162 | owing to a problem related to a previous call. |
dd7d45e8 | 3163 | |
04b9968b UD |
3164 | This function is defined as a cancellation point in multi-threaded |
3165 | programs, so one has to be prepared for this and make sure that | |
3166 | allocated resources (like memory, files descriptors, semaphores or | |
3167 | whatever) are freed even if the thread is canceled. | |
dd7d45e8 | 3168 | @c @xref{pthread_cleanup_push}, for a method how to do this. |
28f540f4 RM |
3169 | @end deftypefun |
3170 | ||
3171 | @node Receiving Datagrams | |
3172 | @subsection Receiving Datagrams | |
3173 | @cindex receiving datagrams | |
3174 | ||
3175 | The @code{recvfrom} function reads a packet from a datagram socket and | |
3176 | also tells you where it was sent from. This function is declared in | |
3177 | @file{sys/socket.h}. | |
3178 | ||
3179 | @comment sys/socket.h | |
3180 | @comment BSD | |
8ded91fb | 3181 | @deftypefun ssize_t recvfrom (int @var{socket}, void *@var{buffer}, size_t @var{size}, int @var{flags}, struct sockaddr *@var{addr}, socklen_t *@var{length-ptr}) |
973f180b | 3182 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
28f540f4 RM |
3183 | The @code{recvfrom} function reads one packet from the socket |
3184 | @var{socket} into the buffer @var{buffer}. The @var{size} argument | |
3185 | specifies the maximum number of bytes to be read. | |
3186 | ||
3187 | If the packet is longer than @var{size} bytes, then you get the first | |
04b9968b | 3188 | @var{size} bytes of the packet and the rest of the packet is lost. |
28f540f4 RM |
3189 | There's no way to read the rest of the packet. Thus, when you use a |
3190 | packet protocol, you must always know how long a packet to expect. | |
3191 | ||
3192 | The @var{addr} and @var{length-ptr} arguments are used to return the | |
3193 | address where the packet came from. @xref{Socket Addresses}. For a | |
04b9968b | 3194 | socket in the local domain the address information won't be meaningful, |
4bca4c17 | 3195 | since you can't read the address of such a socket (@pxref{Local |
28f540f4 RM |
3196 | Namespace}). You can specify a null pointer as the @var{addr} argument |
3197 | if you are not interested in this information. | |
3198 | ||
3199 | The @var{flags} are interpreted the same way as for @code{recv} | |
3200 | (@pxref{Socket Data Options}). The return value and error conditions | |
3201 | are also the same as for @code{recv}. | |
dd7d45e8 | 3202 | |
04b9968b UD |
3203 | This function is defined as a cancellation point in multi-threaded |
3204 | programs, so one has to be prepared for this and make sure that | |
3205 | allocated resources (like memory, files descriptors, semaphores or | |
3206 | whatever) are freed even if the thread is canceled. | |
dd7d45e8 | 3207 | @c @xref{pthread_cleanup_push}, for a method how to do this. |
28f540f4 RM |
3208 | @end deftypefun |
3209 | ||
3210 | You can use plain @code{recv} (@pxref{Receiving Data}) instead of | |
04b9968b | 3211 | @code{recvfrom} if you don't need to find out who sent the packet |
28f540f4 RM |
3212 | (either because you know where it should come from or because you |
3213 | treat all possible senders alike). Even @code{read} can be used if | |
3214 | you don't want to specify @var{flags} (@pxref{I/O Primitives}). | |
3215 | ||
3216 | @ignore | |
3217 | @c sendmsg and recvmsg are like readv and writev in that they | |
3218 | @c use a series of buffers. It's not clear this is worth | |
3219 | @c supporting or that we support them. | |
3220 | @c !!! they can do more; it is hairy | |
3221 | ||
3222 | @comment sys/socket.h | |
3223 | @comment BSD | |
3224 | @deftp {Data Type} {struct msghdr} | |
3225 | @end deftp | |
3226 | ||
3227 | @comment sys/socket.h | |
3228 | @comment BSD | |
8ded91fb | 3229 | @deftypefun ssize_t sendmsg (int @var{socket}, const struct msghdr *@var{message}, int @var{flags}) |
973f180b | 3230 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
dd7d45e8 | 3231 | |
04b9968b UD |
3232 | This function is defined as a cancellation point in multi-threaded |
3233 | programs, so one has to be prepared for this and make sure that | |
3234 | allocated resources (like memory, files descriptors, semaphores or | |
3235 | whatever) are freed even if the thread is cancel. | |
dd7d45e8 | 3236 | @c @xref{pthread_cleanup_push}, for a method how to do this. |
28f540f4 RM |
3237 | @end deftypefun |
3238 | ||
3239 | @comment sys/socket.h | |
3240 | @comment BSD | |
8ded91fb | 3241 | @deftypefun ssize_t recvmsg (int @var{socket}, struct msghdr *@var{message}, int @var{flags}) |
973f180b | 3242 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
dd7d45e8 | 3243 | |
04b9968b UD |
3244 | This function is defined as a cancellation point in multi-threaded |
3245 | programs, so one has to be prepared for this and make sure that | |
3246 | allocated resources (like memory, files descriptors, semaphores or | |
3247 | whatever) are freed even if the thread is canceled. | |
dd7d45e8 | 3248 | @c @xref{pthread_cleanup_push}, for a method how to do this. |
28f540f4 RM |
3249 | @end deftypefun |
3250 | @end ignore | |
3251 | ||
3252 | @node Datagram Example | |
3253 | @subsection Datagram Socket Example | |
3254 | ||
3255 | Here is a set of example programs that send messages over a datagram | |
4bca4c17 UD |
3256 | stream in the local namespace. Both the client and server programs use |
3257 | the @code{make_named_socket} function that was presented in @ref{Local | |
3258 | Socket Example}, to create and name their sockets. | |
28f540f4 RM |
3259 | |
3260 | First, here is the server program. It sits in a loop waiting for | |
3261 | messages to arrive, bouncing each message back to the sender. | |
04b9968b | 3262 | Obviously this isn't a particularly useful program, but it does show |
28f540f4 RM |
3263 | the general ideas involved. |
3264 | ||
3265 | @smallexample | |
3266 | @include filesrv.c.texi | |
3267 | @end smallexample | |
3268 | ||
3269 | @node Example Receiver | |
3270 | @subsection Example of Reading Datagrams | |
3271 | ||
3272 | Here is the client program corresponding to the server above. | |
3273 | ||
3274 | It sends a datagram to the server and then waits for a reply. Notice | |
3275 | that the socket for the client (as well as for the server) in this | |
3276 | example has to be given a name. This is so that the server can direct | |
3277 | a message back to the client. Since the socket has no associated | |
3278 | connection state, the only way the server can do this is by | |
3279 | referencing the name of the client. | |
3280 | ||
3281 | @smallexample | |
3282 | @include filecli.c.texi | |
3283 | @end smallexample | |
3284 | ||
3285 | Keep in mind that datagram socket communications are unreliable. In | |
3286 | this example, the client program waits indefinitely if the message | |
3287 | never reaches the server or if the server's response never comes | |
04b9968b UD |
3288 | back. It's up to the user running the program to kill and restart |
3289 | it if desired. A more automatic solution could be to use | |
28f540f4 | 3290 | @code{select} (@pxref{Waiting for I/O}) to establish a timeout period |
04b9968b | 3291 | for the reply, and in case of timeout either re-send the message or |
28f540f4 RM |
3292 | shut down the socket and exit. |
3293 | ||
3294 | @node Inetd | |
3295 | @section The @code{inetd} Daemon | |
3296 | ||
3297 | We've explained above how to write a server program that does its own | |
3298 | listening. Such a server must already be running in order for anyone | |
3299 | to connect to it. | |
3300 | ||
04b9968b | 3301 | Another way to provide a service on an Internet port is to let the daemon |
28f540f4 RM |
3302 | program @code{inetd} do the listening. @code{inetd} is a program that |
3303 | runs all the time and waits (using @code{select}) for messages on a | |
3304 | specified set of ports. When it receives a message, it accepts the | |
3305 | connection (if the socket style calls for connections) and then forks a | |
3306 | child process to run the corresponding server program. You specify the | |
3307 | ports and their programs in the file @file{/etc/inetd.conf}. | |
3308 | ||
3309 | @menu | |
3310 | * Inetd Servers:: | |
3311 | * Configuring Inetd:: | |
3312 | @end menu | |
3313 | ||
3314 | @node Inetd Servers | |
3315 | @subsection @code{inetd} Servers | |
3316 | ||
3317 | Writing a server program to be run by @code{inetd} is very simple. Each time | |
3318 | someone requests a connection to the appropriate port, a new server | |
3319 | process starts. The connection already exists at this time; the | |
3320 | socket is available as the standard input descriptor and as the | |
3321 | standard output descriptor (descriptors 0 and 1) in the server | |
04b9968b | 3322 | process. Thus the server program can begin reading and writing data |
28f540f4 RM |
3323 | right away. Often the program needs only the ordinary I/O facilities; |
3324 | in fact, a general-purpose filter program that knows nothing about | |
3325 | sockets can work as a byte stream server run by @code{inetd}. | |
3326 | ||
3327 | You can also use @code{inetd} for servers that use connectionless | |
3328 | communication styles. For these servers, @code{inetd} does not try to accept | |
04b9968b | 3329 | a connection since no connection is possible. It just starts the |
28f540f4 RM |
3330 | server program, which can read the incoming datagram packet from |
3331 | descriptor 0. The server program can handle one request and then | |
3332 | exit, or you can choose to write it to keep reading more requests | |
3333 | until no more arrive, and then exit. You must specify which of these | |
04b9968b | 3334 | two techniques the server uses when you configure @code{inetd}. |
28f540f4 RM |
3335 | |
3336 | @node Configuring Inetd | |
3337 | @subsection Configuring @code{inetd} | |
3338 | ||
3339 | The file @file{/etc/inetd.conf} tells @code{inetd} which ports to listen to | |
3340 | and what server programs to run for them. Normally each entry in the | |
3341 | file is one line, but you can split it onto multiple lines provided | |
3342 | all but the first line of the entry start with whitespace. Lines that | |
3343 | start with @samp{#} are comments. | |
3344 | ||
3345 | Here are two standard entries in @file{/etc/inetd.conf}: | |
3346 | ||
3347 | @smallexample | |
3348 | ftp stream tcp nowait root /libexec/ftpd ftpd | |
3349 | talk dgram udp wait root /libexec/talkd talkd | |
3350 | @end smallexample | |
3351 | ||
3352 | An entry has this format: | |
3353 | ||
3354 | @smallexample | |
3355 | @var{service} @var{style} @var{protocol} @var{wait} @var{username} @var{program} @var{arguments} | |
3356 | @end smallexample | |
3357 | ||
3358 | The @var{service} field says which service this program provides. It | |
3359 | should be the name of a service defined in @file{/etc/services}. | |
3360 | @code{inetd} uses @var{service} to decide which port to listen on for | |
3361 | this entry. | |
3362 | ||
3363 | The fields @var{style} and @var{protocol} specify the communication | |
3364 | style and the protocol to use for the listening socket. The style | |
3365 | should be the name of a communication style, converted to lower case | |
3366 | and with @samp{SOCK_} deleted---for example, @samp{stream} or | |
3367 | @samp{dgram}. @var{protocol} should be one of the protocols listed in | |
3368 | @file{/etc/protocols}. The typical protocol names are @samp{tcp} for | |
3369 | byte stream connections and @samp{udp} for unreliable datagrams. | |
3370 | ||
3371 | The @var{wait} field should be either @samp{wait} or @samp{nowait}. | |
3372 | Use @samp{wait} if @var{style} is a connectionless style and the | |
04b9968b | 3373 | server, once started, handles multiple requests as they come in. |
28f540f4 RM |
3374 | Use @samp{nowait} if @code{inetd} should start a new process for each message |
3375 | or request that comes in. If @var{style} uses connections, then | |
3376 | @var{wait} @strong{must} be @samp{nowait}. | |
3377 | ||
3378 | @var{user} is the user name that the server should run as. @code{inetd} runs | |
3379 | as root, so it can set the user ID of its children arbitrarily. It's | |
3380 | best to avoid using @samp{root} for @var{user} if you can; but some | |
3381 | servers, such as Telnet and FTP, read a username and password | |
3382 | themselves. These servers need to be root initially so they can log | |
3383 | in as commanded by the data coming over the network. | |
3384 | ||
3385 | @var{program} together with @var{arguments} specifies the command to | |
3386 | run to start the server. @var{program} should be an absolute file | |
3387 | name specifying the executable file to run. @var{arguments} consists | |
3388 | of any number of whitespace-separated words, which become the | |
3389 | command-line arguments of @var{program}. The first word in | |
3390 | @var{arguments} is argument zero, which should by convention be the | |
3391 | program name itself (sans directories). | |
3392 | ||
3393 | If you edit @file{/etc/inetd.conf}, you can tell @code{inetd} to reread the | |
3394 | file and obey its new contents by sending the @code{inetd} process the | |
3395 | @code{SIGHUP} signal. You'll have to use @code{ps} to determine the | |
04b9968b | 3396 | process ID of the @code{inetd} process as it is not fixed. |
28f540f4 RM |
3397 | |
3398 | @c !!! could document /etc/inetd.sec | |
3399 | ||
3400 | @node Socket Options | |
3401 | @section Socket Options | |
3402 | @cindex socket options | |
3403 | ||
3404 | This section describes how to read or set various options that modify | |
3405 | the behavior of sockets and their underlying communications protocols. | |
3406 | ||
3407 | @cindex level, for socket options | |
3408 | @cindex socket option level | |
3409 | When you are manipulating a socket option, you must specify which | |
3410 | @dfn{level} the option pertains to. This describes whether the option | |
3411 | applies to the socket interface, or to a lower-level communications | |
3412 | protocol interface. | |
3413 | ||
3414 | @menu | |
3415 | * Socket Option Functions:: The basic functions for setting and getting | |
3416 | socket options. | |
3417 | * Socket-Level Options:: Details of the options at the socket level. | |
3418 | @end menu | |
3419 | ||
3420 | @node Socket Option Functions | |
3421 | @subsection Socket Option Functions | |
3422 | ||
3423 | @pindex sys/socket.h | |
3424 | Here are the functions for examining and modifying socket options. | |
3425 | They are declared in @file{sys/socket.h}. | |
3426 | ||
3427 | @comment sys/socket.h | |
3428 | @comment BSD | |
55c14926 | 3429 | @deftypefun int getsockopt (int @var{socket}, int @var{level}, int @var{optname}, void *@var{optval}, socklen_t *@var{optlen-ptr}) |
973f180b | 3430 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
28f540f4 RM |
3431 | The @code{getsockopt} function gets information about the value of |
3432 | option @var{optname} at level @var{level} for socket @var{socket}. | |
3433 | ||
3434 | The option value is stored in a buffer that @var{optval} points to. | |
3435 | Before the call, you should supply in @code{*@var{optlen-ptr}} the | |
3436 | size of this buffer; on return, it contains the number of bytes of | |
3437 | information actually stored in the buffer. | |
3438 | ||
3439 | Most options interpret the @var{optval} buffer as a single @code{int} | |
3440 | value. | |
3441 | ||
3442 | The actual return value of @code{getsockopt} is @code{0} on success | |
3443 | and @code{-1} on failure. The following @code{errno} error conditions | |
3444 | are defined: | |
3445 | ||
3446 | @table @code | |
3447 | @item EBADF | |
3448 | The @var{socket} argument is not a valid file descriptor. | |
3449 | ||
3450 | @item ENOTSOCK | |
3451 | The descriptor @var{socket} is not a socket. | |
3452 | ||
3453 | @item ENOPROTOOPT | |
3454 | The @var{optname} doesn't make sense for the given @var{level}. | |
3455 | @end table | |
3456 | @end deftypefun | |
3457 | ||
3458 | @comment sys/socket.h | |
3459 | @comment BSD | |
8ded91fb | 3460 | @deftypefun int setsockopt (int @var{socket}, int @var{level}, int @var{optname}, const void *@var{optval}, socklen_t @var{optlen}) |
973f180b | 3461 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
28f540f4 RM |
3462 | This function is used to set the socket option @var{optname} at level |
3463 | @var{level} for socket @var{socket}. The value of the option is passed | |
04b9968b | 3464 | in the buffer @var{optval} of size @var{optlen}. |
28f540f4 | 3465 | |
838e5ffe UD |
3466 | @c Argh. -zw |
3467 | @iftex | |
3468 | @hfuzz 6pt | |
28f540f4 RM |
3469 | The return value and error codes for @code{setsockopt} are the same as |
3470 | for @code{getsockopt}. | |
838e5ffe UD |
3471 | @end iftex |
3472 | @ifinfo | |
3473 | The return value and error codes for @code{setsockopt} are the same as | |
3474 | for @code{getsockopt}. | |
3475 | @end ifinfo | |
3476 | ||
28f540f4 RM |
3477 | @end deftypefun |
3478 | ||
3479 | @node Socket-Level Options | |
3480 | @subsection Socket-Level Options | |
3481 | ||
3482 | @comment sys/socket.h | |
3483 | @comment BSD | |
3484 | @deftypevr Constant int SOL_SOCKET | |
3485 | Use this constant as the @var{level} argument to @code{getsockopt} or | |
3486 | @code{setsockopt} to manipulate the socket-level options described in | |
3487 | this section. | |
3488 | @end deftypevr | |
3489 | ||
3490 | @pindex sys/socket.h | |
838e5ffe | 3491 | @noindent |
28f540f4 | 3492 | Here is a table of socket-level option names; all are defined in the |
9afc8a59 | 3493 | header file @file{sys/socket.h}. |
28f540f4 RM |
3494 | |
3495 | @table @code | |
3496 | @comment sys/socket.h | |
3497 | @comment BSD | |
3498 | @item SO_DEBUG | |
3499 | @c Extra blank line here makes the table look better. | |
3500 | ||
3501 | This option toggles recording of debugging information in the underlying | |
3502 | protocol modules. The value has type @code{int}; a nonzero value means | |
3503 | ``yes''. | |
3504 | @c !!! should say how this is used | |
04b9968b | 3505 | @c OK, anyone who knows, please explain. |
28f540f4 RM |
3506 | |
3507 | @comment sys/socket.h | |
3508 | @comment BSD | |
3509 | @item SO_REUSEADDR | |
3510 | This option controls whether @code{bind} (@pxref{Setting Address}) | |
3511 | should permit reuse of local addresses for this socket. If you enable | |
3512 | this option, you can actually have two sockets with the same Internet | |
3513 | port number; but the system won't allow you to use the two | |
3514 | identically-named sockets in a way that would confuse the Internet. The | |
3515 | reason for this option is that some higher-level Internet protocols, | |
4bca4c17 | 3516 | including FTP, require you to keep reusing the same port number. |
28f540f4 RM |
3517 | |
3518 | The value has type @code{int}; a nonzero value means ``yes''. | |
3519 | ||
3520 | @comment sys/socket.h | |
3521 | @comment BSD | |
3522 | @item SO_KEEPALIVE | |
3523 | This option controls whether the underlying protocol should | |
3524 | periodically transmit messages on a connected socket. If the peer | |
3525 | fails to respond to these messages, the connection is considered | |
3526 | broken. The value has type @code{int}; a nonzero value means | |
3527 | ``yes''. | |
3528 | ||
3529 | @comment sys/socket.h | |
3530 | @comment BSD | |
3531 | @item SO_DONTROUTE | |
3532 | This option controls whether outgoing messages bypass the normal | |
3533 | message routing facilities. If set, messages are sent directly to the | |
3534 | network interface instead. The value has type @code{int}; a nonzero | |
3535 | value means ``yes''. | |
3536 | ||
3537 | @comment sys/socket.h | |
3538 | @comment BSD | |
3539 | @item SO_LINGER | |
3540 | This option specifies what should happen when the socket of a type | |
3541 | that promises reliable delivery still has untransmitted messages when | |
3542 | it is closed; see @ref{Closing a Socket}. The value has type | |
3543 | @code{struct linger}. | |
3544 | ||
3545 | @comment sys/socket.h | |
3546 | @comment BSD | |
3547 | @deftp {Data Type} {struct linger} | |
3548 | This structure type has the following members: | |
3549 | ||
3550 | @table @code | |
3551 | @item int l_onoff | |
3552 | This field is interpreted as a boolean. If nonzero, @code{close} | |
04b9968b | 3553 | blocks until the data are transmitted or the timeout period has expired. |
28f540f4 RM |
3554 | |
3555 | @item int l_linger | |
3556 | This specifies the timeout period, in seconds. | |
3557 | @end table | |
3558 | @end deftp | |
3559 | ||
3560 | @comment sys/socket.h | |
3561 | @comment BSD | |
3562 | @item SO_BROADCAST | |
3563 | This option controls whether datagrams may be broadcast from the socket. | |
3564 | The value has type @code{int}; a nonzero value means ``yes''. | |
3565 | ||
3566 | @comment sys/socket.h | |
3567 | @comment BSD | |
3568 | @item SO_OOBINLINE | |
3569 | If this option is set, out-of-band data received on the socket is | |
3570 | placed in the normal input queue. This permits it to be read using | |
3571 | @code{read} or @code{recv} without specifying the @code{MSG_OOB} | |
3572 | flag. @xref{Out-of-Band Data}. The value has type @code{int}; a | |
3573 | nonzero value means ``yes''. | |
3574 | ||
3575 | @comment sys/socket.h | |
3576 | @comment BSD | |
3577 | @item SO_SNDBUF | |
3578 | This option gets or sets the size of the output buffer. The value is a | |
3579 | @code{size_t}, which is the size in bytes. | |
3580 | ||
3581 | @comment sys/socket.h | |
3582 | @comment BSD | |
3583 | @item SO_RCVBUF | |
3584 | This option gets or sets the size of the input buffer. The value is a | |
3585 | @code{size_t}, which is the size in bytes. | |
3586 | ||
3587 | @comment sys/socket.h | |
3588 | @comment GNU | |
3589 | @item SO_STYLE | |
3590 | @comment sys/socket.h | |
6e953631 | 3591 | @comment BSD |
28f540f4 RM |
3592 | @itemx SO_TYPE |
3593 | This option can be used with @code{getsockopt} only. It is used to | |
3594 | get the socket's communication style. @code{SO_TYPE} is the | |
3595 | historical name, and @code{SO_STYLE} is the preferred name in GNU. | |
3596 | The value has type @code{int} and its value designates a communication | |
3597 | style; see @ref{Communication Styles}. | |
3598 | ||
3599 | @comment sys/socket.h | |
6e953631 | 3600 | @comment BSD |
28f540f4 RM |
3601 | @item SO_ERROR |
3602 | @c Extra blank line here makes the table look better. | |
3603 | ||
3604 | This option can be used with @code{getsockopt} only. It is used to reset | |
3605 | the error status of the socket. The value is an @code{int}, which represents | |
3606 | the previous error status. | |
3607 | @c !!! what is "socket error status"? this is never defined. | |
3608 | @end table | |
3609 | ||
3610 | @node Networks Database | |
3611 | @section Networks Database | |
3612 | @cindex networks database | |
3613 | @cindex converting network number to network name | |
3614 | @cindex converting network name to network number | |
3615 | ||
3616 | @pindex /etc/networks | |
3617 | @pindex netdb.h | |
3618 | Many systems come with a database that records a list of networks known | |
3619 | to the system developer. This is usually kept either in the file | |
3620 | @file{/etc/networks} or in an equivalent from a name server. This data | |
3621 | base is useful for routing programs such as @code{route}, but it is not | |
3622 | useful for programs that simply communicate over the network. We | |
04b9968b | 3623 | provide functions to access this database, which are declared in |
28f540f4 RM |
3624 | @file{netdb.h}. |
3625 | ||
3626 | @comment netdb.h | |
3627 | @comment BSD | |
3628 | @deftp {Data Type} {struct netent} | |
3629 | This data type is used to represent information about entries in the | |
3630 | networks database. It has the following members: | |
3631 | ||
3632 | @table @code | |
3633 | @item char *n_name | |
3634 | This is the ``official'' name of the network. | |
3635 | ||
3636 | @item char **n_aliases | |
3637 | These are alternative names for the network, represented as a vector | |
3638 | of strings. A null pointer terminates the array. | |
3639 | ||
3640 | @item int n_addrtype | |
3641 | This is the type of the network number; this is always equal to | |
3642 | @code{AF_INET} for Internet networks. | |
3643 | ||
3644 | @item unsigned long int n_net | |
3645 | This is the network number. Network numbers are returned in host | |
3646 | byte order; see @ref{Byte Order}. | |
3647 | @end table | |
3648 | @end deftp | |
3649 | ||
3650 | Use the @code{getnetbyname} or @code{getnetbyaddr} functions to search | |
3651 | the networks database for information about a specific network. The | |
3652 | information is returned in a statically-allocated structure; you must | |
3653 | copy the information if you need to save it. | |
3654 | ||
3655 | @comment netdb.h | |
3656 | @comment BSD | |
3657 | @deftypefun {struct netent *} getnetbyname (const char *@var{name}) | |
973f180b AO |
3658 | @safety{@prelim{}@mtunsafe{@mtasurace{:netbyname} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} |
3659 | @c getnetbyname =~ getpwuid @mtasurace:netbyname @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
3660 | @c libc_lock_lock dup @asulock @aculock | |
3661 | @c malloc dup @ascuheap @acsmem | |
3662 | @c getnetbyname_r dup @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
3663 | @c realloc dup @ascuheap @acsmem | |
3664 | @c free dup @ascuheap @acsmem | |
3665 | @c libc_lock_unlock dup @aculock | |
3666 | @c | |
3667 | @c getnetbyname_r =~ getpwuid_r @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
3668 | @c no nscd support | |
3669 | @c res_maybe_init(!preinit) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd | |
3670 | @c nss_networks_lookup2 =~ nss_passwd_lookup2 @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
3671 | @c *fct.l -> _nss_*_getnetbyname_r @ascuplugin | |
3672 | @c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
28f540f4 RM |
3673 | The @code{getnetbyname} function returns information about the network |
3674 | named @var{name}. It returns a null pointer if there is no such | |
3675 | network. | |
3676 | @end deftypefun | |
3677 | ||
3678 | @comment netdb.h | |
3679 | @comment BSD | |
8ded91fb | 3680 | @deftypefun {struct netent *} getnetbyaddr (uint32_t @var{net}, int @var{type}) |
973f180b AO |
3681 | @safety{@prelim{}@mtunsafe{@mtasurace{:netbyaddr} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} |
3682 | @c getnetbyaddr =~ getpwuid @mtasurace:netbyaddr @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
3683 | @c libc_lock_lock dup @asulock @aculock | |
3684 | @c malloc dup @ascuheap @acsmem | |
3685 | @c getnetbyaddr_r dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
3686 | @c realloc dup @ascuheap @acsmem | |
3687 | @c free dup @ascuheap @acsmem | |
3688 | @c libc_lock_unlock dup @aculock | |
3689 | @c | |
3690 | @c getnetbyaddr_r =~ getpwuid_r @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
3691 | @c no nscd support | |
3692 | @c nss_networks_lookup2 =~ nss_passwd_lookup2 @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
3693 | @c *fct.l -> _nss_*_getnetbyaddr_r @ascuplugin | |
3694 | @c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
28f540f4 RM |
3695 | The @code{getnetbyaddr} function returns information about the network |
3696 | of type @var{type} with number @var{net}. You should specify a value of | |
6e953631 | 3697 | @code{AF_INET} for the @var{type} argument for Internet networks. |
28f540f4 RM |
3698 | |
3699 | @code{getnetbyaddr} returns a null pointer if there is no such | |
3700 | network. | |
3701 | @end deftypefun | |
3702 | ||
3703 | You can also scan the networks database using @code{setnetent}, | |
04b9968b UD |
3704 | @code{getnetent} and @code{endnetent}. Be careful when using these |
3705 | functions because they are not reentrant. | |
28f540f4 RM |
3706 | |
3707 | @comment netdb.h | |
3708 | @comment BSD | |
3709 | @deftypefun void setnetent (int @var{stayopen}) | |
973f180b AO |
3710 | @safety{@prelim{}@mtunsafe{@mtasurace{:netent} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} |
3711 | @c setnetent @mtasurace:netent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
3712 | @c libc_lock_lock dup @asulock @aculock | |
3713 | @c nss_setent(nss_networks_lookup2) @mtasurace:netent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
3714 | @c res_maybe_init(!preinit) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd | |
3715 | @c setup(nss_networks_lookup2) @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
3716 | @c *lookup_fct = nss_networks_lookup2 dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
3717 | @c nss_lookup dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
3718 | @c *fct.f @mtasurace:netent @ascuplugin | |
3719 | @c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
3720 | @c libc_lock_unlock dup @aculock | |
28f540f4 RM |
3721 | This function opens and rewinds the networks database. |
3722 | ||
3723 | If the @var{stayopen} argument is nonzero, this sets a flag so that | |
3724 | subsequent calls to @code{getnetbyname} or @code{getnetbyaddr} will | |
3725 | not close the database (as they usually would). This makes for more | |
3726 | efficiency if you call those functions several times, by avoiding | |
3727 | reopening the database for each call. | |
3728 | @end deftypefun | |
3729 | ||
3730 | @comment netdb.h | |
3731 | @comment BSD | |
3732 | @deftypefun {struct netent *} getnetent (void) | |
973f180b AO |
3733 | @safety{@prelim{}@mtunsafe{@mtasurace{:netent} @mtasurace{:netentbuf} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} |
3734 | @c getnetent @mtasurace:netent @mtasurace:netentbuf @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
3735 | @c libc_lock_lock dup @asulock @aculock | |
3736 | @c nss_getent(getnetent_r) @mtasurace:netent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
3737 | @c malloc dup @ascuheap @acsmem | |
3738 | @c *func = getnetent_r dup @mtasurace:netent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
3739 | @c realloc dup @ascuheap @acsmem | |
3740 | @c free dup @ascuheap @acsmem | |
3741 | @c libc_lock_unlock dup @aculock | |
3742 | @c | |
3743 | @c getnetent_r @mtasurace:netent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
3744 | @c libc_lock_lock dup @asulock @aculock | |
3745 | @c nss_getent_r(nss_networks_lookup2) @mtasurace:netent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
3746 | @c res_maybe_init(!preinit) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd | |
3747 | @c setup(nss_networks_lookup2) dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
3748 | @c *fct.f @mtasurace:servent @ascuplugin | |
3749 | @c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
3750 | @c nss_lookup dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
3751 | @c *sfct.f @mtasurace:netent @ascuplugin | |
3752 | @c libc_lock_unlock dup @aculock | |
28f540f4 RM |
3753 | This function returns the next entry in the networks database. It |
3754 | returns a null pointer if there are no more entries. | |
3755 | @end deftypefun | |
3756 | ||
3757 | @comment netdb.h | |
3758 | @comment BSD | |
3759 | @deftypefun void endnetent (void) | |
973f180b AO |
3760 | @safety{@prelim{}@mtunsafe{@mtasurace{:netent} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} |
3761 | @c endnetent @mtasurace:netent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
3762 | @c libc_lock_lock @asulock @aculock | |
3763 | @c nss_endent(nss_networks_lookup2) @mtasurace:netent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
3764 | @c res_maybe_init(!preinit) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd | |
3765 | @c setup(nss_networks_lookup2) dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
3766 | @c *fct.f @mtasurace:netent @ascuplugin | |
3767 | @c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
3768 | @c libc_lock_unlock @aculock | |
28f540f4 RM |
3769 | This function closes the networks database. |
3770 | @end deftypefun |