← Back to branch summary

~ubuntu-branches/ubuntu/utopic/eglibc/utopic

« back to all changes in this revision

Viewing changes to manual/socket.texi

  • Committer: Package Import Robot
  • Author(s): Adam Conrad
  • Date: 2012-10-26 05:14:58 UTC
  • mfrom: (1.5.1) (4.4.22 experimental)
  • Revision ID: package-import@ubuntu.com-20121026051458-oryotr4i03ob5pab
Tags: 2.16-0ubuntu1
* Merge with unreleased 2.16 in Debian experimental, remaining changes:
  - Drop the Breaks line from libc6, which refers to a Debian transition
  - Remove the libc6 recommends on libc6-i686, which we don't build
  - Enable libc6{,-dev}-armel on armhf and libc6{-dev}-armhf on armel
  - Ship update-locale and validlocale in /usr/sbin in libc-bin
  - Don't build locales or locales-all in Ubuntu, we rely on langpacks
  - Heavily mangle the way we do service restarting on major upgrades
  - Use different MIN_KERNEL_SUPPORTED versions than Debian, due to
    buildd needs.  This should be universally bumped to 3.2.0 once all
    our buildds (including the PPA guests) are running precise kernels
  - Build i386 variants as -march=i686, build amd64 with -O3, and build
    ppc64 variants (both 64-bit and 32-bit) with -O3 -fno-tree-vectorize
  - Re-enable unsubmitted-ldconfig-cache-abi.diff and rebuild the cache
    on upgrades from previous versions that used a different constant
  - debian/patches/any/local-CVE-2012-3406.diff: switch to malloc when
    array grows too large to handle via alloca extension (CVE-2012-3406)
  - Build generic i386/i686 flavour with -mno-tls-direct-seg-refs
* Changes added/dropped with this merge while reducing our delta:
  - Stop building glibc docs from the eglibc source, and instead make
    the glibc-docs stub have a hard dependency on glibc-doc-reference
  - Remove outdated conflicts against ancient versions of ia32-libs
  - Drop the tzdata dependency from libc6, it's in required and minimal
  - Use gcc-4.7/g++-4.7 by default on all our supported architectures
  - Save our historical changelog as changelog.ubuntu in the source
  - Drop nscd's libaudit build-dep for now, as libaudit is in universe
  - Drop the unnecessary Breaks from libc6 to locales and locales-all
  - Ship xen's ld.so.conf.d snippet as /etc/ld.so.conf.d/libc6-xen.conf
* Disable hard failures on the test suite for the first upload to raring

Show diffs side-by-side

added added

removed removed

Lines of Context:
manual/socket.texi
1
 
@node Sockets, Low-Level Terminal Interface, Pipes and FIFOs, Top
2
 
@c %MENU% A more complicated IPC mechanism, with networking support
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.
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.
17
 
 
18
 
Not all operating systems support sockets.  In the GNU library, the
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
21
 
not really support sockets these functions always fail.
22
 
 
23
 
@strong{Incomplete:} We do not currently document the facilities for
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.
27
 
 
28
 
@menu
29
 
* Socket Concepts::     Basic concepts you need to know about.
30
 
* Communication Styles::Stream communication, datagrams and other styles.
31
 
* Socket Addresses::    How socket names (``addresses'') work.
32
 
* Interface Naming::    Identifying specific network interfaces.
33
 
* Local Namespace::     Details about the local namespace.
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
63
 
styles regard the data as a sequence of bytes with no larger
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
83
 
@dfn{connection} with one remote socket and then exchange data
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
114
 
operating system and you need not know about them.  What you do need to
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
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
131
 
number.  And that's what you should normally do---use the default.
132
 
@end itemize
133
 
 
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
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
145
 
possible.
146
 
 
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
151
 
which require that references to 32-bit variables be passed can be as
152
 
happy as implementations which use 64-bit values.
153
 
 
154
 
 
155
 
@node Communication Styles
156
 
@section Communication Styles
157
 
 
158
 
The GNU library includes support for several different kinds of sockets,
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
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
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
178
 
individually-addressed packets unreliably.
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
192
 
acceptable to simply re-send a packet if no response is seen in a
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
205
 
This style is like @code{SOCK_STREAM} except that the data are
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
264
 
discriminates based on address; for example, the rsh and rlogin
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}).
267
 
 
268
 
The details of socket addresses vary depending on what namespace you are
269
 
using.  @xref{Local Namespace}, or @ref{Internet Namespace}, for specific
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
 
 
295
 
Thus, the usual practice is to construct an address of the proper
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
300
 
sockaddr} data type is the @dfn{address format designator}.  This tells
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
309
 
@deftp {Data Type} {struct sockaddr}
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
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
335
 
Details}, for information about this address format.
336
 
 
337
 
@comment sys/socket.h
338
 
@comment BSD, Unix98
339
 
@item AF_UNIX
340
 
@vindex AF_UNIX
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}).
347
 
 
348
 
@comment sys/socket.h
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}.)
354
 
 
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.)
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.)
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
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
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}.
392
 
For examples of use, see @ref{Local Socket Example}, or see @ref{Inet Example}.
393
 
 
394
 
@comment sys/socket.h
395
 
@comment BSD
396
 
@deftypefun int bind (int @var{socket}, struct sockaddr *@var{addr}, socklen_t @var{length})
397
 
The @code{bind} function assigns an address to the socket
398
 
@var{socket}.  The @var{addr} and @var{length} arguments specify the
399
 
address; the detailed format of the address depends on the namespace.
400
 
The first part of the address is always the format designator, which
401
 
specifies a namespace, and says that the address is in the format of
402
 
that namespace.
403
 
 
404
 
The return value is @code{0} on success and @code{-1} on failure.  The
405
 
following @code{errno} error conditions are defined for this function:
406
 
 
407
 
@table @code
408
 
@item EBADF
409
 
The @var{socket} argument is not a valid file descriptor.
410
 
 
411
 
@item ENOTSOCK
412
 
The descriptor @var{socket} is not a socket.
413
 
 
414
 
@item EADDRNOTAVAIL
415
 
The specified address is not available on this machine.
416
 
 
417
 
@item EADDRINUSE
418
 
Some other socket is already using the specified address.
419
 
 
420
 
@item EINVAL
421
 
The socket @var{socket} already has an address.
422
 
 
423
 
@item EACCES
424
 
You do not have permission to access the requested address.  (In the
425
 
Internet domain, only the super-user is allowed to specify a port number
426
 
in the range 0 through @code{IPPORT_RESERVED} minus one; see
427
 
@ref{Ports}.)
428
 
@end table
429
 
 
430
 
Additional conditions may be possible depending on the particular namespace
431
 
of the socket.
432
 
@end deftypefun
433
 
 
434
 
@node Reading Address
435
 
@subsection Reading the Address of a Socket
436
 
 
437
 
@pindex sys/socket.h
438
 
Use the function @code{getsockname} to examine the address of an
439
 
Internet socket.  The prototype for this function is in the header file
440
 
@file{sys/socket.h}.
441
 
 
442
 
@comment sys/socket.h
443
 
@comment BSD
444
 
@deftypefun int getsockname (int @var{socket}, struct sockaddr *@var{addr}, socklen_t *@var{length-ptr})
445
 
The @code{getsockname} function returns information about the
446
 
address of the socket @var{socket} in the locations specified by the
447
 
@var{addr} and @var{length-ptr} arguments.  Note that the
448
 
@var{length-ptr} is a pointer; you should initialize it to be the
449
 
allocation size of @var{addr}, and on return it contains the actual
450
 
size of the address data.
451
 
 
452
 
The format of the address data depends on the socket namespace.  The
453
 
length of the information is usually fixed for a given namespace, so
454
 
normally you can know exactly how much space is needed and can provide
455
 
that much.  The usual practice is to allocate a place for the value
456
 
using the proper data type for the socket's namespace, then cast its
457
 
address to @code{struct sockaddr *} to pass it to @code{getsockname}.
458
 
 
459
 
The return value is @code{0} on success and @code{-1} on error.  The
460
 
following @code{errno} error conditions are defined for this function:
461
 
 
462
 
@table @code
463
 
@item EBADF
464
 
The @var{socket} argument is not a valid file descriptor.
465
 
 
466
 
@item ENOTSOCK
467
 
The descriptor @var{socket} is not a socket.
468
 
 
469
 
@item ENOBUFS
470
 
There are not enough internal buffers available for the operation.
471
 
@end table
472
 
@end deftypefun
473
 
 
474
 
You can't read the address of a socket in the file namespace.  This is
475
 
consistent with the rest of the system; in general, there's no way to
476
 
find a file's name from a descriptor for that file.
477
 
 
478
 
@node Interface Naming
479
 
@section Interface Naming
480
 
 
481
 
Each network interface has a name.  This usually consists of a few
482
 
letters that relate to the type of interface, which may be followed by a
483
 
number if there is more than one interface of that type.  Examples
484
 
might be @code{lo} (the loopback interface) and @code{eth0} (the first
485
 
Ethernet interface).
486
 
 
487
 
Although such names are convenient for humans, it would be clumsy to
488
 
have to use them whenever a program needs to refer to an interface.  In
489
 
such situations an interface is referred to by its @dfn{index}, which is
490
 
an arbitrarily-assigned small positive integer.
491
 
 
492
 
The following functions, constants and data types are declared in the
493
 
header file @file{net/if.h}.
494
 
 
495
 
@comment net/if.h
496
 
@deftypevr Constant size_t IFNAMSIZ
497
 
This constant defines the maximum buffer size needed to hold an
498
 
interface name, including its terminating zero byte.
499
 
@end deftypevr
500
 
 
501
 
@comment net/if.h
502
 
@comment IPv6 basic API
503
 
@deftypefun {unsigned int} if_nametoindex (const char *ifname)
504
 
This function yields the interface index corresponding to a particular
505
 
name.  If no interface exists with the name given, it returns 0.
506
 
@end deftypefun
507
 
 
508
 
@comment net/if.h
509
 
@comment IPv6 basic API
510
 
@deftypefun {char *} if_indextoname (unsigned int ifindex, char *ifname)
511
 
This function maps an interface index to its corresponding name.  The
512
 
returned name is placed in the buffer pointed to by @code{ifname}, which
513
 
must be at least @code{IFNAMSIZ} bytes in length.  If the index was
514
 
invalid, the function's return value is a null pointer, otherwise it is
515
 
@code{ifname}.
516
 
@end deftypefun
517
 
 
518
 
@comment net/if.h
519
 
@comment IPv6 basic API
520
 
@deftp {Data Type} {struct if_nameindex}
521
 
This data type is used to hold the information about a single
522
 
interface.  It has the following members:
523
 
 
524
 
@table @code
525
 
@item unsigned int if_index;
526
 
This is the interface index.
527
 
 
528
 
@item char *if_name
529
 
This is the null-terminated index name.
530
 
 
531
 
@end table
532
 
@end deftp
533
 
 
534
 
@comment net/if.h
535
 
@comment IPv6 basic API
536
 
@deftypefun {struct if_nameindex *} if_nameindex (void)
537
 
This function returns an array of @code{if_nameindex} structures, one
538
 
for every interface that is present.  The end of the list is indicated
539
 
by a structure with an interface of 0 and a null name pointer.  If an
540
 
error occurs, this function returns a null pointer.
541
 
 
542
 
The returned structure must be freed with @code{if_freenameindex} after
543
 
use.
544
 
@end deftypefun
545
 
 
546
 
@comment net/if.h
547
 
@comment IPv6 basic API
548
 
@deftypefun void if_freenameindex (struct if_nameindex *ptr)
549
 
This function frees the structure returned by an earlier call to
550
 
@code{if_nameindex}.
551
 
@end deftypefun
552
 
 
553
 
@node Local Namespace
554
 
@section The Local Namespace
555
 
@cindex local namespace, for sockets
556
 
 
557
 
This section describes the details of the local namespace, whose
558
 
symbolic name (required when you create a socket) is @code{PF_LOCAL}.
559
 
The local namespace is also known as ``Unix domain sockets''.  Another
560
 
name is file namespace since socket addresses are normally implemented
561
 
as file names.
562
 
 
563
 
@menu
564
 
* Concepts: Local Namespace Concepts. What you need to understand.
565
 
* Details: Local Namespace Details.   Address format, symbolic names, etc.
566
 
* Example: Local Socket Example.      Example of creating a socket.
567
 
@end menu
568
 
 
569
 
@node Local Namespace Concepts
570
 
@subsection Local Namespace Concepts
571
 
 
572
 
In the local namespace socket addresses are file names.  You can specify
573
 
any file name you want as the address of the socket, but you must have
574
 
write permission on the directory containing it.
575
 
@c XXX The following was said to be wrong.
576
 
@c In order to connect to a socket you must have read permission for it.
577
 
It's common to put these files in the @file{/tmp} directory.
578
 
 
579
 
One peculiarity of the local namespace is that the name is only used
580
 
when opening the connection; once open the address is not meaningful and
581
 
may not exist.
582
 
 
583
 
Another peculiarity is that you cannot connect to such a socket from
584
 
another machine--not even if the other machine shares the file system
585
 
which contains the name of the socket.  You can see the socket in a
586
 
directory listing, but connecting to it never succeeds.  Some programs
587
 
take advantage of this, such as by asking the client to send its own
588
 
process ID, and using the process IDs to distinguish between clients.
589
 
However, we recommend you not use this method in protocols you design,
590
 
as we might someday permit connections from other machines that mount
591
 
the same file systems.  Instead, send each new client an identifying
592
 
number if you want it to have one.
593
 
 
594
 
After you close a socket in the local namespace, you should delete the
595
 
file name from the file system.  Use @code{unlink} or @code{remove} to
596
 
do this; see @ref{Deleting Files}.
597
 
 
598
 
The local namespace supports just one protocol for any communication
599
 
style; it is protocol number @code{0}.
600
 
 
601
 
@node Local Namespace Details
602
 
@subsection Details of Local Namespace
603
 
 
604
 
@pindex sys/socket.h
605
 
To create a socket in the local namespace, use the constant
606
 
@code{PF_LOCAL} as the @var{namespace} argument to @code{socket} or
607
 
@code{socketpair}.  This constant is defined in @file{sys/socket.h}.
608
 
 
609
 
@comment sys/socket.h
610
 
@comment POSIX
611
 
@deftypevr Macro int PF_LOCAL
612
 
This designates the local namespace, in which socket addresses are local
613
 
names, and its associated family of protocols.  @code{PF_Local} is the
614
 
macro used by Posix.1g.
615
 
@end deftypevr
616
 
 
617
 
@comment sys/socket.h
618
 
@comment BSD
619
 
@deftypevr Macro int PF_UNIX
620
 
This is a synonym for @code{PF_LOCAL}, for compatibility's sake.
621
 
@end deftypevr
622
 
 
623
 
@comment sys/socket.h
624
 
@comment GNU
625
 
@deftypevr Macro int PF_FILE
626
 
This is a synonym for @code{PF_LOCAL}, for compatibility's sake.
627
 
@end deftypevr
628
 
 
629
 
The structure for specifying socket names in the local namespace is
630
 
defined in the header file @file{sys/un.h}:
631
 
@pindex sys/un.h
632
 
 
633
 
@comment sys/un.h
634
 
@comment BSD
635
 
@deftp {Data Type} {struct sockaddr_un}
636
 
This structure is used to specify local namespace socket addresses.  It has
637
 
the following members:
638
 
 
639
 
@table @code
640
 
@item short int sun_family
641
 
This identifies the address family or format of the socket address.
642
 
You should store the value @code{AF_LOCAL} to designate the local
643
 
namespace.  @xref{Socket Addresses}.
644
 
 
645
 
@item char sun_path[108]
646
 
This is the file name to use.
647
 
 
648
 
@strong{Incomplete:}  Why is 108 a magic number?  RMS suggests making
649
 
this a zero-length array and tweaking the following example to use
650
 
@code{alloca} to allocate an appropriate amount of storage based on
651
 
the length of the filename.
652
 
@end table
653
 
@end deftp
654
 
 
655
 
You should compute the @var{length} parameter for a socket address in
656
 
the local namespace as the sum of the size of the @code{sun_family}
657
 
component and the string length (@emph{not} the allocation size!) of
658
 
the file name string.  This can be done using the macro @code{SUN_LEN}:
659
 
 
660
 
@comment sys/un.h
661
 
@comment BSD
662
 
@deftypefn {Macro} int SUN_LEN (@emph{struct sockaddr_un *} @var{ptr})
663
 
The macro computes the length of socket address in the local namespace.
664
 
@end deftypefn
665
 
 
666
 
@node Local Socket Example
667
 
@subsection Example of Local-Namespace Sockets
668
 
 
669
 
Here is an example showing how to create and name a socket in the local
670
 
namespace.
671
 
 
672
 
@smallexample
673
 
@include mkfsock.c.texi
674
 
@end smallexample
675
 
 
676
 
@node Internet Namespace
677
 
@section The Internet Namespace
678
 
@cindex Internet namespace, for sockets
679
 
 
680
 
This section describes the details of the protocols and socket naming
681
 
conventions used in the Internet namespace.
682
 
 
683
 
Originally the Internet namespace used only IP version 4 (IPv4).  With
684
 
the growing number of hosts on the Internet, a new protocol with a
685
 
larger address space was necessary: IP version 6 (IPv6).  IPv6
686
 
introduces 128-bit addresses (IPv4 has 32-bit addresses) and other
687
 
features, and will eventually replace IPv4.
688
 
 
689
 
To create a socket in the IPv4 Internet namespace, use the symbolic name
690
 
@code{PF_INET} of this namespace as the @var{namespace} argument to
691
 
@code{socket} or @code{socketpair}.  For IPv6 addresses you need the
692
 
macro @code{PF_INET6}. These macros are defined in @file{sys/socket.h}.
693
 
@pindex sys/socket.h
694
 
 
695
 
@comment sys/socket.h
696
 
@comment BSD
697
 
@deftypevr Macro int PF_INET
698
 
This designates the IPv4 Internet namespace and associated family of
699
 
protocols.
700
 
@end deftypevr
701
 
 
702
 
@comment sys/socket.h
703
 
@comment X/Open
704
 
@deftypevr Macro int PF_INET6
705
 
This designates the IPv6 Internet namespace and associated family of
706
 
protocols.
707
 
@end deftypevr
708
 
 
709
 
A socket address for the Internet namespace includes the following components:
710
 
 
711
 
@itemize @bullet
712
 
@item
713
 
The address of the machine you want to connect to.  Internet addresses
714
 
can be specified in several ways; these are discussed in @ref{Internet
715
 
Address Formats}, @ref{Host Addresses} and @ref{Host Names}.
716
 
 
717
 
@item
718
 
A port number for that machine.  @xref{Ports}.
719
 
@end itemize
720
 
 
721
 
You must ensure that the address and port number are represented in a
722
 
canonical format called @dfn{network byte order}.  @xref{Byte Order},
723
 
for information about this.
724
 
 
725
 
@menu
726
 
* Internet Address Formats::    How socket addresses are specified in the
727
 
                                 Internet namespace.
728
 
* Host Addresses::              All about host addresses of Internet host.
729
 
* Protocols Database::          Referring to protocols by name.
730
 
* Ports::                       Internet port numbers.
731
 
* Services Database::           Ports may have symbolic names.
732
 
* Byte Order::                  Different hosts may use different byte
733
 
                                 ordering conventions; you need to
734
 
                                 canonicalize host address and port number.
735
 
* Inet Example::                Putting it all together.
736
 
@end menu
737
 
 
738
 
@node Internet Address Formats
739
 
@subsection Internet Socket Address Formats
740
 
 
741
 
In the Internet namespace, for both IPv4 (@code{AF_INET}) and IPv6
742
 
(@code{AF_INET6}), a socket address consists of a host address
743
 
and a port on that host.  In addition, the protocol you choose serves
744
 
effectively as a part of the address because local port numbers are
745
 
meaningful only within a particular protocol.
746
 
 
747
 
The data types for representing socket addresses in the Internet namespace
748
 
are defined in the header file @file{netinet/in.h}.
749
 
@pindex netinet/in.h
750
 
 
751
 
@comment netinet/in.h
752
 
@comment BSD
753
 
@deftp {Data Type} {struct sockaddr_in}
754
 
This is the data type used to represent socket addresses in the
755
 
Internet namespace.  It has the following members:
756
 
 
757
 
@table @code
758
 
@item sa_family_t sin_family
759
 
This identifies the address family or format of the socket address.
760
 
You should store the value @code{AF_INET} in this member.
761
 
@xref{Socket Addresses}.
762
 
 
763
 
@item struct in_addr sin_addr
764
 
This is the Internet address of the host machine.  @xref{Host
765
 
Addresses}, and @ref{Host Names}, for how to get a value to store
766
 
here.
767
 
 
768
 
@item unsigned short int sin_port
769
 
This is the port number.  @xref{Ports}.
770
 
@end table
771
 
@end deftp
772
 
 
773
 
When you call @code{bind} or @code{getsockname}, you should specify
774
 
@code{sizeof (struct sockaddr_in)} as the @var{length} parameter if
775
 
you are using an IPv4 Internet namespace socket address.
776
 
 
777
 
@deftp {Data Type} {struct sockaddr_in6}
778
 
This is the data type used to represent socket addresses in the IPv6
779
 
namespace.  It has the following members:
780
 
 
781
 
@table @code
782
 
@item sa_family_t sin6_family
783
 
This identifies the address family or format of the socket address.
784
 
You should store the value of @code{AF_INET6} in this member.
785
 
@xref{Socket Addresses}.
786
 
 
787
 
@item struct in6_addr sin6_addr
788
 
This is the IPv6 address of the host machine.  @xref{Host
789
 
Addresses}, and @ref{Host Names}, for how to get a value to store
790
 
here.
791
 
 
792
 
@item uint32_t sin6_flowinfo
793
 
This is a currently unimplemented field.
794
 
 
795
 
@item uint16_t sin6_port
796
 
This is the port number.  @xref{Ports}.
797
 
 
798
 
@end table
799
 
@end deftp
800
 
 
801
 
@node Host Addresses
802
 
@subsection Host Addresses
803
 
 
804
 
Each computer on the Internet has one or more @dfn{Internet addresses},
805
 
numbers which identify that computer among all those on the Internet.
806
 
Users typically write IPv4 numeric host addresses as sequences of four
807
 
numbers, separated by periods, as in @samp{128.52.46.32}, and IPv6
808
 
numeric host addresses as sequences of up to eight numbers separated by
809
 
colons, as in @samp{5f03:1200:836f:c100::1}.
810
 
 
811
 
Each computer also has one or more @dfn{host names}, which are strings
812
 
of words separated by periods, as in @samp{mescaline.gnu.org}.
813
 
 
814
 
Programs that let the user specify a host typically accept both numeric
815
 
addresses and host names.  To open a connection a program needs a
816
 
numeric address, and so must convert a host name to the numeric address
817
 
it stands for.
818
 
 
819
 
@menu
820
 
* Abstract Host Addresses::     What a host number consists of.
821
 
* Data type: Host Address Data Type.    Data type for a host number.
822
 
* Functions: Host Address Functions.    Functions to operate on them.
823
 
* Names: Host Names.            Translating host names to host numbers.
824
 
@end menu
825
 
 
826
 
@node Abstract Host Addresses
827
 
@subsubsection Internet Host Addresses
828
 
@cindex host address, Internet
829
 
@cindex Internet host address
830
 
 
831
 
@ifinfo
832
 
Each computer on the Internet has one or more Internet addresses,
833
 
numbers which identify that computer among all those on the Internet.
834
 
@end ifinfo
835
 
 
836
 
@cindex network number
837
 
@cindex local network address number
838
 
An IPv4 Internet host address is a number containing four bytes of data.
839
 
Historically these are divided into two parts, a @dfn{network number} and a
840
 
@dfn{local network address number} within that network.  In the
841
 
mid-1990s classless addresses were introduced which changed this
842
 
behavior.  Since some functions implicitly expect the old definitions,
843
 
we first describe the class-based network and will then describe
844
 
classless addresses.  IPv6 uses only classless addresses and therefore
845
 
the following paragraphs don't apply.
846
 
 
847
 
The class-based IPv4 network number consists of the first one, two or
848
 
three bytes; the rest of the bytes are the local address.
849
 
 
850
 
IPv4 network numbers are registered with the Network Information Center
851
 
(NIC), and are divided into three classes---A, B and C.  The local
852
 
network address numbers of individual machines are registered with the
853
 
administrator of the particular network.
854
 
 
855
 
Class A networks have single-byte numbers in the range 0 to 127.  There
856
 
are only a small number of Class A networks, but they can each support a
857
 
very large number of hosts.  Medium-sized Class B networks have two-byte
858
 
network numbers, with the first byte in the range 128 to 191.  Class C
859
 
networks are the smallest; they have three-byte network numbers, with
860
 
the first byte in the range 192-255.  Thus, the first 1, 2, or 3 bytes
861
 
of an Internet address specify a network.  The remaining bytes of the
862
 
Internet address specify the address within that network.
863
 
 
864
 
The Class A network 0 is reserved for broadcast to all networks.  In
865
 
addition, the host number 0 within each network is reserved for broadcast
866
 
to all hosts in that network.  These uses are obsolete now but for
867
 
compatibility reasons you shouldn't use network 0 and host number 0.
868
 
 
869
 
The Class A network 127 is reserved for loopback; you can always use
870
 
the Internet address @samp{127.0.0.1} to refer to the host machine.
871
 
 
872
 
Since a single machine can be a member of multiple networks, it can
873
 
have multiple Internet host addresses.  However, there is never
874
 
supposed to be more than one machine with the same host address.
875
 
 
876
 
@c !!! this section could document the IN_CLASS* macros in <netinet/in.h>.
877
 
@c No, it shouldn't since they're obsolete.
878
 
 
879
 
@cindex standard dot notation, for Internet addresses
880
 
@cindex dot notation, for Internet addresses
881
 
There are four forms of the @dfn{standard numbers-and-dots notation}
882
 
for Internet addresses:
883
 
 
884
 
@table @code
885
 
@item @var{a}.@var{b}.@var{c}.@var{d}
886
 
This specifies all four bytes of the address individually and is the
887
 
commonly used representation.
888
 
 
889
 
@item @var{a}.@var{b}.@var{c}
890
 
The last part of the address, @var{c}, is interpreted as a 2-byte quantity.
891
 
This is useful for specifying host addresses in a Class B network with
892
 
network address number @code{@var{a}.@var{b}}.
893
 
 
894
 
@item @var{a}.@var{b}
895
 
The last part of the address, @var{b}, is interpreted as a 3-byte quantity.
896
 
This is useful for specifying host addresses in a Class A network with
897
 
network address number @var{a}.
898
 
 
899
 
@item @var{a}
900
 
If only one part is given, this corresponds directly to the host address
901
 
number.
902
 
@end table
903
 
 
904
 
Within each part of the address, the usual C conventions for specifying
905
 
the radix apply.  In other words, a leading @samp{0x} or @samp{0X} implies
906
 
hexadecimal radix; a leading @samp{0} implies octal; and otherwise decimal
907
 
radix is assumed.
908
 
 
909
 
@subsubheading Classless Addresses
910
 
 
911
 
IPv4 addresses (and IPv6 addresses also) are now considered classless;
912
 
the distinction between classes A, B and C can be ignored.  Instead an
913
 
IPv4 host address consists of a 32-bit address and a 32-bit mask.  The
914
 
mask contains set bits for the network part and cleared bits for the
915
 
host part.  The network part is contiguous from the left, with the
916
 
remaining bits representing the host.  As a consequence, the netmask can
917
 
simply be specified as the number of set bits.  Classes A, B and C are
918
 
just special cases of this general rule.  For example, class A addresses
919
 
have a netmask of @samp{255.0.0.0} or a prefix length of 8.
920
 
 
921
 
Classless IPv4 network addresses are written in numbers-and-dots
922
 
notation with the prefix length appended and a slash as separator.  For
923
 
example the class A network 10 is written as @samp{10.0.0.0/8}.
924
 
 
925
 
@subsubheading IPv6 Addresses
926
 
 
927
 
IPv6 addresses contain 128 bits (IPv4 has 32 bits) of data.  A host
928
 
address is usually written as eight 16-bit hexadecimal numbers that are
929
 
separated by colons.  Two colons are used to abbreviate strings of
930
 
consecutive zeros.  For example, the IPv6 loopback address
931
 
@samp{0:0:0:0:0:0:0:1} can just be written as @samp{::1}.
932
 
 
933
 
@node Host Address Data Type
934
 
@subsubsection Host Address Data Type
935
 
 
936
 
IPv4 Internet host addresses are represented in some contexts as integers
937
 
(type @code{uint32_t}).  In other contexts, the integer is
938
 
packaged inside a structure of type @code{struct in_addr}.  It would
939
 
be better if the usage were made consistent, but it is not hard to extract
940
 
the integer from the structure or put the integer into a structure.
941
 
 
942
 
You will find older code that uses @code{unsigned long int} for
943
 
IPv4 Internet host addresses instead of @code{uint32_t} or @code{struct
944
 
in_addr}.  Historically @code{unsigned long int} was a 32-bit number but
945
 
with 64-bit machines this has changed.  Using @code{unsigned long int}
946
 
might break the code if it is used on machines where this type doesn't
947
 
have 32 bits.  @code{uint32_t} is specified by Unix98 and guaranteed to have
948
 
32 bits.
949
 
 
950
 
IPv6 Internet host addresses have 128 bits and are packaged inside a
951
 
structure of type @code{struct in6_addr}.
952
 
 
953
 
The following basic definitions for Internet addresses are declared in
954
 
the header file @file{netinet/in.h}:
955
 
@pindex netinet/in.h
956
 
 
957
 
@comment netinet/in.h
958
 
@comment BSD
959
 
@deftp {Data Type} {struct in_addr}
960
 
This data type is used in certain contexts to contain an IPv4 Internet
961
 
host address.  It has just one field, named @code{s_addr}, which records
962
 
the host address number as an @code{uint32_t}.
963
 
@end deftp
964
 
 
965
 
@comment netinet/in.h
966
 
@comment BSD
967
 
@deftypevr Macro {uint32_t} INADDR_LOOPBACK
968
 
You can use this constant to stand for ``the address of this machine,''
969
 
instead of finding its actual address.  It is the IPv4 Internet address
970
 
@samp{127.0.0.1}, which is usually called @samp{localhost}.  This
971
 
special constant saves you the trouble of looking up the address of your
972
 
own machine.  Also, the system usually implements @code{INADDR_LOOPBACK}
973
 
specially, avoiding any network traffic for the case of one machine
974
 
talking to itself.
975
 
@end deftypevr
976
 
 
977
 
@comment netinet/in.h
978
 
@comment BSD
979
 
@deftypevr Macro {uint32_t} INADDR_ANY
980
 
You can use this constant to stand for ``any incoming address'' when
981
 
binding to an address.  @xref{Setting Address}.  This is the usual
982
 
address to give in the @code{sin_addr} member of @w{@code{struct
983
 
sockaddr_in}} when you want to accept Internet connections.
984
 
@end deftypevr
985
 
 
986
 
@comment netinet/in.h
987
 
@comment BSD
988
 
@deftypevr Macro {uint32_t} INADDR_BROADCAST
989
 
This constant is the address you use to send a broadcast message.
990
 
@c !!! broadcast needs further documented
991
 
@end deftypevr
992
 
 
993
 
@comment netinet/in.h
994
 
@comment BSD
995
 
@deftypevr Macro {uint32_t} INADDR_NONE
996
 
This constant is returned by some functions to indicate an error.
997
 
@end deftypevr
998
 
 
999
 
@comment netinet/in.h
1000
 
@comment IPv6 basic API
1001
 
@deftp {Data Type} {struct in6_addr}
1002
 
This data type is used to store an IPv6 address.  It stores 128 bits of
1003
 
data, which can be accessed (via a union) in a variety of ways.
1004
 
@end deftp
1005
 
 
1006
 
@comment netinet/in.h
1007
 
@comment IPv6 basic API
1008
 
@deftypevr Constant {struct in6_addr} in6addr_loopback
1009
 
This constant is the IPv6 address @samp{::1}, the loopback address.  See
1010
 
above for a description of what this means.  The macro
1011
 
@code{IN6ADDR_LOOPBACK_INIT} is provided to allow you to initialize your
1012
 
own variables to this value.
1013
 
@end deftypevr
1014
 
 
1015
 
@comment netinet/in.h
1016
 
@comment IPv6 basic API
1017
 
@deftypevr Constant {struct in6_addr} in6addr_any
1018
 
This constant is the IPv6 address @samp{::}, the unspecified address.  See
1019
 
above for a description of what this means.  The macro
1020
 
@code{IN6ADDR_ANY_INIT} is provided to allow you to initialize your
1021
 
own variables to this value.
1022
 
@end deftypevr
1023
 
 
1024
 
@node Host Address Functions
1025
 
@subsubsection Host Address Functions
1026
 
 
1027
 
@pindex arpa/inet.h
1028
 
@noindent
1029
 
These additional functions for manipulating Internet addresses are
1030
 
declared in the header file @file{arpa/inet.h}.  They represent Internet
1031
 
addresses in network byte order, and network numbers and
1032
 
local-address-within-network numbers in host byte order.  @xref{Byte
1033
 
Order}, for an explanation of network and host byte order.
1034
 
 
1035
 
@comment arpa/inet.h
1036
 
@comment BSD
1037
 
@deftypefun int inet_aton (const char *@var{name}, struct in_addr *@var{addr})
1038
 
This function converts the IPv4 Internet host address @var{name}
1039
 
from the standard numbers-and-dots notation into binary data and stores
1040
 
it in the @code{struct in_addr} that @var{addr} points to.
1041
 
@code{inet_aton} returns nonzero if the address is valid, zero if not.
1042
 
@end deftypefun
1043
 
 
1044
 
@comment arpa/inet.h
1045
 
@comment BSD
1046
 
@deftypefun {uint32_t} inet_addr (const char *@var{name})
1047
 
This function converts the IPv4 Internet host address @var{name} from the
1048
 
standard numbers-and-dots notation into binary data.  If the input is
1049
 
not valid, @code{inet_addr} returns @code{INADDR_NONE}.  This is an
1050
 
obsolete interface to @code{inet_aton}, described immediately above. It
1051
 
is obsolete because @code{INADDR_NONE} is a valid address
1052
 
(255.255.255.255), and @code{inet_aton} provides a cleaner way to
1053
 
indicate error return.
1054
 
@end deftypefun
1055
 
 
1056
 
@comment arpa/inet.h
1057
 
@comment BSD
1058
 
@deftypefun {uint32_t} inet_network (const char *@var{name})
1059
 
This function extracts the network number from the address @var{name},
1060
 
given in the standard numbers-and-dots notation. The returned address is
1061
 
in host order. If the input is not valid, @code{inet_network} returns
1062
 
@code{-1}.
1063
 
 
1064
 
The function works only with traditional IPv4 class A, B and C network
1065
 
types.  It doesn't work with classless addresses and shouldn't be used
1066
 
anymore.
1067
 
@end deftypefun
1068
 
 
1069
 
@comment arpa/inet.h
1070
 
@comment BSD
1071
 
@deftypefun {char *} inet_ntoa (struct in_addr @var{addr})
1072
 
This function converts the IPv4 Internet host address @var{addr} to a
1073
 
string in the standard numbers-and-dots notation.  The return value is
1074
 
a pointer into a statically-allocated buffer.  Subsequent calls will
1075
 
overwrite the same buffer, so you should copy the string if you need
1076
 
to save it.
1077
 
 
1078
 
In multi-threaded programs each thread has an own statically-allocated
1079
 
buffer.  But still subsequent calls of @code{inet_ntoa} in the same
1080
 
thread will overwrite the result of the last call.
1081
 
 
1082
 
Instead of @code{inet_ntoa} the newer function @code{inet_ntop} which is
1083
 
described below should be used since it handles both IPv4 and IPv6
1084
 
addresses.
1085
 
@end deftypefun
1086
 
 
1087
 
@comment arpa/inet.h
1088
 
@comment BSD
1089
 
@deftypefun {struct in_addr} inet_makeaddr (uint32_t @var{net}, uint32_t @var{local})
1090
 
This function makes an IPv4 Internet host address by combining the network
1091
 
number @var{net} with the local-address-within-network number
1092
 
@var{local}.
1093
 
@end deftypefun
1094
 
 
1095
 
@comment arpa/inet.h
1096
 
@comment BSD
1097
 
@deftypefun uint32_t inet_lnaof (struct in_addr @var{addr})
1098
 
This function returns the local-address-within-network part of the
1099
 
Internet host address @var{addr}.
1100
 
 
1101
 
The function works only with traditional IPv4 class A, B and C network
1102
 
types.  It doesn't work with classless addresses and shouldn't be used
1103
 
anymore.
1104
 
@end deftypefun
1105
 
 
1106
 
@comment arpa/inet.h
1107
 
@comment BSD
1108
 
@deftypefun uint32_t inet_netof (struct in_addr @var{addr})
1109
 
This function returns the network number part of the Internet host
1110
 
address @var{addr}.
1111
 
 
1112
 
The function works only with traditional IPv4 class A, B and C network
1113
 
types.  It doesn't work with classless addresses and shouldn't be used
1114
 
anymore.
1115
 
@end deftypefun
1116
 
 
1117
 
@comment arpa/inet.h
1118
 
@comment IPv6 basic API
1119
 
@deftypefun int inet_pton (int @var{af}, const char *@var{cp}, void *@var{buf})
1120
 
This function converts an Internet address (either IPv4 or IPv6) from
1121
 
presentation (textual) to network (binary) format.  @var{af} should be
1122
 
either @code{AF_INET} or @code{AF_INET6}, as appropriate for the type of
1123
 
address being converted.  @var{cp} is a pointer to the input string, and
1124
 
@var{buf} is a pointer to a buffer for the result.  It is the caller's
1125
 
responsibility to make sure the buffer is large enough.
1126
 
@end deftypefun
1127
 
 
1128
 
@comment arpa/inet.h
1129
 
@comment IPv6 basic API
1130
 
@deftypefun {const char *} inet_ntop (int @var{af}, const void *@var{cp}, char *@var{buf}, size_t @var{len})
1131
 
This function converts an Internet address (either IPv4 or IPv6) from
1132
 
network (binary) to presentation (textual) form.  @var{af} should be
1133
 
either @code{AF_INET} or @code{AF_INET6}, as appropriate.  @var{cp} is a
1134
 
pointer to the address to be converted.  @var{buf} should be a pointer
1135
 
to a buffer to hold the result, and @var{len} is the length of this
1136
 
buffer.  The return value from the function will be this buffer address.
1137
 
@end deftypefun
1138
 
 
1139
 
@node Host Names
1140
 
@subsubsection Host Names
1141
 
@cindex hosts database
1142
 
@cindex converting host name to address
1143
 
@cindex converting host address to name
1144
 
 
1145
 
Besides the standard numbers-and-dots notation for Internet addresses,
1146
 
you can also refer to a host by a symbolic name.  The advantage of a
1147
 
symbolic name is that it is usually easier to remember.  For example,
1148
 
the machine with Internet address @samp{158.121.106.19} is also known as
1149
 
@samp{alpha.gnu.org}; and other machines in the @samp{gnu.org}
1150
 
domain can refer to it simply as @samp{alpha}.
1151
 
 
1152
 
@pindex /etc/hosts
1153
 
@pindex netdb.h
1154
 
Internally, the system uses a database to keep track of the mapping
1155
 
between host names and host numbers.  This database is usually either
1156
 
the file @file{/etc/hosts} or an equivalent provided by a name server.
1157
 
The functions and other symbols for accessing this database are declared
1158
 
in @file{netdb.h}.  They are BSD features, defined unconditionally if
1159
 
you include @file{netdb.h}.
1160
 
 
1161
 
@comment netdb.h
1162
 
@comment BSD
1163
 
@deftp {Data Type} {struct hostent}
1164
 
This data type is used to represent an entry in the hosts database.  It
1165
 
has the following members:
1166
 
 
1167
 
@table @code
1168
 
@item char *h_name
1169
 
This is the ``official'' name of the host.
1170
 
 
1171
 
@item char **h_aliases
1172
 
These are alternative names for the host, represented as a null-terminated
1173
 
vector of strings.
1174
 
 
1175
 
@item int h_addrtype
1176
 
This is the host address type; in practice, its value is always either
1177
 
@code{AF_INET} or @code{AF_INET6}, with the latter being used for IPv6
1178
 
hosts.  In principle other kinds of addresses could be represented in
1179
 
the database as well as Internet addresses; if this were done, you
1180
 
might find a value in this field other than @code{AF_INET} or
1181
 
@code{AF_INET6}.  @xref{Socket Addresses}.
1182
 
 
1183
 
@item int h_length
1184
 
This is the length, in bytes, of each address.
1185
 
 
1186
 
@item char **h_addr_list
1187
 
This is the vector of addresses for the host.  (Recall that the host
1188
 
might be connected to multiple networks and have different addresses on
1189
 
each one.)  The vector is terminated by a null pointer.
1190
 
 
1191
 
@item char *h_addr
1192
 
This is a synonym for @code{h_addr_list[0]}; in other words, it is the
1193
 
first host address.
1194
 
@end table
1195
 
@end deftp
1196
 
 
1197
 
As far as the host database is concerned, each address is just a block
1198
 
of memory @code{h_length} bytes long.  But in other contexts there is an
1199
 
implicit assumption that you can convert IPv4 addresses to a
1200
 
@code{struct in_addr} or an @code{uint32_t}.  Host addresses in
1201
 
a @code{struct hostent} structure are always given in network byte
1202
 
order; see @ref{Byte Order}.
1203
 
 
1204
 
You can use @code{gethostbyname}, @code{gethostbyname2} or
1205
 
@code{gethostbyaddr} to search the hosts database for information about
1206
 
a particular host.  The information is returned in a
1207
 
statically-allocated structure; you must copy the information if you
1208
 
need to save it across calls.  You can also use @code{getaddrinfo} and
1209
 
@code{getnameinfo} to obtain this information.
1210
 
 
1211
 
@comment netdb.h
1212
 
@comment BSD
1213
 
@deftypefun {struct hostent *} gethostbyname (const char *@var{name})
1214
 
The @code{gethostbyname} function returns information about the host
1215
 
named @var{name}.  If the lookup fails, it returns a null pointer.
1216
 
@end deftypefun
1217
 
 
1218
 
@comment netdb.h
1219
 
@comment IPv6 Basic API
1220
 
@deftypefun {struct hostent *} gethostbyname2 (const char *@var{name}, int @var{af})
1221
 
The @code{gethostbyname2} function is like @code{gethostbyname}, but
1222
 
allows the caller to specify the desired address family (e.g.@:
1223
 
@code{AF_INET} or @code{AF_INET6}) of the result.
1224
 
@end deftypefun
1225
 
 
1226
 
@comment netdb.h
1227
 
@comment BSD
1228
 
@deftypefun {struct hostent *} gethostbyaddr (const char *@var{addr}, size_t @var{length}, int @var{format})
1229
 
The @code{gethostbyaddr} function returns information about the host
1230
 
with Internet address @var{addr}.  The parameter @var{addr} is not
1231
 
really a pointer to char - it can be a pointer to an IPv4 or an IPv6
1232
 
address. The @var{length} argument is the size (in bytes) of the address
1233
 
at @var{addr}.  @var{format} specifies the address format; for an IPv4
1234
 
Internet address, specify a value of @code{AF_INET}; for an IPv6
1235
 
Internet address, use @code{AF_INET6}.
1236
 
 
1237
 
If the lookup fails, @code{gethostbyaddr} returns a null pointer.
1238
 
@end deftypefun
1239
 
 
1240
 
@vindex h_errno
1241
 
If the name lookup by @code{gethostbyname} or @code{gethostbyaddr}
1242
 
fails, you can find out the reason by looking at the value of the
1243
 
variable @code{h_errno}.  (It would be cleaner design for these
1244
 
functions to set @code{errno}, but use of @code{h_errno} is compatible
1245
 
with other systems.)
1246
 
 
1247
 
Here are the error codes that you may find in @code{h_errno}:
1248
 
 
1249
 
@table @code
1250
 
@comment netdb.h
1251
 
@comment BSD
1252
 
@item HOST_NOT_FOUND
1253
 
@vindex HOST_NOT_FOUND
1254
 
No such host is known in the database.
1255
 
 
1256
 
@comment netdb.h
1257
 
@comment BSD
1258
 
@item TRY_AGAIN
1259
 
@vindex TRY_AGAIN
1260
 
This condition happens when the name server could not be contacted.  If
1261
 
you try again later, you may succeed then.
1262
 
 
1263
 
@comment netdb.h
1264
 
@comment BSD
1265
 
@item NO_RECOVERY
1266
 
@vindex NO_RECOVERY
1267
 
A non-recoverable error occurred.
1268
 
 
1269
 
@comment netdb.h
1270
 
@comment BSD
1271
 
@item NO_ADDRESS
1272
 
@vindex NO_ADDRESS
1273
 
The host database contains an entry for the name, but it doesn't have an
1274
 
associated Internet address.
1275
 
@end table
1276
 
 
1277
 
The lookup functions above all have one in common: they are not
1278
 
reentrant and therefore unusable in multi-threaded applications.
1279
 
Therefore provides the GNU C library a new set of functions which can be
1280
 
used in this context.
1281
 
 
1282
 
@comment netdb.h
1283
 
@comment GNU
1284
 
@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})
1285
 
The @code{gethostbyname_r} function returns information about the host
1286
 
named @var{name}.  The caller must pass a pointer to an object of type
1287
 
@code{struct hostent} in the @var{result_buf} parameter.  In addition
1288
 
the function may need extra buffer space and the caller must pass an
1289
 
pointer and the size of the buffer in the @var{buf} and @var{buflen}
1290
 
parameters.
1291
 
 
1292
 
A pointer to the buffer, in which the result is stored, is available in
1293
 
@code{*@var{result}} after the function call successfully returned.  If
1294
 
an error occurs or if no entry is found, the pointer @code{*@var{result}}
1295
 
is a null pointer.  Success is signalled by a zero return value.  If the
1296
 
function failed the return value is an error number.  In addition to the
1297
 
errors defined for @code{gethostbyname} it can also be @code{ERANGE}.
1298
 
In this case the call should be repeated with a larger buffer.
1299
 
Additional error information is not stored in the global variable
1300
 
@code{h_errno} but instead in the object pointed to by @var{h_errnop}.
1301
 
 
1302
 
Here's a small example:
1303
 
@smallexample
1304
 
struct hostent *
1305
 
gethostname (char *host)
1306
 
@{
1307
 
  struct hostent hostbuf, *hp;
1308
 
  size_t hstbuflen;
1309
 
  char *tmphstbuf;
1310
 
  int res;
1311
 
  int herr;
1312
 
 
1313
 
  hstbuflen = 1024;
1314
 
  /* Allocate buffer, remember to free it to avoid memory leakage.  */
1315
 
  tmphstbuf = malloc (hstbuflen);
1316
 
 
1317
 
  while ((res = gethostbyname_r (host, &hostbuf, tmphstbuf, hstbuflen,
1318
 
                                 &hp, &herr)) == ERANGE)
1319
 
    @{
1320
 
      /* Enlarge the buffer.  */
1321
 
      hstbuflen *= 2;
1322
 
      tmphstbuf = realloc (tmphstbuf, hstbuflen);
1323
 
    @}
1324
 
  /*  Check for errors.  */
1325
 
  if (res || hp == NULL)
1326
 
    return NULL;
1327
 
  return hp;
1328
 
@}
1329
 
@end smallexample
1330
 
@end deftypefun
1331
 
 
1332
 
@comment netdb.h
1333
 
@comment GNU
1334
 
@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})
1335
 
The @code{gethostbyname2_r} function is like @code{gethostbyname_r}, but
1336
 
allows the caller to specify the desired address family (e.g.@:
1337
 
@code{AF_INET} or @code{AF_INET6}) for the result.
1338
 
@end deftypefun
1339
 
 
1340
 
@comment netdb.h
1341
 
@comment GNU
1342
 
@deftypefun int gethostbyaddr_r (const char *@var{addr}, size_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})
1343
 
The @code{gethostbyaddr_r} function returns information about the host
1344
 
with Internet address @var{addr}.  The parameter @var{addr} is not
1345
 
really a pointer to char - it can be a pointer to an IPv4 or an IPv6
1346
 
address. The @var{length} argument is the size (in bytes) of the address
1347
 
at @var{addr}.  @var{format} specifies the address format; for an IPv4
1348
 
Internet address, specify a value of @code{AF_INET}; for an IPv6
1349
 
Internet address, use @code{AF_INET6}.
1350
 
 
1351
 
Similar to the @code{gethostbyname_r} function, the caller must provide
1352
 
buffers for the result and memory used internally.  In case of success
1353
 
the function returns zero.  Otherwise the value is an error number where
1354
 
@code{ERANGE} has the special meaning that the caller-provided buffer is
1355
 
too small.
1356
 
@end deftypefun
1357
 
 
1358
 
You can also scan the entire hosts database one entry at a time using
1359
 
@code{sethostent}, @code{gethostent} and @code{endhostent}.  Be careful
1360
 
when using these functions because they are not reentrant.
1361
 
 
1362
 
@comment netdb.h
1363
 
@comment BSD
1364
 
@deftypefun void sethostent (int @var{stayopen})
1365
 
This function opens the hosts database to begin scanning it.  You can
1366
 
then call @code{gethostent} to read the entries.
1367
 
 
1368
 
@c There was a rumor that this flag has different meaning if using the DNS,
1369
 
@c but it appears this description is accurate in that case also.
1370
 
If the @var{stayopen} argument is nonzero, this sets a flag so that
1371
 
subsequent calls to @code{gethostbyname} or @code{gethostbyaddr} will
1372
 
not close the database (as they usually would).  This makes for more
1373
 
efficiency if you call those functions several times, by avoiding
1374
 
reopening the database for each call.
1375
 
@end deftypefun
1376
 
 
1377
 
@comment netdb.h
1378
 
@comment BSD
1379
 
@deftypefun {struct hostent *} gethostent (void)
1380
 
This function returns the next entry in the hosts database.  It
1381
 
returns a null pointer if there are no more entries.
1382
 
@end deftypefun
1383
 
 
1384
 
@comment netdb.h
1385
 
@comment BSD
1386
 
@deftypefun void endhostent (void)
1387
 
This function closes the hosts database.
1388
 
@end deftypefun
1389
 
 
1390
 
@node Ports
1391
 
@subsection Internet Ports
1392
 
@cindex port number
1393
 
 
1394
 
A socket address in the Internet namespace consists of a machine's
1395
 
Internet address plus a @dfn{port number} which distinguishes the
1396
 
sockets on a given machine (for a given protocol).  Port numbers range
1397
 
from 0 to 65,535.
1398
 
 
1399
 
Port numbers less than @code{IPPORT_RESERVED} are reserved for standard
1400
 
servers, such as @code{finger} and @code{telnet}.  There is a database
1401
 
that keeps track of these, and you can use the @code{getservbyname}
1402
 
function to map a service name onto a port number; see @ref{Services
1403
 
Database}.
1404
 
 
1405
 
If you write a server that is not one of the standard ones defined in
1406
 
the database, you must choose a port number for it.  Use a number
1407
 
greater than @code{IPPORT_USERRESERVED}; such numbers are reserved for
1408
 
servers and won't ever be generated automatically by the system.
1409
 
Avoiding conflicts with servers being run by other users is up to you.
1410
 
 
1411
 
When you use a socket without specifying its address, the system
1412
 
generates a port number for it.  This number is between
1413
 
@code{IPPORT_RESERVED} and @code{IPPORT_USERRESERVED}.
1414
 
 
1415
 
On the Internet, it is actually legitimate to have two different
1416
 
sockets with the same port number, as long as they never both try to
1417
 
communicate with the same socket address (host address plus port
1418
 
number).  You shouldn't duplicate a port number except in special
1419
 
circumstances where a higher-level protocol requires it.  Normally,
1420
 
the system won't let you do it; @code{bind} normally insists on
1421
 
distinct port numbers.  To reuse a port number, you must set the
1422
 
socket option @code{SO_REUSEADDR}.  @xref{Socket-Level Options}.
1423
 
 
1424
 
@pindex netinet/in.h
1425
 
These macros are defined in the header file @file{netinet/in.h}.
1426
 
 
1427
 
@comment netinet/in.h
1428
 
@comment BSD
1429
 
@deftypevr Macro int IPPORT_RESERVED
1430
 
Port numbers less than @code{IPPORT_RESERVED} are reserved for
1431
 
superuser use.
1432
 
@end deftypevr
1433
 
 
1434
 
@comment netinet/in.h
1435
 
@comment BSD
1436
 
@deftypevr Macro int IPPORT_USERRESERVED
1437
 
Port numbers greater than or equal to @code{IPPORT_USERRESERVED} are
1438
 
reserved for explicit use; they will never be allocated automatically.
1439
 
@end deftypevr
1440
 
 
1441
 
@node Services Database
1442
 
@subsection The Services Database
1443
 
@cindex services database
1444
 
@cindex converting service name to port number
1445
 
@cindex converting port number to service name
1446
 
 
1447
 
@pindex /etc/services
1448
 
The database that keeps track of ``well-known'' services is usually
1449
 
either the file @file{/etc/services} or an equivalent from a name server.
1450
 
You can use these utilities, declared in @file{netdb.h}, to access
1451
 
the services database.
1452
 
@pindex netdb.h
1453
 
 
1454
 
@comment netdb.h
1455
 
@comment BSD
1456
 
@deftp {Data Type} {struct servent}
1457
 
This data type holds information about entries from the services database.
1458
 
It has the following members:
1459
 
 
1460
 
@table @code
1461
 
@item char *s_name
1462
 
This is the ``official'' name of the service.
1463
 
 
1464
 
@item char **s_aliases
1465
 
These are alternate names for the service, represented as an array of
1466
 
strings.  A null pointer terminates the array.
1467
 
 
1468
 
@item int s_port
1469
 
This is the port number for the service.  Port numbers are given in
1470
 
network byte order; see @ref{Byte Order}.
1471
 
 
1472
 
@item char *s_proto
1473
 
This is the name of the protocol to use with this service.
1474
 
@xref{Protocols Database}.
1475
 
@end table
1476
 
@end deftp
1477
 
 
1478
 
To get information about a particular service, use the
1479
 
@code{getservbyname} or @code{getservbyport} functions.  The information
1480
 
is returned in a statically-allocated structure; you must copy the
1481
 
information if you need to save it across calls.
1482
 
 
1483
 
@comment netdb.h
1484
 
@comment BSD
1485
 
@deftypefun {struct servent *} getservbyname (const char *@var{name}, const char *@var{proto})
1486
 
The @code{getservbyname} function returns information about the
1487
 
service named @var{name} using protocol @var{proto}.  If it can't find
1488
 
such a service, it returns a null pointer.
1489
 
 
1490
 
This function is useful for servers as well as for clients; servers
1491
 
use it to determine which port they should listen on (@pxref{Listening}).
1492
 
@end deftypefun
1493
 
 
1494
 
@comment netdb.h
1495
 
@comment BSD
1496
 
@deftypefun {struct servent *} getservbyport (int @var{port}, const char *@var{proto})
1497
 
The @code{getservbyport} function returns information about the
1498
 
service at port @var{port} using protocol @var{proto}.  If it can't
1499
 
find such a service, it returns a null pointer.
1500
 
@end deftypefun
1501
 
 
1502
 
@noindent
1503
 
You can also scan the services database using @code{setservent},
1504
 
@code{getservent} and @code{endservent}.  Be careful when using these
1505
 
functions because they are not reentrant.
1506
 
 
1507
 
@comment netdb.h
1508
 
@comment BSD
1509
 
@deftypefun void setservent (int @var{stayopen})
1510
 
This function opens the services database to begin scanning it.
1511
 
 
1512
 
If the @var{stayopen} argument is nonzero, this sets a flag so that
1513
 
subsequent calls to @code{getservbyname} or @code{getservbyport} will
1514
 
not close the database (as they usually would).  This makes for more
1515
 
efficiency if you call those functions several times, by avoiding
1516
 
reopening the database for each call.
1517
 
@end deftypefun
1518
 
 
1519
 
@comment netdb.h
1520
 
@comment BSD
1521
 
@deftypefun {struct servent *} getservent (void)
1522
 
This function returns the next entry in the services database.  If
1523
 
there are no more entries, it returns a null pointer.
1524
 
@end deftypefun
1525
 
 
1526
 
@comment netdb.h
1527
 
@comment BSD
1528
 
@deftypefun void endservent (void)
1529
 
This function closes the services database.
1530
 
@end deftypefun
1531
 
 
1532
 
@node Byte Order
1533
 
@subsection Byte Order Conversion
1534
 
@cindex byte order conversion, for socket
1535
 
@cindex converting byte order
1536
 
 
1537
 
@cindex big-endian
1538
 
@cindex little-endian
1539
 
Different kinds of computers use different conventions for the
1540
 
ordering of bytes within a word.  Some computers put the most
1541
 
significant byte within a word first (this is called ``big-endian''
1542
 
order), and others put it last (``little-endian'' order).
1543
 
 
1544
 
@cindex network byte order
1545
 
So that machines with different byte order conventions can
1546
 
communicate, the Internet protocols specify a canonical byte order
1547
 
convention for data transmitted over the network.  This is known
1548
 
as @dfn{network byte order}.
1549
 
 
1550
 
When establishing an Internet socket connection, you must make sure that
1551
 
the data in the @code{sin_port} and @code{sin_addr} members of the
1552
 
@code{sockaddr_in} structure are represented in network byte order.
1553
 
If you are encoding integer data in the messages sent through the
1554
 
socket, you should convert this to network byte order too.  If you don't
1555
 
do this, your program may fail when running on or talking to other kinds
1556
 
of machines.
1557
 
 
1558
 
If you use @code{getservbyname} and @code{gethostbyname} or
1559
 
@code{inet_addr} to get the port number and host address, the values are
1560
 
already in network byte order, and you can copy them directly into
1561
 
the @code{sockaddr_in} structure.
1562
 
 
1563
 
Otherwise, you have to convert the values explicitly.  Use @code{htons}
1564
 
and @code{ntohs} to convert values for the @code{sin_port} member.  Use
1565
 
@code{htonl} and @code{ntohl} to convert IPv4 addresses for the
1566
 
@code{sin_addr} member.  (Remember, @code{struct in_addr} is equivalent
1567
 
to @code{uint32_t}.)  These functions are declared in
1568
 
@file{netinet/in.h}.
1569
 
@pindex netinet/in.h
1570
 
 
1571
 
@comment netinet/in.h
1572
 
@comment BSD
1573
 
@deftypefun {uint16_t} htons (uint16_t @var{hostshort})
1574
 
This function converts the @code{uint16_t} integer @var{hostshort} from
1575
 
host byte order to network byte order.
1576
 
@end deftypefun
1577
 
 
1578
 
@comment netinet/in.h
1579
 
@comment BSD
1580
 
@deftypefun {uint16_t} ntohs (uint16_t @var{netshort})
1581
 
This function converts the @code{uint16_t} integer @var{netshort} from
1582
 
network byte order to host byte order.
1583
 
@end deftypefun
1584
 
 
1585
 
@comment netinet/in.h
1586
 
@comment BSD
1587
 
@deftypefun {uint32_t} htonl (uint32_t @var{hostlong})
1588
 
This function converts the @code{uint32_t} integer @var{hostlong} from
1589
 
host byte order to network byte order.
1590
 
 
1591
 
This is used for IPv4 Internet addresses.
1592
 
@end deftypefun
1593
 
 
1594
 
@comment netinet/in.h
1595
 
@comment BSD
1596
 
@deftypefun {uint32_t} ntohl (uint32_t @var{netlong})
1597
 
This function converts the @code{uint32_t} integer @var{netlong} from
1598
 
network byte order to host byte order.
1599
 
 
1600
 
This is used for IPv4 Internet addresses.
1601
 
@end deftypefun
1602
 
 
1603
 
@node Protocols Database
1604
 
@subsection Protocols Database
1605
 
@cindex protocols database
1606
 
 
1607
 
The communications protocol used with a socket controls low-level
1608
 
details of how data are exchanged.  For example, the protocol implements
1609
 
things like checksums to detect errors in transmissions, and routing
1610
 
instructions for messages.  Normal user programs have little reason to
1611
 
mess with these details directly.
1612
 
 
1613
 
@cindex TCP (Internet protocol)
1614
 
The default communications protocol for the Internet namespace depends on
1615
 
the communication style.  For stream communication, the default is TCP
1616
 
(``transmission control protocol'').  For datagram communication, the
1617
 
default is UDP (``user datagram protocol'').  For reliable datagram
1618
 
communication, the default is RDP (``reliable datagram protocol'').
1619
 
You should nearly always use the default.
1620
 
 
1621
 
@pindex /etc/protocols
1622
 
Internet protocols are generally specified by a name instead of a
1623
 
number.  The network protocols that a host knows about are stored in a
1624
 
database.  This is usually either derived from the file
1625
 
@file{/etc/protocols}, or it may be an equivalent provided by a name
1626
 
server.  You look up the protocol number associated with a named
1627
 
protocol in the database using the @code{getprotobyname} function.
1628
 
 
1629
 
Here are detailed descriptions of the utilities for accessing the
1630
 
protocols database.  These are declared in @file{netdb.h}.
1631
 
@pindex netdb.h
1632
 
 
1633
 
@comment netdb.h
1634
 
@comment BSD
1635
 
@deftp {Data Type} {struct protoent}
1636
 
This data type is used to represent entries in the network protocols
1637
 
database.  It has the following members:
1638
 
 
1639
 
@table @code
1640
 
@item char *p_name
1641
 
This is the official name of the protocol.
1642
 
 
1643
 
@item char **p_aliases
1644
 
These are alternate names for the protocol, specified as an array of
1645
 
strings.  The last element of the array is a null pointer.
1646
 
 
1647
 
@item int p_proto
1648
 
This is the protocol number (in host byte order); use this member as the
1649
 
@var{protocol} argument to @code{socket}.
1650
 
@end table
1651
 
@end deftp
1652
 
 
1653
 
You can use @code{getprotobyname} and @code{getprotobynumber} to search
1654
 
the protocols database for a specific protocol.  The information is
1655
 
returned in a statically-allocated structure; you must copy the
1656
 
information if you need to save it across calls.
1657
 
 
1658
 
@comment netdb.h
1659
 
@comment BSD
1660
 
@deftypefun {struct protoent *} getprotobyname (const char *@var{name})
1661
 
The @code{getprotobyname} function returns information about the
1662
 
network protocol named @var{name}.  If there is no such protocol, it
1663
 
returns a null pointer.
1664
 
@end deftypefun
1665
 
 
1666
 
@comment netdb.h
1667
 
@comment BSD
1668
 
@deftypefun {struct protoent *} getprotobynumber (int @var{protocol})
1669
 
The @code{getprotobynumber} function returns information about the
1670
 
network protocol with number @var{protocol}.  If there is no such
1671
 
protocol, it returns a null pointer.
1672
 
@end deftypefun
1673
 
 
1674
 
You can also scan the whole protocols database one protocol at a time by
1675
 
using @code{setprotoent}, @code{getprotoent} and @code{endprotoent}.
1676
 
Be careful when using these functions because they are not reentrant.
1677
 
 
1678
 
@comment netdb.h
1679
 
@comment BSD
1680
 
@deftypefun void setprotoent (int @var{stayopen})
1681
 
This function opens the protocols database to begin scanning it.
1682
 
 
1683
 
If the @var{stayopen} argument is nonzero, this sets a flag so that
1684
 
subsequent calls to @code{getprotobyname} or @code{getprotobynumber} will
1685
 
not close the database (as they usually would).  This makes for more
1686
 
efficiency if you call those functions several times, by avoiding
1687
 
reopening the database for each call.
1688
 
@end deftypefun
1689
 
 
1690
 
@comment netdb.h
1691
 
@comment BSD
1692
 
@deftypefun {struct protoent *} getprotoent (void)
1693
 
This function returns the next entry in the protocols database.  It
1694
 
returns a null pointer if there are no more entries.
1695
 
@end deftypefun
1696
 
 
1697
 
@comment netdb.h
1698
 
@comment BSD
1699
 
@deftypefun void endprotoent (void)
1700
 
This function closes the protocols database.
1701
 
@end deftypefun
1702
 
 
1703
 
@node Inet Example
1704
 
@subsection Internet Socket Example
1705
 
 
1706
 
Here is an example showing how to create and name a socket in the
1707
 
Internet namespace.  The newly created socket exists on the machine that
1708
 
the program is running on.  Rather than finding and using the machine's
1709
 
Internet address, this example specifies @code{INADDR_ANY} as the host
1710
 
address; the system replaces that with the machine's actual address.
1711
 
 
1712
 
@smallexample
1713
 
@include mkisock.c.texi
1714
 
@end smallexample
1715
 
 
1716
 
Here is another example, showing how you can fill in a @code{sockaddr_in}
1717
 
structure, given a host name string and a port number:
1718
 
 
1719
 
@smallexample
1720
 
@include isockad.c.texi
1721
 
@end smallexample
1722
 
 
1723
 
@node Misc Namespaces
1724
 
@section Other Namespaces
1725
 
 
1726
 
@vindex PF_NS
1727
 
@vindex PF_ISO
1728
 
@vindex PF_CCITT
1729
 
@vindex PF_IMPLINK
1730
 
@vindex PF_ROUTE
1731
 
Certain other namespaces and associated protocol families are supported
1732
 
but not documented yet because they are not often used.  @code{PF_NS}
1733
 
refers to the Xerox Network Software protocols.  @code{PF_ISO} stands
1734
 
for Open Systems Interconnect.  @code{PF_CCITT} refers to protocols from
1735
 
CCITT.  @file{socket.h} defines these symbols and others naming protocols
1736
 
not actually implemented.
1737
 
 
1738
 
@code{PF_IMPLINK} is used for communicating between hosts and Internet
1739
 
Message Processors.  For information on this and @code{PF_ROUTE}, an
1740
 
occasionally-used local area routing protocol, see the GNU Hurd Manual
1741
 
(to appear in the future).
1742
 
 
1743
 
@node Open/Close Sockets
1744
 
@section Opening and Closing Sockets
1745
 
 
1746
 
This section describes the actual library functions for opening and
1747
 
closing sockets.  The same functions work for all namespaces and
1748
 
connection styles.
1749
 
 
1750
 
@menu
1751
 
* Creating a Socket::           How to open a socket.
1752
 
* Closing a Socket::            How to close a socket.
1753
 
* Socket Pairs::                These are created like pipes.
1754
 
@end menu
1755
 
 
1756
 
@node Creating a Socket
1757
 
@subsection Creating a Socket
1758
 
@cindex creating a socket
1759
 
@cindex socket, creating
1760
 
@cindex opening a socket
1761
 
 
1762
 
The primitive for creating a socket is the @code{socket} function,
1763
 
declared in @file{sys/socket.h}.
1764
 
@pindex sys/socket.h
1765
 
 
1766
 
@comment sys/socket.h
1767
 
@comment BSD
1768
 
@deftypefun int socket (int @var{namespace}, int @var{style}, int @var{protocol})
1769
 
This function creates a socket and specifies communication style
1770
 
@var{style}, which should be one of the socket styles listed in
1771
 
@ref{Communication Styles}.  The @var{namespace} argument specifies
1772
 
the namespace; it must be @code{PF_LOCAL} (@pxref{Local Namespace}) or
1773
 
@code{PF_INET} (@pxref{Internet Namespace}).  @var{protocol}
1774
 
designates the specific protocol (@pxref{Socket Concepts}); zero is
1775
 
usually right for @var{protocol}.
1776
 
 
1777
 
The return value from @code{socket} is the file descriptor for the new
1778
 
socket, or @code{-1} in case of error.  The following @code{errno} error
1779
 
conditions are defined for this function:
1780
 
 
1781
 
@table @code
1782
 
@item EPROTONOSUPPORT
1783
 
The @var{protocol} or @var{style} is not supported by the
1784
 
@var{namespace} specified.
1785
 
 
1786
 
@item EMFILE
1787
 
The process already has too many file descriptors open.
1788
 
 
1789
 
@item ENFILE
1790
 
The system already has too many file descriptors open.
1791
 
 
1792
 
@item EACCES
1793
 
The process does not have the privilege to create a socket of the specified
1794
 
@var{style} or @var{protocol}.
1795
 
 
1796
 
@item ENOBUFS
1797
 
The system ran out of internal buffer space.
1798
 
@end table
1799
 
 
1800
 
The file descriptor returned by the @code{socket} function supports both
1801
 
read and write operations.  However, like pipes, sockets do not support file
1802
 
positioning operations.
1803
 
@end deftypefun
1804
 
 
1805
 
For examples of how to call the @code{socket} function,
1806
 
see @ref{Local Socket Example}, or @ref{Inet Example}.
1807
 
 
1808
 
 
1809
 
@node Closing a Socket
1810
 
@subsection Closing a Socket
1811
 
@cindex socket, closing
1812
 
@cindex closing a socket
1813
 
@cindex shutting down a socket
1814
 
@cindex socket shutdown
1815
 
 
1816
 
When you have finished using a socket, you can simply close its
1817
 
file descriptor with @code{close}; see @ref{Opening and Closing Files}.
1818
 
If there is still data waiting to be transmitted over the connection,
1819
 
normally @code{close} tries to complete this transmission.  You
1820
 
can control this behavior using the @code{SO_LINGER} socket option to
1821
 
specify a timeout period; see @ref{Socket Options}.
1822
 
 
1823
 
@pindex sys/socket.h
1824
 
You can also shut down only reception or transmission on a
1825
 
connection by calling @code{shutdown}, which is declared in
1826
 
@file{sys/socket.h}.
1827
 
 
1828
 
@comment sys/socket.h
1829
 
@comment BSD
1830
 
@deftypefun int shutdown (int @var{socket}, int @var{how})
1831
 
The @code{shutdown} function shuts down the connection of socket
1832
 
@var{socket}.  The argument @var{how} specifies what action to
1833
 
perform:
1834
 
 
1835
 
@table @code
1836
 
@item 0
1837
 
Stop receiving data for this socket.  If further data arrives,
1838
 
reject it.
1839
 
 
1840
 
@item 1
1841
 
Stop trying to transmit data from this socket.  Discard any data
1842
 
waiting to be sent.  Stop looking for acknowledgement of data already
1843
 
sent; don't retransmit it if it is lost.
1844
 
 
1845
 
@item 2
1846
 
Stop both reception and transmission.
1847
 
@end table
1848
 
 
1849
 
The return value is @code{0} on success and @code{-1} on failure.  The
1850
 
following @code{errno} error conditions are defined for this function:
1851
 
 
1852
 
@table @code
1853
 
@item EBADF
1854
 
@var{socket} is not a valid file descriptor.
1855
 
 
1856
 
@item ENOTSOCK
1857
 
@var{socket} is not a socket.
1858
 
 
1859
 
@item ENOTCONN
1860
 
@var{socket} is not connected.
1861
 
@end table
1862
 
@end deftypefun
1863
 
 
1864
 
@node Socket Pairs
1865
 
@subsection Socket Pairs
1866
 
@cindex creating a socket pair
1867
 
@cindex socket pair
1868
 
@cindex opening a socket pair
1869
 
 
1870
 
@pindex sys/socket.h
1871
 
A @dfn{socket pair} consists of a pair of connected (but unnamed)
1872
 
sockets.  It is very similar to a pipe and is used in much the same
1873
 
way.  Socket pairs are created with the @code{socketpair} function,
1874
 
declared in @file{sys/socket.h}.  A socket pair is much like a pipe; the
1875
 
main difference is that the socket pair is bidirectional, whereas the
1876
 
pipe has one input-only end and one output-only end (@pxref{Pipes and
1877
 
FIFOs}).
1878
 
 
1879
 
@comment sys/socket.h
1880
 
@comment BSD
1881
 
@deftypefun int socketpair (int @var{namespace}, int @var{style}, int @var{protocol}, int @var{filedes}@t{[2]})
1882
 
This function creates a socket pair, returning the file descriptors in
1883
 
@code{@var{filedes}[0]} and @code{@var{filedes}[1]}.  The socket pair
1884
 
is a full-duplex communications channel, so that both reading and writing
1885
 
may be performed at either end.
1886
 
 
1887
 
The @var{namespace}, @var{style} and @var{protocol} arguments are
1888
 
interpreted as for the @code{socket} function.  @var{style} should be
1889
 
one of the communication styles listed in @ref{Communication Styles}.
1890
 
The @var{namespace} argument specifies the namespace, which must be
1891
 
@code{AF_LOCAL} (@pxref{Local Namespace}); @var{protocol} specifies the
1892
 
communications protocol, but zero is the only meaningful value.
1893
 
 
1894
 
If @var{style} specifies a connectionless communication style, then
1895
 
the two sockets you get are not @emph{connected}, strictly speaking,
1896
 
but each of them knows the other as the default destination address,
1897
 
so they can send packets to each other.
1898
 
 
1899
 
The @code{socketpair} function returns @code{0} on success and @code{-1}
1900
 
on failure.  The following @code{errno} error conditions are defined
1901
 
for this function:
1902
 
 
1903
 
@table @code
1904
 
@item EMFILE
1905
 
The process has too many file descriptors open.
1906
 
 
1907
 
@item EAFNOSUPPORT
1908
 
The specified namespace is not supported.
1909
 
 
1910
 
@item EPROTONOSUPPORT
1911
 
The specified protocol is not supported.
1912
 
 
1913
 
@item EOPNOTSUPP
1914
 
The specified protocol does not support the creation of socket pairs.
1915
 
@end table
1916
 
@end deftypefun
1917
 
 
1918
 
@node Connections
1919
 
@section Using Sockets with Connections
1920
 
 
1921
 
@cindex connection
1922
 
@cindex client
1923
 
@cindex server
1924
 
The most common communication styles involve making a connection to a
1925
 
particular other socket, and then exchanging data with that socket
1926
 
over and over.  Making a connection is asymmetric; one side (the
1927
 
@dfn{client}) acts to request a connection, while the other side (the
1928
 
@dfn{server}) makes a socket and waits for the connection request.
1929
 
 
1930
 
@iftex
1931
 
@itemize @bullet
1932
 
@item
1933
 
@ref{Connecting}, describes what the client program must do to
1934
 
initiate a connection with a server.
1935
 
 
1936
 
@item
1937
 
@ref{Listening} and @ref{Accepting Connections} describe what the
1938
 
server program must do to wait for and act upon connection requests
1939
 
from clients.
1940
 
 
1941
 
@item
1942
 
@ref{Transferring Data}, describes how data are transferred through the
1943
 
connected socket.
1944
 
@end itemize
1945
 
@end iftex
1946
 
 
1947
 
@menu
1948
 
* Connecting::               What the client program must do.
1949
 
* Listening::                How a server program waits for requests.
1950
 
* Accepting Connections::    What the server does when it gets a request.
1951
 
* Who is Connected::         Getting the address of the
1952
 
                                other side of a connection.
1953
 
* Transferring Data::        How to send and receive data.
1954
 
* Byte Stream Example::      An example program: a client for communicating
1955
 
                              over a byte stream socket in the Internet namespace.
1956
 
* Server Example::           A corresponding server program.
1957
 
* Out-of-Band Data::         This is an advanced feature.
1958
 
@end menu
1959
 
 
1960
 
@node Connecting
1961
 
@subsection Making a Connection
1962
 
@cindex connecting a socket
1963
 
@cindex socket, connecting
1964
 
@cindex socket, initiating a connection
1965
 
@cindex socket, client actions
1966
 
 
1967
 
In making a connection, the client makes a connection while the server
1968
 
waits for and accepts the connection.  Here we discuss what the client
1969
 
program must do with the @code{connect} function, which is declared in
1970
 
@file{sys/socket.h}.
1971
 
 
1972
 
@comment sys/socket.h
1973
 
@comment BSD
1974
 
@deftypefun int connect (int @var{socket}, struct sockaddr *@var{addr}, socklen_t @var{length})
1975
 
The @code{connect} function initiates a connection from the socket
1976
 
with file descriptor @var{socket} to the socket whose address is
1977
 
specified by the @var{addr} and @var{length} arguments.  (This socket
1978
 
is typically on another machine, and it must be already set up as a
1979
 
server.)  @xref{Socket Addresses}, for information about how these
1980
 
arguments are interpreted.
1981
 
 
1982
 
Normally, @code{connect} waits until the server responds to the request
1983
 
before it returns.  You can set nonblocking mode on the socket
1984
 
@var{socket} to make @code{connect} return immediately without waiting
1985
 
for the response.  @xref{File Status Flags}, for information about
1986
 
nonblocking mode.
1987
 
@c !!! how do you tell when it has finished connecting?  I suspect the
1988
 
@c way you do it is select for writing.
1989
 
 
1990
 
The normal return value from @code{connect} is @code{0}.  If an error
1991
 
occurs, @code{connect} returns @code{-1}.  The following @code{errno}
1992
 
error conditions are defined for this function:
1993
 
 
1994
 
@table @code
1995
 
@item EBADF
1996
 
The socket @var{socket} is not a valid file descriptor.
1997
 
 
1998
 
@item ENOTSOCK
1999
 
File descriptor @var{socket} is not a socket.
2000
 
 
2001
 
@item EADDRNOTAVAIL
2002
 
The specified address is not available on the remote machine.
2003
 
 
2004
 
@item EAFNOSUPPORT
2005
 
The namespace of the @var{addr} is not supported by this socket.
2006
 
 
2007
 
@item EISCONN
2008
 
The socket @var{socket} is already connected.
2009
 
 
2010
 
@item ETIMEDOUT
2011
 
The attempt to establish the connection timed out.
2012
 
 
2013
 
@item ECONNREFUSED
2014
 
The server has actively refused to establish the connection.
2015
 
 
2016
 
@item ENETUNREACH
2017
 
The network of the given @var{addr} isn't reachable from this host.
2018
 
 
2019
 
@item EADDRINUSE
2020
 
The socket address of the given @var{addr} is already in use.
2021
 
 
2022
 
@item EINPROGRESS
2023
 
The socket @var{socket} is non-blocking and the connection could not be
2024
 
established immediately.  You can determine when the connection is
2025
 
completely established with @code{select}; @pxref{Waiting for I/O}.
2026
 
Another @code{connect} call on the same socket, before the connection is
2027
 
completely established, will fail with @code{EALREADY}.
2028
 
 
2029
 
@item EALREADY
2030
 
The socket @var{socket} is non-blocking and already has a pending
2031
 
connection in progress (see @code{EINPROGRESS} above).
2032
 
@end table
2033
 
 
2034
 
This function is defined as a cancellation point in multi-threaded
2035
 
programs, so one has to be prepared for this and make sure that
2036
 
allocated resources (like memory, files descriptors, semaphores or
2037
 
whatever) are freed even if the thread is canceled.
2038
 
@c @xref{pthread_cleanup_push}, for a method how to do this.
2039
 
@end deftypefun
2040
 
 
2041
 
@node Listening
2042
 
@subsection Listening for Connections
2043
 
@cindex listening (sockets)
2044
 
@cindex sockets, server actions
2045
 
@cindex sockets, listening
2046
 
 
2047
 
Now let us consider what the server process must do to accept
2048
 
connections on a socket.  First it must use the @code{listen} function
2049
 
to enable connection requests on the socket, and then accept each
2050
 
incoming connection with a call to @code{accept} (@pxref{Accepting
2051
 
Connections}).  Once connection requests are enabled on a server socket,
2052
 
the @code{select} function reports when the socket has a connection
2053
 
ready to be accepted (@pxref{Waiting for I/O}).
2054
 
 
2055
 
The @code{listen} function is not allowed for sockets using
2056
 
connectionless communication styles.
2057
 
 
2058
 
You can write a network server that does not even start running until a
2059
 
connection to it is requested.  @xref{Inetd Servers}.
2060
 
 
2061
 
In the Internet namespace, there are no special protection mechanisms
2062
 
for controlling access to a port; any process on any machine
2063
 
can make a connection to your server.  If you want to restrict access to
2064
 
your server, make it examine the addresses associated with connection
2065
 
requests or implement some other handshaking or identification
2066
 
protocol.
2067
 
 
2068
 
In the local namespace, the ordinary file protection bits control who has
2069
 
access to connect to the socket.
2070
 
 
2071
 
@comment sys/socket.h
2072
 
@comment BSD
2073
 
@deftypefun int listen (int @var{socket}, int @var{n})
2074
 
The @code{listen} function enables the socket @var{socket} to accept
2075
 
connections, thus making it a server socket.
2076
 
 
2077
 
The argument @var{n} specifies the length of the queue for pending
2078
 
connections.  When the queue fills, new clients attempting to connect
2079
 
fail with @code{ECONNREFUSED} until the server calls @code{accept} to
2080
 
accept a connection from the queue.
2081
 
 
2082
 
The @code{listen} function returns @code{0} on success and @code{-1}
2083
 
on failure.  The following @code{errno} error conditions are defined
2084
 
for this function:
2085
 
 
2086
 
@table @code
2087
 
@item EBADF
2088
 
The argument @var{socket} is not a valid file descriptor.
2089
 
 
2090
 
@item ENOTSOCK
2091
 
The argument @var{socket} is not a socket.
2092
 
 
2093
 
@item EOPNOTSUPP
2094
 
The socket @var{socket} does not support this operation.
2095
 
@end table
2096
 
@end deftypefun
2097
 
 
2098
 
@node Accepting Connections
2099
 
@subsection Accepting Connections
2100
 
@cindex sockets, accepting connections
2101
 
@cindex accepting connections
2102
 
 
2103
 
When a server receives a connection request, it can complete the
2104
 
connection by accepting the request.  Use the function @code{accept}
2105
 
to do this.
2106
 
 
2107
 
A socket that has been established as a server can accept connection
2108
 
requests from multiple clients.  The server's original socket
2109
 
@emph{does not become part of the connection}; instead, @code{accept}
2110
 
makes a new socket which participates in the connection.
2111
 
@code{accept} returns the descriptor for this socket.  The server's
2112
 
original socket remains available for listening for further connection
2113
 
requests.
2114
 
 
2115
 
The number of pending connection requests on a server socket is finite.
2116
 
If connection requests arrive from clients faster than the server can
2117
 
act upon them, the queue can fill up and additional requests are refused
2118
 
with an @code{ECONNREFUSED} error.  You can specify the maximum length of
2119
 
this queue as an argument to the @code{listen} function, although the
2120
 
system may also impose its own internal limit on the length of this
2121
 
queue.
2122
 
 
2123
 
@comment sys/socket.h
2124
 
@comment BSD
2125
 
@deftypefun int accept (int @var{socket}, struct sockaddr *@var{addr}, socklen_t *@var{length_ptr})
2126
 
This function is used to accept a connection request on the server
2127
 
socket @var{socket}.
2128
 
 
2129
 
The @code{accept} function waits if there are no connections pending,
2130
 
unless the socket @var{socket} has nonblocking mode set.  (You can use
2131
 
@code{select} to wait for a pending connection, with a nonblocking
2132
 
socket.)  @xref{File Status Flags}, for information about nonblocking
2133
 
mode.
2134
 
 
2135
 
The @var{addr} and @var{length-ptr} arguments are used to return
2136
 
information about the name of the client socket that initiated the
2137
 
connection.  @xref{Socket Addresses}, for information about the format
2138
 
of the information.
2139
 
 
2140
 
Accepting a connection does not make @var{socket} part of the
2141
 
connection.  Instead, it creates a new socket which becomes
2142
 
connected.  The normal return value of @code{accept} is the file
2143
 
descriptor for the new socket.
2144
 
 
2145
 
After @code{accept}, the original socket @var{socket} remains open and
2146
 
unconnected, and continues listening until you close it.  You can
2147
 
accept further connections with @var{socket} by calling @code{accept}
2148
 
again.
2149
 
 
2150
 
If an error occurs, @code{accept} returns @code{-1}.  The following
2151
 
@code{errno} error conditions are defined for this function:
2152
 
 
2153
 
@table @code
2154
 
@item EBADF
2155
 
The @var{socket} argument is not a valid file descriptor.
2156
 
 
2157
 
@item ENOTSOCK
2158
 
The descriptor @var{socket} argument is not a socket.
2159
 
 
2160
 
@item EOPNOTSUPP
2161
 
The descriptor @var{socket} does not support this operation.
2162
 
 
2163
 
@item EWOULDBLOCK
2164
 
@var{socket} has nonblocking mode set, and there are no pending
2165
 
connections immediately available.
2166
 
@end table
2167
 
 
2168
 
This function is defined as a cancellation point in multi-threaded
2169
 
programs, so one has to be prepared for this and make sure that
2170
 
allocated resources (like memory, files descriptors, semaphores or
2171
 
whatever) are freed even if the thread is canceled.
2172
 
@c @xref{pthread_cleanup_push}, for a method how to do this.
2173
 
@end deftypefun
2174
 
 
2175
 
The @code{accept} function is not allowed for sockets using
2176
 
connectionless communication styles.
2177
 
 
2178
 
@node Who is Connected
2179
 
@subsection Who is Connected to Me?
2180
 
 
2181
 
@comment sys/socket.h
2182
 
@comment BSD
2183
 
@deftypefun int getpeername (int @var{socket}, struct sockaddr *@var{addr}, socklen_t *@var{length-ptr})
2184
 
The @code{getpeername} function returns the address of the socket that
2185
 
@var{socket} is connected to; it stores the address in the memory space
2186
 
specified by @var{addr} and @var{length-ptr}.  It stores the length of
2187
 
the address in @code{*@var{length-ptr}}.
2188
 
 
2189
 
@xref{Socket Addresses}, for information about the format of the
2190
 
address.  In some operating systems, @code{getpeername} works only for
2191
 
sockets in the Internet domain.
2192
 
 
2193
 
The return value is @code{0} on success and @code{-1} on error.  The
2194
 
following @code{errno} error conditions are defined for this function:
2195
 
 
2196
 
@table @code
2197
 
@item EBADF
2198
 
The argument @var{socket} is not a valid file descriptor.
2199
 
 
2200
 
@item ENOTSOCK
2201
 
The descriptor @var{socket} is not a socket.
2202
 
 
2203
 
@item ENOTCONN
2204
 
The socket @var{socket} is not connected.
2205
 
 
2206
 
@item ENOBUFS
2207
 
There are not enough internal buffers available.
2208
 
@end table
2209
 
@end deftypefun
2210
 
 
2211
 
 
2212
 
@node Transferring Data
2213
 
@subsection Transferring Data
2214
 
@cindex reading from a socket
2215
 
@cindex writing to a socket
2216
 
 
2217
 
Once a socket has been connected to a peer, you can use the ordinary
2218
 
@code{read} and @code{write} operations (@pxref{I/O Primitives}) to
2219
 
transfer data.  A socket is a two-way communications channel, so read
2220
 
and write operations can be performed at either end.
2221
 
 
2222
 
There are also some I/O modes that are specific to socket operations.
2223
 
In order to specify these modes, you must use the @code{recv} and
2224
 
@code{send} functions instead of the more generic @code{read} and
2225
 
@code{write} functions.  The @code{recv} and @code{send} functions take
2226
 
an additional argument which you can use to specify various flags to
2227
 
control special I/O modes.  For example, you can specify the
2228
 
@code{MSG_OOB} flag to read or write out-of-band data, the
2229
 
@code{MSG_PEEK} flag to peek at input, or the @code{MSG_DONTROUTE} flag
2230
 
to control inclusion of routing information on output.
2231
 
 
2232
 
@menu
2233
 
* Sending Data::                Sending data with @code{send}.
2234
 
* Receiving Data::              Reading data with @code{recv}.
2235
 
* Socket Data Options::         Using @code{send} and @code{recv}.
2236
 
@end menu
2237
 
 
2238
 
@node Sending Data
2239
 
@subsubsection Sending Data
2240
 
 
2241
 
@pindex sys/socket.h
2242
 
The @code{send} function is declared in the header file
2243
 
@file{sys/socket.h}.  If your @var{flags} argument is zero, you can just
2244
 
as well use @code{write} instead of @code{send}; see @ref{I/O
2245
 
Primitives}.  If the socket was connected but the connection has broken,
2246
 
you get a @code{SIGPIPE} signal for any use of @code{send} or
2247
 
@code{write} (@pxref{Miscellaneous Signals}).
2248
 
 
2249
 
@comment sys/socket.h
2250
 
@comment BSD
2251
 
@deftypefun int send (int @var{socket}, void *@var{buffer}, size_t @var{size}, int @var{flags})
2252
 
The @code{send} function is like @code{write}, but with the additional
2253
 
flags @var{flags}.  The possible values of @var{flags} are described
2254
 
in @ref{Socket Data Options}.
2255
 
 
2256
 
This function returns the number of bytes transmitted, or @code{-1} on
2257
 
failure.  If the socket is nonblocking, then @code{send} (like
2258
 
@code{write}) can return after sending just part of the data.
2259
 
@xref{File Status Flags}, for information about nonblocking mode.
2260
 
 
2261
 
Note, however, that a successful return value merely indicates that
2262
 
the message has been sent without error, not necessarily that it has
2263
 
been received without error.
2264
 
 
2265
 
The following @code{errno} error conditions are defined for this function:
2266
 
 
2267
 
@table @code
2268
 
@item EBADF
2269
 
The @var{socket} argument is not a valid file descriptor.
2270
 
 
2271
 
@item EINTR
2272
 
The operation was interrupted by a signal before any data was sent.
2273
 
@xref{Interrupted Primitives}.
2274
 
 
2275
 
@item ENOTSOCK
2276
 
The descriptor @var{socket} is not a socket.
2277
 
 
2278
 
@item EMSGSIZE
2279
 
The socket type requires that the message be sent atomically, but the
2280
 
message is too large for this to be possible.
2281
 
 
2282
 
@item EWOULDBLOCK
2283
 
Nonblocking mode has been set on the socket, and the write operation
2284
 
would block.  (Normally @code{send} blocks until the operation can be
2285
 
completed.)
2286
 
 
2287
 
@item ENOBUFS
2288
 
There is not enough internal buffer space available.
2289
 
 
2290
 
@item ENOTCONN
2291
 
You never connected this socket.
2292
 
 
2293
 
@item EPIPE
2294
 
This socket was connected but the connection is now broken.  In this
2295
 
case, @code{send} generates a @code{SIGPIPE} signal first; if that
2296
 
signal is ignored or blocked, or if its handler returns, then
2297
 
@code{send} fails with @code{EPIPE}.
2298
 
@end table
2299
 
 
2300
 
This function is defined as a cancellation point in multi-threaded
2301
 
programs, so one has to be prepared for this and make sure that
2302
 
allocated resources (like memory, files descriptors, semaphores or
2303
 
whatever) are freed even if the thread is canceled.
2304
 
@c @xref{pthread_cleanup_push}, for a method how to do this.
2305
 
@end deftypefun
2306
 
 
2307
 
@node Receiving Data
2308
 
@subsubsection Receiving Data
2309
 
 
2310
 
@pindex sys/socket.h
2311
 
The @code{recv} function is declared in the header file
2312
 
@file{sys/socket.h}.  If your @var{flags} argument is zero, you can
2313
 
just as well use @code{read} instead of @code{recv}; see @ref{I/O
2314
 
Primitives}.
2315
 
 
2316
 
@comment sys/socket.h
2317
 
@comment BSD
2318
 
@deftypefun int recv (int @var{socket}, void *@var{buffer}, size_t @var{size}, int @var{flags})
2319
 
The @code{recv} function is like @code{read}, but with the additional
2320
 
flags @var{flags}.  The possible values of @var{flags} are described
2321
 
in @ref{Socket Data Options}.
2322
 
 
2323
 
If nonblocking mode is set for @var{socket}, and no data are available to
2324
 
be read, @code{recv} fails immediately rather than waiting.  @xref{File
2325
 
Status Flags}, for information about nonblocking mode.
2326
 
 
2327
 
This function returns the number of bytes received, or @code{-1} on failure.
2328
 
The following @code{errno} error conditions are defined for this function:
2329
 
 
2330
 
@table @code
2331
 
@item EBADF
2332
 
The @var{socket} argument is not a valid file descriptor.
2333
 
 
2334
 
@item ENOTSOCK
2335
 
The descriptor @var{socket} is not a socket.
2336
 
 
2337
 
@item EWOULDBLOCK
2338
 
Nonblocking mode has been set on the socket, and the read operation
2339
 
would block.  (Normally, @code{recv} blocks until there is input
2340
 
available to be read.)
2341
 
 
2342
 
@item EINTR
2343
 
The operation was interrupted by a signal before any data was read.
2344
 
@xref{Interrupted Primitives}.
2345
 
 
2346
 
@item ENOTCONN
2347
 
You never connected this socket.
2348
 
@end table
2349
 
 
2350
 
This function is defined as a cancellation point in multi-threaded
2351
 
programs, so one has to be prepared for this and make sure that
2352
 
allocated resources (like memory, files descriptors, semaphores or
2353
 
whatever) are freed even if the thread is canceled.
2354
 
@c @xref{pthread_cleanup_push}, for a method how to do this.
2355
 
@end deftypefun
2356
 
 
2357
 
@node Socket Data Options
2358
 
@subsubsection Socket Data Options
2359
 
 
2360
 
@pindex sys/socket.h
2361
 
The @var{flags} argument to @code{send} and @code{recv} is a bit
2362
 
mask.  You can bitwise-OR the values of the following macros together
2363
 
to obtain a value for this argument.  All are defined in the header
2364
 
file @file{sys/socket.h}.
2365
 
 
2366
 
@comment sys/socket.h
2367
 
@comment BSD
2368
 
@deftypevr Macro int MSG_OOB
2369
 
Send or receive out-of-band data.  @xref{Out-of-Band Data}.
2370
 
@end deftypevr
2371
 
 
2372
 
@comment sys/socket.h
2373
 
@comment BSD
2374
 
@deftypevr Macro int MSG_PEEK
2375
 
Look at the data but don't remove it from the input queue.  This is
2376
 
only meaningful with input functions such as @code{recv}, not with
2377
 
@code{send}.
2378
 
@end deftypevr
2379
 
 
2380
 
@comment sys/socket.h
2381
 
@comment BSD
2382
 
@deftypevr Macro int MSG_DONTROUTE
2383
 
Don't include routing information in the message.  This is only
2384
 
meaningful with output operations, and is usually only of interest for
2385
 
diagnostic or routing programs.  We don't try to explain it here.
2386
 
@end deftypevr
2387
 
 
2388
 
@node Byte Stream Example
2389
 
@subsection Byte Stream Socket Example
2390
 
 
2391
 
Here is an example client program that makes a connection for a byte
2392
 
stream socket in the Internet namespace.  It doesn't do anything
2393
 
particularly interesting once it has connected to the server; it just
2394
 
sends a text string to the server and exits.
2395
 
 
2396
 
This program uses @code{init_sockaddr} to set up the socket address; see
2397
 
@ref{Inet Example}.
2398
 
 
2399
 
@smallexample
2400
 
@include inetcli.c.texi
2401
 
@end smallexample
2402
 
 
2403
 
@node Server Example
2404
 
@subsection Byte Stream Connection Server Example
2405
 
 
2406
 
The server end is much more complicated.  Since we want to allow
2407
 
multiple clients to be connected to the server at the same time, it
2408
 
would be incorrect to wait for input from a single client by simply
2409
 
calling @code{read} or @code{recv}.  Instead, the right thing to do is
2410
 
to use @code{select} (@pxref{Waiting for I/O}) to wait for input on
2411
 
all of the open sockets.  This also allows the server to deal with
2412
 
additional connection requests.
2413
 
 
2414
 
This particular server doesn't do anything interesting once it has
2415
 
gotten a message from a client.  It does close the socket for that
2416
 
client when it detects an end-of-file condition (resulting from the
2417
 
client shutting down its end of the connection).
2418
 
 
2419
 
This program uses @code{make_socket} to set up the socket address; see
2420
 
@ref{Inet Example}.
2421
 
 
2422
 
@smallexample
2423
 
@include inetsrv.c.texi
2424
 
@end smallexample
2425
 
 
2426
 
@node Out-of-Band Data
2427
 
@subsection Out-of-Band Data
2428
 
 
2429
 
@cindex out-of-band data
2430
 
@cindex high-priority data
2431
 
Streams with connections permit @dfn{out-of-band} data that is
2432
 
delivered with higher priority than ordinary data.  Typically the
2433
 
reason for sending out-of-band data is to send notice of an
2434
 
exceptional condition.  To send out-of-band data use
2435
 
@code{send}, specifying the flag @code{MSG_OOB} (@pxref{Sending
2436
 
Data}).
2437
 
 
2438
 
Out-of-band data are received with higher priority because the
2439
 
receiving process need not read it in sequence; to read the next
2440
 
available out-of-band data, use @code{recv} with the @code{MSG_OOB}
2441
 
flag (@pxref{Receiving Data}).  Ordinary read operations do not read
2442
 
out-of-band data; they read only ordinary data.
2443
 
 
2444
 
@cindex urgent socket condition
2445
 
When a socket finds that out-of-band data are on their way, it sends a
2446
 
@code{SIGURG} signal to the owner process or process group of the
2447
 
socket.  You can specify the owner using the @code{F_SETOWN} command
2448
 
to the @code{fcntl} function; see @ref{Interrupt Input}.  You must
2449
 
also establish a handler for this signal, as described in @ref{Signal
2450
 
Handling}, in order to take appropriate action such as reading the
2451
 
out-of-band data.
2452
 
 
2453
 
Alternatively, you can test for pending out-of-band data, or wait
2454
 
until there is out-of-band data, using the @code{select} function; it
2455
 
can wait for an exceptional condition on the socket.  @xref{Waiting
2456
 
for I/O}, for more information about @code{select}.
2457
 
 
2458
 
Notification of out-of-band data (whether with @code{SIGURG} or with
2459
 
@code{select}) indicates that out-of-band data are on the way; the data
2460
 
may not actually arrive until later.  If you try to read the
2461
 
out-of-band data before it arrives, @code{recv} fails with an
2462
 
@code{EWOULDBLOCK} error.
2463
 
 
2464
 
Sending out-of-band data automatically places a ``mark'' in the stream
2465
 
of ordinary data, showing where in the sequence the out-of-band data
2466
 
``would have been''.  This is useful when the meaning of out-of-band
2467
 
data is ``cancel everything sent so far''.  Here is how you can test,
2468
 
in the receiving process, whether any ordinary data was sent before
2469
 
the mark:
2470
 
 
2471
 
@smallexample
2472
 
success = ioctl (socket, SIOCATMARK, &atmark);
2473
 
@end smallexample
2474
 
 
2475
 
The @code{integer} variable @var{atmark} is set to a nonzero value if
2476
 
the socket's read pointer has reached the ``mark''.
2477
 
 
2478
 
@c Posix  1.g specifies sockatmark for this ioctl.  sockatmark is not
2479
 
@c implemented yet.
2480
 
 
2481
 
Here's a function to discard any ordinary data preceding the
2482
 
out-of-band mark:
2483
 
 
2484
 
@smallexample
2485
 
int
2486
 
discard_until_mark (int socket)
2487
 
@{
2488
 
  while (1)
2489
 
    @{
2490
 
      /* @r{This is not an arbitrary limit; any size will do.}  */
2491
 
      char buffer[1024];
2492
 
      int atmark, success;
2493
 
 
2494
 
      /* @r{If we have reached the mark, return.}  */
2495
 
      success = ioctl (socket, SIOCATMARK, &atmark);
2496
 
      if (success < 0)
2497
 
        perror ("ioctl");
2498
 
      if (result)
2499
 
        return;
2500
 
 
2501
 
      /* @r{Otherwise, read a bunch of ordinary data and discard it.}
2502
 
         @r{This is guaranteed not to read past the mark}
2503
 
         @r{if it starts before the mark.}  */
2504
 
      success = read (socket, buffer, sizeof buffer);
2505
 
      if (success < 0)
2506
 
        perror ("read");
2507
 
    @}
2508
 
@}
2509
 
@end smallexample
2510
 
 
2511
 
If you don't want to discard the ordinary data preceding the mark, you
2512
 
may need to read some of it anyway, to make room in internal system
2513
 
buffers for the out-of-band data.  If you try to read out-of-band data
2514
 
and get an @code{EWOULDBLOCK} error, try reading some ordinary data
2515
 
(saving it so that you can use it when you want it) and see if that
2516
 
makes room.  Here is an example:
2517
 
 
2518
 
@smallexample
2519
 
struct buffer
2520
 
@{
2521
 
  char *buf;
2522
 
  int size;
2523
 
  struct buffer *next;
2524
 
@};
2525
 
 
2526
 
/* @r{Read the out-of-band data from SOCKET and return it}
2527
 
   @r{as a `struct buffer', which records the address of the data}
2528
 
   @r{and its size.}
2529
 
 
2530
 
   @r{It may be necessary to read some ordinary data}
2531
 
   @r{in order to make room for the out-of-band data.}
2532
 
   @r{If so, the ordinary data are saved as a chain of buffers}
2533
 
   @r{found in the `next' field of the value.}  */
2534
 
 
2535
 
struct buffer *
2536
 
read_oob (int socket)
2537
 
@{
2538
 
  struct buffer *tail = 0;
2539
 
  struct buffer *list = 0;
2540
 
 
2541
 
  while (1)
2542
 
    @{
2543
 
      /* @r{This is an arbitrary limit.}
2544
 
         @r{Does anyone know how to do this without a limit?}  */
2545
 
#define BUF_SZ 1024
2546
 
      char *buf = (char *) xmalloc (BUF_SZ);
2547
 
      int success;
2548
 
      int atmark;
2549
 
 
2550
 
      /* @r{Try again to read the out-of-band data.}  */
2551
 
      success = recv (socket, buf, BUF_SZ, MSG_OOB);
2552
 
      if (success >= 0)
2553
 
        @{
2554
 
          /* @r{We got it, so return it.}  */
2555
 
          struct buffer *link
2556
 
            = (struct buffer *) xmalloc (sizeof (struct buffer));
2557
 
          link->buf = buf;
2558
 
          link->size = success;
2559
 
          link->next = list;
2560
 
          return link;
2561
 
        @}
2562
 
 
2563
 
      /* @r{If we fail, see if we are at the mark.}  */
2564
 
      success = ioctl (socket, SIOCATMARK, &atmark);
2565
 
      if (success < 0)
2566
 
        perror ("ioctl");
2567
 
      if (atmark)
2568
 
        @{
2569
 
          /* @r{At the mark; skipping past more ordinary data cannot help.}
2570
 
             @r{So just wait a while.}  */
2571
 
          sleep (1);
2572
 
          continue;
2573
 
        @}
2574
 
 
2575
 
      /* @r{Otherwise, read a bunch of ordinary data and save it.}
2576
 
         @r{This is guaranteed not to read past the mark}
2577
 
         @r{if it starts before the mark.}  */
2578
 
      success = read (socket, buf, BUF_SZ);
2579
 
      if (success < 0)
2580
 
        perror ("read");
2581
 
 
2582
 
      /* @r{Save this data in the buffer list.}  */
2583
 
      @{
2584
 
        struct buffer *link
2585
 
          = (struct buffer *) xmalloc (sizeof (struct buffer));
2586
 
        link->buf = buf;
2587
 
        link->size = success;
2588
 
 
2589
 
        /* @r{Add the new link to the end of the list.}  */
2590
 
        if (tail)
2591
 
          tail->next = link;
2592
 
        else
2593
 
          list = link;
2594
 
        tail = link;
2595
 
      @}
2596
 
    @}
2597
 
@}
2598
 
@end smallexample
2599
 
 
2600
 
@node Datagrams
2601
 
@section Datagram Socket Operations
2602
 
 
2603
 
@cindex datagram socket
2604
 
This section describes how to use communication styles that don't use
2605
 
connections (styles @code{SOCK_DGRAM} and @code{SOCK_RDM}).  Using
2606
 
these styles, you group data into packets and each packet is an
2607
 
independent communication.  You specify the destination for each
2608
 
packet individually.
2609
 
 
2610
 
Datagram packets are like letters: you send each one independently
2611
 
with its own destination address, and they may arrive in the wrong
2612
 
order or not at all.
2613
 
 
2614
 
The @code{listen} and @code{accept} functions are not allowed for
2615
 
sockets using connectionless communication styles.
2616
 
 
2617
 
@menu
2618
 
* Sending Datagrams::    Sending packets on a datagram socket.
2619
 
* Receiving Datagrams::  Receiving packets on a datagram socket.
2620
 
* Datagram Example::     An example program: packets sent over a
2621
 
                           datagram socket in the local namespace.
2622
 
* Example Receiver::     Another program, that receives those packets.
2623
 
@end menu
2624
 
 
2625
 
@node Sending Datagrams
2626
 
@subsection Sending Datagrams
2627
 
@cindex sending a datagram
2628
 
@cindex transmitting datagrams
2629
 
@cindex datagrams, transmitting
2630
 
 
2631
 
@pindex sys/socket.h
2632
 
The normal way of sending data on a datagram socket is by using the
2633
 
@code{sendto} function, declared in @file{sys/socket.h}.
2634
 
 
2635
 
You can call @code{connect} on a datagram socket, but this only
2636
 
specifies a default destination for further data transmission on the
2637
 
socket.  When a socket has a default destination you can use
2638
 
@code{send} (@pxref{Sending Data}) or even @code{write} (@pxref{I/O
2639
 
Primitives}) to send a packet there.  You can cancel the default
2640
 
destination by calling @code{connect} using an address format of
2641
 
@code{AF_UNSPEC} in the @var{addr} argument.  @xref{Connecting}, for
2642
 
more information about the @code{connect} function.
2643
 
 
2644
 
@comment sys/socket.h
2645
 
@comment BSD
2646
 
@deftypefun int sendto (int @var{socket}, void *@var{buffer}. size_t @var{size}, int @var{flags}, struct sockaddr *@var{addr}, socklen_t @var{length})
2647
 
The @code{sendto} function transmits the data in the @var{buffer}
2648
 
through the socket @var{socket} to the destination address specified
2649
 
by the @var{addr} and @var{length} arguments.  The @var{size} argument
2650
 
specifies the number of bytes to be transmitted.
2651
 
 
2652
 
The @var{flags} are interpreted the same way as for @code{send}; see
2653
 
@ref{Socket Data Options}.
2654
 
 
2655
 
The return value and error conditions are also the same as for
2656
 
@code{send}, but you cannot rely on the system to detect errors and
2657
 
report them; the most common error is that the packet is lost or there
2658
 
is no-one at the specified address to receive it, and the operating
2659
 
system on your machine usually does not know this.
2660
 
 
2661
 
It is also possible for one call to @code{sendto} to report an error
2662
 
owing to a problem related to a previous call.
2663
 
 
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.
2668
 
@c @xref{pthread_cleanup_push}, for a method how to do this.
2669
 
@end deftypefun
2670
 
 
2671
 
@node Receiving Datagrams
2672
 
@subsection Receiving Datagrams
2673
 
@cindex receiving datagrams
2674
 
 
2675
 
The @code{recvfrom} function reads a packet from a datagram socket and
2676
 
also tells you where it was sent from.  This function is declared in
2677
 
@file{sys/socket.h}.
2678
 
 
2679
 
@comment sys/socket.h
2680
 
@comment BSD
2681
 
@deftypefun int recvfrom (int @var{socket}, void *@var{buffer}, size_t @var{size}, int @var{flags}, struct sockaddr *@var{addr}, socklen_t *@var{length-ptr})
2682
 
The @code{recvfrom} function reads one packet from the socket
2683
 
@var{socket} into the buffer @var{buffer}.  The @var{size} argument
2684
 
specifies the maximum number of bytes to be read.
2685
 
 
2686
 
If the packet is longer than @var{size} bytes, then you get the first
2687
 
@var{size} bytes of the packet and the rest of the packet is lost.
2688
 
There's no way to read the rest of the packet.  Thus, when you use a
2689
 
packet protocol, you must always know how long a packet to expect.
2690
 
 
2691
 
The @var{addr} and @var{length-ptr} arguments are used to return the
2692
 
address where the packet came from.  @xref{Socket Addresses}.  For a
2693
 
socket in the local domain the address information won't be meaningful,
2694
 
since you can't read the address of such a socket (@pxref{Local
2695
 
Namespace}).  You can specify a null pointer as the @var{addr} argument
2696
 
if you are not interested in this information.
2697
 
 
2698
 
The @var{flags} are interpreted the same way as for @code{recv}
2699
 
(@pxref{Socket Data Options}).  The return value and error conditions
2700
 
are also the same as for @code{recv}.
2701
 
 
2702
 
This function is defined as a cancellation point in multi-threaded
2703
 
programs, so one has to be prepared for this and make sure that
2704
 
allocated resources (like memory, files descriptors, semaphores or
2705
 
whatever) are freed even if the thread is canceled.
2706
 
@c @xref{pthread_cleanup_push}, for a method how to do this.
2707
 
@end deftypefun
2708
 
 
2709
 
You can use plain @code{recv} (@pxref{Receiving Data}) instead of
2710
 
@code{recvfrom} if you don't need to find out who sent the packet
2711
 
(either because you know where it should come from or because you
2712
 
treat all possible senders alike).  Even @code{read} can be used if
2713
 
you don't want to specify @var{flags} (@pxref{I/O Primitives}).
2714
 
 
2715
 
@ignore
2716
 
@c sendmsg and recvmsg are like readv and writev in that they
2717
 
@c use a series of buffers.  It's not clear this is worth
2718
 
@c supporting or that we support them.
2719
 
@c !!! they can do more; it is hairy
2720
 
 
2721
 
@comment sys/socket.h
2722
 
@comment BSD
2723
 
@deftp {Data Type} {struct msghdr}
2724
 
@end deftp
2725
 
 
2726
 
@comment sys/socket.h
2727
 
@comment BSD
2728
 
@deftypefun int sendmsg (int @var{socket}, const struct msghdr *@var{message}, int @var{flags})
2729
 
 
2730
 
This function is defined as a cancellation point in multi-threaded
2731
 
programs, so one has to be prepared for this and make sure that
2732
 
allocated resources (like memory, files descriptors, semaphores or
2733
 
whatever) are freed even if the thread is cancel.
2734
 
@c @xref{pthread_cleanup_push}, for a method how to do this.
2735
 
@end deftypefun
2736
 
 
2737
 
@comment sys/socket.h
2738
 
@comment BSD
2739
 
@deftypefun int recvmsg (int @var{socket}, struct msghdr *@var{message}, int @var{flags})
2740
 
 
2741
 
This function is defined as a cancellation point in multi-threaded
2742
 
programs, so one has to be prepared for this and make sure that
2743
 
allocated resources (like memory, files descriptors, semaphores or
2744
 
whatever) are freed even if the thread is canceled.
2745
 
@c @xref{pthread_cleanup_push}, for a method how to do this.
2746
 
@end deftypefun
2747
 
@end ignore
2748
 
 
2749
 
@node Datagram Example
2750
 
@subsection Datagram Socket Example
2751
 
 
2752
 
Here is a set of example programs that send messages over a datagram
2753
 
stream in the local namespace.  Both the client and server programs use
2754
 
the @code{make_named_socket} function that was presented in @ref{Local
2755
 
Socket Example}, to create and name their sockets.
2756
 
 
2757
 
First, here is the server program.  It sits in a loop waiting for
2758
 
messages to arrive, bouncing each message back to the sender.
2759
 
Obviously this isn't a particularly useful program, but it does show
2760
 
the general ideas involved.
2761
 
 
2762
 
@smallexample
2763
 
@include filesrv.c.texi
2764
 
@end smallexample
2765
 
 
2766
 
@node Example Receiver
2767
 
@subsection Example of Reading Datagrams
2768
 
 
2769
 
Here is the client program corresponding to the server above.
2770
 
 
2771
 
It sends a datagram to the server and then waits for a reply.  Notice
2772
 
that the socket for the client (as well as for the server) in this
2773
 
example has to be given a name.  This is so that the server can direct
2774
 
a message back to the client.  Since the socket has no associated
2775
 
connection state, the only way the server can do this is by
2776
 
referencing the name of the client.
2777
 
 
2778
 
@smallexample
2779
 
@include filecli.c.texi
2780
 
@end smallexample
2781
 
 
2782
 
Keep in mind that datagram socket communications are unreliable.  In
2783
 
this example, the client program waits indefinitely if the message
2784
 
never reaches the server or if the server's response never comes
2785
 
back.  It's up to the user running the program to kill and restart
2786
 
it if desired.  A more automatic solution could be to use
2787
 
@code{select} (@pxref{Waiting for I/O}) to establish a timeout period
2788
 
for the reply, and in case of timeout either re-send the message or
2789
 
shut down the socket and exit.
2790
 
 
2791
 
@node Inetd
2792
 
@section The @code{inetd} Daemon
2793
 
 
2794
 
We've explained above how to write a server program that does its own
2795
 
listening.  Such a server must already be running in order for anyone
2796
 
to connect to it.
2797
 
 
2798
 
Another way to provide a service on an Internet port is to let the daemon
2799
 
program @code{inetd} do the listening.  @code{inetd} is a program that
2800
 
runs all the time and waits (using @code{select}) for messages on a
2801
 
specified set of ports.  When it receives a message, it accepts the
2802
 
connection (if the socket style calls for connections) and then forks a
2803
 
child process to run the corresponding server program.  You specify the
2804
 
ports and their programs in the file @file{/etc/inetd.conf}.
2805
 
 
2806
 
@menu
2807
 
* Inetd Servers::
2808
 
* Configuring Inetd::
2809
 
@end menu
2810
 
 
2811
 
@node Inetd Servers
2812
 
@subsection @code{inetd} Servers
2813
 
 
2814
 
Writing a server program to be run by @code{inetd} is very simple.  Each time
2815
 
someone requests a connection to the appropriate port, a new server
2816
 
process starts.  The connection already exists at this time; the
2817
 
socket is available as the standard input descriptor and as the
2818
 
standard output descriptor (descriptors 0 and 1) in the server
2819
 
process.  Thus the server program can begin reading and writing data
2820
 
right away.  Often the program needs only the ordinary I/O facilities;
2821
 
in fact, a general-purpose filter program that knows nothing about
2822
 
sockets can work as a byte stream server run by @code{inetd}.
2823
 
 
2824
 
You can also use @code{inetd} for servers that use connectionless
2825
 
communication styles.  For these servers, @code{inetd} does not try to accept
2826
 
a connection since no connection is possible.  It just starts the
2827
 
server program, which can read the incoming datagram packet from
2828
 
descriptor 0.  The server program can handle one request and then
2829
 
exit, or you can choose to write it to keep reading more requests
2830
 
until no more arrive, and then exit.  You must specify which of these
2831
 
two techniques the server uses when you configure @code{inetd}.
2832
 
 
2833
 
@node Configuring Inetd
2834
 
@subsection Configuring @code{inetd}
2835
 
 
2836
 
The file @file{/etc/inetd.conf} tells @code{inetd} which ports to listen to
2837
 
and what server programs to run for them.  Normally each entry in the
2838
 
file is one line, but you can split it onto multiple lines provided
2839
 
all but the first line of the entry start with whitespace.  Lines that
2840
 
start with @samp{#} are comments.
2841
 
 
2842
 
Here are two standard entries in @file{/etc/inetd.conf}:
2843
 
 
2844
 
@smallexample
2845
 
ftp     stream  tcp     nowait  root    /libexec/ftpd   ftpd
2846
 
talk    dgram   udp     wait    root    /libexec/talkd  talkd
2847
 
@end smallexample
2848
 
 
2849
 
An entry has this format:
2850
 
 
2851
 
@smallexample
2852
 
@var{service} @var{style} @var{protocol} @var{wait} @var{username} @var{program} @var{arguments}
2853
 
@end smallexample
2854
 
 
2855
 
The @var{service} field says which service this program provides.  It
2856
 
should be the name of a service defined in @file{/etc/services}.
2857
 
@code{inetd} uses @var{service} to decide which port to listen on for
2858
 
this entry.
2859
 
 
2860
 
The fields @var{style} and @var{protocol} specify the communication
2861
 
style and the protocol to use for the listening socket.  The style
2862
 
should be the name of a communication style, converted to lower case
2863
 
and with @samp{SOCK_} deleted---for example, @samp{stream} or
2864
 
@samp{dgram}.  @var{protocol} should be one of the protocols listed in
2865
 
@file{/etc/protocols}.  The typical protocol names are @samp{tcp} for
2866
 
byte stream connections and @samp{udp} for unreliable datagrams.
2867
 
 
2868
 
The @var{wait} field should be either @samp{wait} or @samp{nowait}.
2869
 
Use @samp{wait} if @var{style} is a connectionless style and the
2870
 
server, once started, handles multiple requests as they come in.
2871
 
Use @samp{nowait} if @code{inetd} should start a new process for each message
2872
 
or request that comes in.  If @var{style} uses connections, then
2873
 
@var{wait} @strong{must} be @samp{nowait}.
2874
 
 
2875
 
@var{user} is the user name that the server should run as.  @code{inetd} runs
2876
 
as root, so it can set the user ID of its children arbitrarily.  It's
2877
 
best to avoid using @samp{root} for @var{user} if you can; but some
2878
 
servers, such as Telnet and FTP, read a username and password
2879
 
themselves.  These servers need to be root initially so they can log
2880
 
in as commanded by the data coming over the network.
2881
 
 
2882
 
@var{program} together with @var{arguments} specifies the command to
2883
 
run to start the server.  @var{program} should be an absolute file
2884
 
name specifying the executable file to run.  @var{arguments} consists
2885
 
of any number of whitespace-separated words, which become the
2886
 
command-line arguments of @var{program}.  The first word in
2887
 
@var{arguments} is argument zero, which should by convention be the
2888
 
program name itself (sans directories).
2889
 
 
2890
 
If you edit @file{/etc/inetd.conf}, you can tell @code{inetd} to reread the
2891
 
file and obey its new contents by sending the @code{inetd} process the
2892
 
@code{SIGHUP} signal.  You'll have to use @code{ps} to determine the
2893
 
process ID of the @code{inetd} process as it is not fixed.
2894
 
 
2895
 
@c !!! could document /etc/inetd.sec
2896
 
 
2897
 
@node Socket Options
2898
 
@section Socket Options
2899
 
@cindex socket options
2900
 
 
2901
 
This section describes how to read or set various options that modify
2902
 
the behavior of sockets and their underlying communications protocols.
2903
 
 
2904
 
@cindex level, for socket options
2905
 
@cindex socket option level
2906
 
When you are manipulating a socket option, you must specify which
2907
 
@dfn{level} the option pertains to.  This describes whether the option
2908
 
applies to the socket interface, or to a lower-level communications
2909
 
protocol interface.
2910
 
 
2911
 
@menu
2912
 
* Socket Option Functions::     The basic functions for setting and getting
2913
 
                                 socket options.
2914
 
* Socket-Level Options::        Details of the options at the socket level.
2915
 
@end menu
2916
 
 
2917
 
@node Socket Option Functions
2918
 
@subsection Socket Option Functions
2919
 
 
2920
 
@pindex sys/socket.h
2921
 
Here are the functions for examining and modifying socket options.
2922
 
They are declared in @file{sys/socket.h}.
2923
 
 
2924
 
@comment sys/socket.h
2925
 
@comment BSD
2926
 
@deftypefun int getsockopt (int @var{socket}, int @var{level}, int @var{optname}, void *@var{optval}, socklen_t *@var{optlen-ptr})
2927
 
The @code{getsockopt} function gets information about the value of
2928
 
option @var{optname} at level @var{level} for socket @var{socket}.
2929
 
 
2930
 
The option value is stored in a buffer that @var{optval} points to.
2931
 
Before the call, you should supply in @code{*@var{optlen-ptr}} the
2932
 
size of this buffer; on return, it contains the number of bytes of
2933
 
information actually stored in the buffer.
2934
 
 
2935
 
Most options interpret the @var{optval} buffer as a single @code{int}
2936
 
value.
2937
 
 
2938
 
The actual return value of @code{getsockopt} is @code{0} on success
2939
 
and @code{-1} on failure.  The following @code{errno} error conditions
2940
 
are defined:
2941
 
 
2942
 
@table @code
2943
 
@item EBADF
2944
 
The @var{socket} argument is not a valid file descriptor.
2945
 
 
2946
 
@item ENOTSOCK
2947
 
The descriptor @var{socket} is not a socket.
2948
 
 
2949
 
@item ENOPROTOOPT
2950
 
The @var{optname} doesn't make sense for the given @var{level}.
2951
 
@end table
2952
 
@end deftypefun
2953
 
 
2954
 
@comment sys/socket.h
2955
 
@comment BSD
2956
 
@deftypefun int setsockopt (int @var{socket}, int @var{level}, int @var{optname}, void *@var{optval}, socklen_t @var{optlen})
2957
 
This function is used to set the socket option @var{optname} at level
2958
 
@var{level} for socket @var{socket}.  The value of the option is passed
2959
 
in the buffer @var{optval} of size @var{optlen}.
2960
 
 
2961
 
@c Argh. -zw
2962
 
@iftex
2963
 
@hfuzz 6pt
2964
 
The return value and error codes for @code{setsockopt} are the same as
2965
 
for @code{getsockopt}.
2966
 
@end iftex
2967
 
@ifinfo
2968
 
The return value and error codes for @code{setsockopt} are the same as
2969
 
for @code{getsockopt}.
2970
 
@end ifinfo
2971
 
 
2972
 
@end deftypefun
2973
 
 
2974
 
@node Socket-Level Options
2975
 
@subsection Socket-Level Options
2976
 
 
2977
 
@comment sys/socket.h
2978
 
@comment BSD
2979
 
@deftypevr Constant int SOL_SOCKET
2980
 
Use this constant as the @var{level} argument to @code{getsockopt} or
2981
 
@code{setsockopt} to manipulate the socket-level options described in
2982
 
this section.
2983
 
@end deftypevr
2984
 
 
2985
 
@pindex sys/socket.h
2986
 
@noindent
2987
 
Here is a table of socket-level option names; all are defined in the
2988
 
header file @file{sys/socket.h}.
2989
 
 
2990
 
@table @code
2991
 
@comment sys/socket.h
2992
 
@comment BSD
2993
 
@item SO_DEBUG
2994
 
@c Extra blank line here makes the table look better.
2995
 
 
2996
 
This option toggles recording of debugging information in the underlying
2997
 
protocol modules.  The value has type @code{int}; a nonzero value means
2998
 
``yes''.
2999
 
@c !!! should say how this is used
3000
 
@c OK, anyone who knows, please explain.
3001
 
 
3002
 
@comment sys/socket.h
3003
 
@comment BSD
3004
 
@item SO_REUSEADDR
3005
 
This option controls whether @code{bind} (@pxref{Setting Address})
3006
 
should permit reuse of local addresses for this socket.  If you enable
3007
 
this option, you can actually have two sockets with the same Internet
3008
 
port number; but the system won't allow you to use the two
3009
 
identically-named sockets in a way that would confuse the Internet.  The
3010
 
reason for this option is that some higher-level Internet protocols,
3011
 
including FTP, require you to keep reusing the same port number.
3012
 
 
3013
 
The value has type @code{int}; a nonzero value means ``yes''.
3014
 
 
3015
 
@comment sys/socket.h
3016
 
@comment BSD
3017
 
@item SO_KEEPALIVE
3018
 
This option controls whether the underlying protocol should
3019
 
periodically transmit messages on a connected socket.  If the peer
3020
 
fails to respond to these messages, the connection is considered
3021
 
broken.  The value has type @code{int}; a nonzero value means
3022
 
``yes''.
3023
 
 
3024
 
@comment sys/socket.h
3025
 
@comment BSD
3026
 
@item SO_DONTROUTE
3027
 
This option controls whether outgoing messages bypass the normal
3028
 
message routing facilities.  If set, messages are sent directly to the
3029
 
network interface instead.  The value has type @code{int}; a nonzero
3030
 
value means ``yes''.
3031
 
 
3032
 
@comment sys/socket.h
3033
 
@comment BSD
3034
 
@item SO_LINGER
3035
 
This option specifies what should happen when the socket of a type
3036
 
that promises reliable delivery still has untransmitted messages when
3037
 
it is closed; see @ref{Closing a Socket}.  The value has type
3038
 
@code{struct linger}.
3039
 
 
3040
 
@comment sys/socket.h
3041
 
@comment BSD
3042
 
@deftp {Data Type} {struct linger}
3043
 
This structure type has the following members:
3044
 
 
3045
 
@table @code
3046
 
@item int l_onoff
3047
 
This field is interpreted as a boolean.  If nonzero, @code{close}
3048
 
blocks until the data are transmitted or the timeout period has expired.
3049
 
 
3050
 
@item int l_linger
3051
 
This specifies the timeout period, in seconds.
3052
 
@end table
3053
 
@end deftp
3054
 
 
3055
 
@comment sys/socket.h
3056
 
@comment BSD
3057
 
@item SO_BROADCAST
3058
 
This option controls whether datagrams may be broadcast from the socket.
3059
 
The value has type @code{int}; a nonzero value means ``yes''.
3060
 
 
3061
 
@comment sys/socket.h
3062
 
@comment BSD
3063
 
@item SO_OOBINLINE
3064
 
If this option is set, out-of-band data received on the socket is
3065
 
placed in the normal input queue.  This permits it to be read using
3066
 
@code{read} or @code{recv} without specifying the @code{MSG_OOB}
3067
 
flag.  @xref{Out-of-Band Data}.  The value has type @code{int}; a
3068
 
nonzero value means ``yes''.
3069
 
 
3070
 
@comment sys/socket.h
3071
 
@comment BSD
3072
 
@item SO_SNDBUF
3073
 
This option gets or sets the size of the output buffer.  The value is a
3074
 
@code{size_t}, which is the size in bytes.
3075
 
 
3076
 
@comment sys/socket.h
3077
 
@comment BSD
3078
 
@item SO_RCVBUF
3079
 
This option gets or sets the size of the input buffer.  The value is a
3080
 
@code{size_t}, which is the size in bytes.
3081
 
 
3082
 
@comment sys/socket.h
3083
 
@comment GNU
3084
 
@item SO_STYLE
3085
 
@comment sys/socket.h
3086
 
@comment BSD
3087
 
@itemx SO_TYPE
3088
 
This option can be used with @code{getsockopt} only.  It is used to
3089
 
get the socket's communication style.  @code{SO_TYPE} is the
3090
 
historical name, and @code{SO_STYLE} is the preferred name in GNU.
3091
 
The value has type @code{int} and its value designates a communication
3092
 
style; see @ref{Communication Styles}.
3093
 
 
3094
 
@comment sys/socket.h
3095
 
@comment BSD
3096
 
@item SO_ERROR
3097
 
@c Extra blank line here makes the table look better.
3098
 
 
3099
 
This option can be used with @code{getsockopt} only.  It is used to reset
3100
 
the error status of the socket.  The value is an @code{int}, which represents
3101
 
the previous error status.
3102
 
@c !!! what is "socket error status"?  this is never defined.
3103
 
@end table
3104
 
 
3105
 
@node Networks Database
3106
 
@section Networks Database
3107
 
@cindex networks database
3108
 
@cindex converting network number to network name
3109
 
@cindex converting network name to network number
3110
 
 
3111
 
@pindex /etc/networks
3112
 
@pindex netdb.h
3113
 
Many systems come with a database that records a list of networks known
3114
 
to the system developer.  This is usually kept either in the file
3115
 
@file{/etc/networks} or in an equivalent from a name server.  This data
3116
 
base is useful for routing programs such as @code{route}, but it is not
3117
 
useful for programs that simply communicate over the network.  We
3118
 
provide functions to access this database, which are declared in
3119
 
@file{netdb.h}.
3120
 
 
3121
 
@comment netdb.h
3122
 
@comment BSD
3123
 
@deftp {Data Type} {struct netent}
3124
 
This data type is used to represent information about entries in the
3125
 
networks database.  It has the following members:
3126
 
 
3127
 
@table @code
3128
 
@item char *n_name
3129
 
This is the ``official'' name of the network.
3130
 
 
3131
 
@item char **n_aliases
3132
 
These are alternative names for the network, represented as a vector
3133
 
of strings.  A null pointer terminates the array.
3134
 
 
3135
 
@item int n_addrtype
3136
 
This is the type of the network number; this is always equal to
3137
 
@code{AF_INET} for Internet networks.
3138
 
 
3139
 
@item unsigned long int n_net
3140
 
This is the network number.  Network numbers are returned in host
3141
 
byte order; see @ref{Byte Order}.
3142
 
@end table
3143
 
@end deftp
3144
 
 
3145
 
Use the @code{getnetbyname} or @code{getnetbyaddr} functions to search
3146
 
the networks database for information about a specific network.  The
3147
 
information is returned in a statically-allocated structure; you must
3148
 
copy the information if you need to save it.
3149
 
 
3150
 
@comment netdb.h
3151
 
@comment BSD
3152
 
@deftypefun {struct netent *} getnetbyname (const char *@var{name})
3153
 
The @code{getnetbyname} function returns information about the network
3154
 
named @var{name}.  It returns a null pointer if there is no such
3155
 
network.
3156
 
@end deftypefun
3157
 
 
3158
 
@comment netdb.h
3159
 
@comment BSD
3160
 
@deftypefun {struct netent *} getnetbyaddr (unsigned long int @var{net}, int @var{type})
3161
 
The @code{getnetbyaddr} function returns information about the network
3162
 
of type @var{type} with number @var{net}.  You should specify a value of
3163
 
@code{AF_INET} for the @var{type} argument for Internet networks.
3164
 
 
3165
 
@code{getnetbyaddr} returns a null pointer if there is no such
3166
 
network.
3167
 
@end deftypefun
3168
 
 
3169
 
You can also scan the networks database using @code{setnetent},
3170
 
@code{getnetent} and @code{endnetent}.  Be careful when using these
3171
 
functions because they are not reentrant.
3172
 
 
3173
 
@comment netdb.h
3174
 
@comment BSD
3175
 
@deftypefun void setnetent (int @var{stayopen})
3176
 
This function opens and rewinds the networks database.
3177
 
 
3178
 
If the @var{stayopen} argument is nonzero, this sets a flag so that
3179
 
subsequent calls to @code{getnetbyname} or @code{getnetbyaddr} will
3180
 
not close the database (as they usually would).  This makes for more
3181
 
efficiency if you call those functions several times, by avoiding
3182
 
reopening the database for each call.
3183
 
@end deftypefun
3184
 
 
3185
 
@comment netdb.h
3186
 
@comment BSD
3187
 
@deftypefun {struct netent *} getnetent (void)
3188
 
This function returns the next entry in the networks database.  It
3189
 
returns a null pointer if there are no more entries.
3190
 
@end deftypefun
3191
 
 
3192
 
@comment netdb.h
3193
 
@comment BSD
3194
 
@deftypefun void endnetent (void)
3195
 
This function closes the networks database.
3196
 
@end deftypefun