PageRenderTime 61ms CodeModel.GetById 16ms RepoModel.GetById 0ms app.codeStats 0ms

/Sources/selp_glibc-2.5.90-19.0.46/manual/socket.texi

https://bitbucket.org/Mali_Laurent/ps50c550
Unknown | 3196 lines | 2626 code | 570 blank | 0 comment | 0 complexity | 6717c0fed79090fee0ef8abd53cda7a7 MD5 | raw file
Possible License(s): GPL-2.0, LGPL-2.0, LGPL-2.1, AGPL-1.0, CC-BY-SA-3.0, BSD-3-Clause

Large files files are truncated, but you can click here to view the full file

  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. This chapter describes the GNU facilities for interprocess
  5. communication using sockets.
  6. @cindex socket
  7. @cindex interprocess communication, with sockets
  8. A @dfn{socket} is a generalized interprocess communication channel.
  9. Like a pipe, a socket is represented as a file descriptor. Unlike pipes
  10. sockets support communication between unrelated processes, and even
  11. between processes running on different machines that communicate over a
  12. network. Sockets are the primary means of communicating with other
  13. machines; @code{telnet}, @code{rlogin}, @code{ftp}, @code{talk} and the
  14. other familiar network programs use sockets.
  15. Not all operating systems support sockets. In the GNU library, the
  16. header file @file{sys/socket.h} exists regardless of the operating
  17. system, and the socket functions always exist, but if the system does
  18. not really support sockets these functions always fail.
  19. @strong{Incomplete:} We do not currently document the facilities for
  20. broadcast messages or for configuring Internet interfaces. The
  21. reentrant functions and some newer functions that are related to IPv6
  22. aren't documented either so far.
  23. @menu
  24. * Socket Concepts:: Basic concepts you need to know about.
  25. * Communication Styles::Stream communication, datagrams and other styles.
  26. * Socket Addresses:: How socket names (``addresses'') work.
  27. * Interface Naming:: Identifying specific network interfaces.
  28. * Local Namespace:: Details about the local namespace.
  29. * Internet Namespace:: Details about the Internet namespace.
  30. * Misc Namespaces:: Other namespaces not documented fully here.
  31. * Open/Close Sockets:: Creating sockets and destroying them.
  32. * Connections:: Operations on sockets with connection state.
  33. * Datagrams:: Operations on datagram sockets.
  34. * Inetd:: Inetd is a daemon that starts servers on request.
  35. The most convenient way to write a server
  36. is to make it work with Inetd.
  37. * Socket Options:: Miscellaneous low-level socket options.
  38. * Networks Database:: Accessing the database of network names.
  39. @end menu
  40. @node Socket Concepts
  41. @section Socket Concepts
  42. @cindex communication style (of a socket)
  43. @cindex style of communication (of a socket)
  44. When you create a socket, you must specify the style of communication
  45. you want to use and the type of protocol that should implement it.
  46. The @dfn{communication style} of a socket defines the user-level
  47. semantics of sending and receiving data on the socket. Choosing a
  48. communication style specifies the answers to questions such as these:
  49. @itemize @bullet
  50. @item
  51. @cindex packet
  52. @cindex byte stream
  53. @cindex stream (sockets)
  54. @strong{What are the units of data transmission?} Some communication
  55. styles regard the data as a sequence of bytes with no larger
  56. structure; others group the bytes into records (which are known in
  57. this context as @dfn{packets}).
  58. @item
  59. @cindex loss of data on sockets
  60. @cindex data loss on sockets
  61. @strong{Can data be lost during normal operation?} Some communication
  62. styles guarantee that all the data sent arrives in the order it was
  63. sent (barring system or network crashes); other styles occasionally
  64. lose data as a normal part of operation, and may sometimes deliver
  65. packets more than once or in the wrong order.
  66. Designing a program to use unreliable communication styles usually
  67. involves taking precautions to detect lost or misordered packets and
  68. to retransmit data as needed.
  69. @item
  70. @strong{Is communication entirely with one partner?} Some
  71. communication styles are like a telephone call---you make a
  72. @dfn{connection} with one remote socket and then exchange data
  73. freely. Other styles are like mailing letters---you specify a
  74. destination address for each message you send.
  75. @end itemize
  76. @cindex namespace (of socket)
  77. @cindex domain (of socket)
  78. @cindex socket namespace
  79. @cindex socket domain
  80. You must also choose a @dfn{namespace} for naming the socket. A socket
  81. name (``address'') is meaningful only in the context of a particular
  82. namespace. In fact, even the data type to use for a socket name may
  83. depend on the namespace. Namespaces are also called ``domains'', but we
  84. avoid that word as it can be confused with other usage of the same
  85. term. Each namespace has a symbolic name that starts with @samp{PF_}.
  86. A corresponding symbolic name starting with @samp{AF_} designates the
  87. address format for that namespace.
  88. @cindex network protocol
  89. @cindex protocol (of socket)
  90. @cindex socket protocol
  91. @cindex protocol family
  92. Finally you must choose the @dfn{protocol} to carry out the
  93. communication. The protocol determines what low-level mechanism is used
  94. to transmit and receive data. Each protocol is valid for a particular
  95. namespace and communication style; a namespace is sometimes called a
  96. @dfn{protocol family} because of this, which is why the namespace names
  97. start with @samp{PF_}.
  98. The rules of a protocol apply to the data passing between two programs,
  99. perhaps on different computers; most of these rules are handled by the
  100. operating system and you need not know about them. What you do need to
  101. know about protocols is this:
  102. @itemize @bullet
  103. @item
  104. In order to have communication between two sockets, they must specify
  105. the @emph{same} protocol.
  106. @item
  107. Each protocol is meaningful with particular style/namespace
  108. combinations and cannot be used with inappropriate combinations. For
  109. example, the TCP protocol fits only the byte stream style of
  110. communication and the Internet namespace.
  111. @item
  112. For each combination of style and namespace there is a @dfn{default
  113. protocol}, which you can request by specifying 0 as the protocol
  114. number. And that's what you should normally do---use the default.
  115. @end itemize
  116. Throughout the following description at various places
  117. variables/parameters to denote sizes are required. And here the trouble
  118. starts. In the first implementations the type of these variables was
  119. simply @code{int}. On most machines at that time an @code{int} was 32
  120. bits wide, which created a @emph{de facto} standard requiring 32-bit
  121. variables. This is important since references to variables of this type
  122. are passed to the kernel.
  123. Then the POSIX people came and unified the interface with the words "all
  124. size values are of type @code{size_t}". On 64-bit machines
  125. @code{size_t} is 64 bits wide, so pointers to variables were no longer
  126. possible.
  127. The Unix98 specification provides a solution by introducing a type
  128. @code{socklen_t}. This type is used in all of the cases that POSIX
  129. changed to use @code{size_t}. The only requirement of this type is that
  130. it be an unsigned type of at least 32 bits. Therefore, implementations
  131. which require that references to 32-bit variables be passed can be as
  132. happy as implementations which use 64-bit values.
  133. @node Communication Styles
  134. @section Communication Styles
  135. The GNU library includes support for several different kinds of sockets,
  136. each with different characteristics. This section describes the
  137. supported socket types. The symbolic constants listed here are
  138. defined in @file{sys/socket.h}.
  139. @pindex sys/socket.h
  140. @comment sys/socket.h
  141. @comment BSD
  142. @deftypevr Macro int SOCK_STREAM
  143. The @code{SOCK_STREAM} style is like a pipe (@pxref{Pipes and FIFOs}).
  144. It operates over a connection with a particular remote socket and
  145. transmits data reliably as a stream of bytes.
  146. Use of this style is covered in detail in @ref{Connections}.
  147. @end deftypevr
  148. @comment sys/socket.h
  149. @comment BSD
  150. @deftypevr Macro int SOCK_DGRAM
  151. The @code{SOCK_DGRAM} style is used for sending
  152. individually-addressed packets unreliably.
  153. It is the diametrical opposite of @code{SOCK_STREAM}.
  154. Each time you write data to a socket of this kind, that data becomes
  155. one packet. Since @code{SOCK_DGRAM} sockets do not have connections,
  156. you must specify the recipient address with each packet.
  157. The only guarantee that the system makes about your requests to
  158. transmit data is that it will try its best to deliver each packet you
  159. send. It may succeed with the sixth packet after failing with the
  160. fourth and fifth packets; the seventh packet may arrive before the
  161. sixth, and may arrive a second time after the sixth.
  162. The typical use for @code{SOCK_DGRAM} is in situations where it is
  163. acceptable to simply re-send a packet if no response is seen in a
  164. reasonable amount of time.
  165. @xref{Datagrams}, for detailed information about how to use datagram
  166. sockets.
  167. @end deftypevr
  168. @ignore
  169. @c This appears to be only for the NS domain, which we aren't
  170. @c discussing and probably won't support either.
  171. @comment sys/socket.h
  172. @comment BSD
  173. @deftypevr Macro int SOCK_SEQPACKET
  174. This style is like @code{SOCK_STREAM} except that the data are
  175. structured into packets.
  176. A program that receives data over a @code{SOCK_SEQPACKET} socket
  177. should be prepared to read the entire message packet in a single call
  178. to @code{read}; if it only reads part of the message, the remainder of
  179. the message is simply discarded instead of being available for
  180. subsequent calls to @code{read}.
  181. Many protocols do not support this communication style.
  182. @end deftypevr
  183. @end ignore
  184. @ignore
  185. @comment sys/socket.h
  186. @comment BSD
  187. @deftypevr Macro int SOCK_RDM
  188. This style is a reliable version of @code{SOCK_DGRAM}: it sends
  189. individually addressed packets, but guarantees that each packet sent
  190. arrives exactly once.
  191. @strong{Warning:} It is not clear this is actually supported
  192. by any operating system.
  193. @end deftypevr
  194. @end ignore
  195. @comment sys/socket.h
  196. @comment BSD
  197. @deftypevr Macro int SOCK_RAW
  198. This style provides access to low-level network protocols and
  199. interfaces. Ordinary user programs usually have no need to use this
  200. style.
  201. @end deftypevr
  202. @node Socket Addresses
  203. @section Socket Addresses
  204. @cindex address of socket
  205. @cindex name of socket
  206. @cindex binding a socket address
  207. @cindex socket address (name) binding
  208. The name of a socket is normally called an @dfn{address}. The
  209. functions and symbols for dealing with socket addresses were named
  210. inconsistently, sometimes using the term ``name'' and sometimes using
  211. ``address''. You can regard these terms as synonymous where sockets
  212. are concerned.
  213. A socket newly created with the @code{socket} function has no
  214. address. Other processes can find it for communication only if you
  215. give it an address. We call this @dfn{binding} the address to the
  216. socket, and the way to do it is with the @code{bind} function.
  217. You need be concerned with the address of a socket if other processes
  218. are to find it and start communicating with it. You can specify an
  219. address for other sockets, but this is usually pointless; the first time
  220. you send data from a socket, or use it to initiate a connection, the
  221. system assigns an address automatically if you have not specified one.
  222. Occasionally a client needs to specify an address because the server
  223. discriminates based on address; for example, the rsh and rlogin
  224. protocols look at the client's socket address and only bypass password
  225. checking if it is less than @code{IPPORT_RESERVED} (@pxref{Ports}).
  226. The details of socket addresses vary depending on what namespace you are
  227. using. @xref{Local Namespace}, or @ref{Internet Namespace}, for specific
  228. information.
  229. Regardless of the namespace, you use the same functions @code{bind} and
  230. @code{getsockname} to set and examine a socket's address. These
  231. functions use a phony data type, @code{struct sockaddr *}, to accept the
  232. address. In practice, the address lives in a structure of some other
  233. data type appropriate to the address format you are using, but you cast
  234. its address to @code{struct sockaddr *} when you pass it to
  235. @code{bind}.
  236. @menu
  237. * Address Formats:: About @code{struct sockaddr}.
  238. * Setting Address:: Binding an address to a socket.
  239. * Reading Address:: Reading the address of a socket.
  240. @end menu
  241. @node Address Formats
  242. @subsection Address Formats
  243. The functions @code{bind} and @code{getsockname} use the generic data
  244. type @code{struct sockaddr *} to represent a pointer to a socket
  245. address. You can't use this data type effectively to interpret an
  246. address or construct one; for that, you must use the proper data type
  247. for the socket's namespace.
  248. Thus, the usual practice is to construct an address of the proper
  249. namespace-specific type, then cast a pointer to @code{struct sockaddr *}
  250. when you call @code{bind} or @code{getsockname}.
  251. The one piece of information that you can get from the @code{struct
  252. sockaddr} data type is the @dfn{address format designator}. This tells
  253. you which data type to use to understand the address fully.
  254. @pindex sys/socket.h
  255. The symbols in this section are defined in the header file
  256. @file{sys/socket.h}.
  257. @comment sys/socket.h
  258. @comment BSD
  259. @deftp {Data Type} {struct sockaddr}
  260. The @code{struct sockaddr} type itself has the following members:
  261. @table @code
  262. @item short int sa_family
  263. This is the code for the address format of this address. It
  264. identifies the format of the data which follows.
  265. @item char sa_data[14]
  266. This is the actual socket address data, which is format-dependent. Its
  267. length also depends on the format, and may well be more than 14. The
  268. length 14 of @code{sa_data} is essentially arbitrary.
  269. @end table
  270. @end deftp
  271. Each address format has a symbolic name which starts with @samp{AF_}.
  272. Each of them corresponds to a @samp{PF_} symbol which designates the
  273. corresponding namespace. Here is a list of address format names:
  274. @table @code
  275. @comment sys/socket.h
  276. @comment POSIX
  277. @item AF_LOCAL
  278. @vindex AF_LOCAL
  279. This designates the address format that goes with the local namespace.
  280. (@code{PF_LOCAL} is the name of that namespace.) @xref{Local Namespace
  281. Details}, for information about this address format.
  282. @comment sys/socket.h
  283. @comment BSD, Unix98
  284. @item AF_UNIX
  285. @vindex AF_UNIX
  286. This is a synonym for @code{AF_LOCAL}. Although @code{AF_LOCAL} is
  287. mandated by POSIX.1g, @code{AF_UNIX} is portable to more systems.
  288. @code{AF_UNIX} was the traditional name stemming from BSD, so even most
  289. POSIX systems support it. It is also the name of choice in the Unix98
  290. specification. (The same is true for @code{PF_UNIX}
  291. vs. @code{PF_LOCAL}).
  292. @comment sys/socket.h
  293. @comment GNU
  294. @item AF_FILE
  295. @vindex AF_FILE
  296. This is another synonym for @code{AF_LOCAL}, for compatibility.
  297. (@code{PF_FILE} is likewise a synonym for @code{PF_LOCAL}.)
  298. @comment sys/socket.h
  299. @comment BSD
  300. @item AF_INET
  301. @vindex AF_INET
  302. This designates the address format that goes with the Internet
  303. namespace. (@code{PF_INET} is the name of that namespace.)
  304. @xref{Internet Address Formats}.
  305. @comment sys/socket.h
  306. @comment IPv6 Basic API
  307. @item AF_INET6
  308. This is similar to @code{AF_INET}, but refers to the IPv6 protocol.
  309. (@code{PF_INET6} is the name of the corresponding namespace.)
  310. @comment sys/socket.h
  311. @comment BSD
  312. @item AF_UNSPEC
  313. @vindex AF_UNSPEC
  314. This designates no particular address format. It is used only in rare
  315. cases, such as to clear out the default destination address of a
  316. ``connected'' datagram socket. @xref{Sending Datagrams}.
  317. The corresponding namespace designator symbol @code{PF_UNSPEC} exists
  318. for completeness, but there is no reason to use it in a program.
  319. @end table
  320. @file{sys/socket.h} defines symbols starting with @samp{AF_} for many
  321. different kinds of networks, most or all of which are not actually
  322. implemented. We will document those that really work as we receive
  323. information about how to use them.
  324. @node Setting Address
  325. @subsection Setting the Address of a Socket
  326. @pindex sys/socket.h
  327. Use the @code{bind} function to assign an address to a socket. The
  328. prototype for @code{bind} is in the header file @file{sys/socket.h}.
  329. For examples of use, see @ref{Local Socket Example}, or see @ref{Inet Example}.
  330. @comment sys/socket.h
  331. @comment BSD
  332. @deftypefun int bind (int @var{socket}, struct sockaddr *@var{addr}, socklen_t @var{length})
  333. The @code{bind} function assigns an address to the socket
  334. @var{socket}. The @var{addr} and @var{length} arguments specify the
  335. address; the detailed format of the address depends on the namespace.
  336. The first part of the address is always the format designator, which
  337. specifies a namespace, and says that the address is in the format of
  338. that namespace.
  339. The return value is @code{0} on success and @code{-1} on failure. The
  340. following @code{errno} error conditions are defined for this function:
  341. @table @code
  342. @item EBADF
  343. The @var{socket} argument is not a valid file descriptor.
  344. @item ENOTSOCK
  345. The descriptor @var{socket} is not a socket.
  346. @item EADDRNOTAVAIL
  347. The specified address is not available on this machine.
  348. @item EADDRINUSE
  349. Some other socket is already using the specified address.
  350. @item EINVAL
  351. The socket @var{socket} already has an address.
  352. @item EACCES
  353. You do not have permission to access the requested address. (In the
  354. Internet domain, only the super-user is allowed to specify a port number
  355. in the range 0 through @code{IPPORT_RESERVED} minus one; see
  356. @ref{Ports}.)
  357. @end table
  358. Additional conditions may be possible depending on the particular namespace
  359. of the socket.
  360. @end deftypefun
  361. @node Reading Address
  362. @subsection Reading the Address of a Socket
  363. @pindex sys/socket.h
  364. Use the function @code{getsockname} to examine the address of an
  365. Internet socket. The prototype for this function is in the header file
  366. @file{sys/socket.h}.
  367. @comment sys/socket.h
  368. @comment BSD
  369. @deftypefun int getsockname (int @var{socket}, struct sockaddr *@var{addr}, socklen_t *@var{length-ptr})
  370. The @code{getsockname} function returns information about the
  371. address of the socket @var{socket} in the locations specified by the
  372. @var{addr} and @var{length-ptr} arguments. Note that the
  373. @var{length-ptr} is a pointer; you should initialize it to be the
  374. allocation size of @var{addr}, and on return it contains the actual
  375. size of the address data.
  376. The format of the address data depends on the socket namespace. The
  377. length of the information is usually fixed for a given namespace, so
  378. normally you can know exactly how much space is needed and can provide
  379. that much. The usual practice is to allocate a place for the value
  380. using the proper data type for the socket's namespace, then cast its
  381. address to @code{struct sockaddr *} to pass it to @code{getsockname}.
  382. The return value is @code{0} on success and @code{-1} on error. The
  383. following @code{errno} error conditions are defined for this function:
  384. @table @code
  385. @item EBADF
  386. The @var{socket} argument is not a valid file descriptor.
  387. @item ENOTSOCK
  388. The descriptor @var{socket} is not a socket.
  389. @item ENOBUFS
  390. There are not enough internal buffers available for the operation.
  391. @end table
  392. @end deftypefun
  393. You can't read the address of a socket in the file namespace. This is
  394. consistent with the rest of the system; in general, there's no way to
  395. find a file's name from a descriptor for that file.
  396. @node Interface Naming
  397. @section Interface Naming
  398. Each network interface has a name. This usually consists of a few
  399. letters that relate to the type of interface, which may be followed by a
  400. number if there is more than one interface of that type. Examples
  401. might be @code{lo} (the loopback interface) and @code{eth0} (the first
  402. Ethernet interface).
  403. Although such names are convenient for humans, it would be clumsy to
  404. have to use them whenever a program needs to refer to an interface. In
  405. such situations an interface is referred to by its @dfn{index}, which is
  406. an arbitrarily-assigned small positive integer.
  407. The following functions, constants and data types are declared in the
  408. header file @file{net/if.h}.
  409. @comment net/if.h
  410. @deftypevr Constant size_t IFNAMSIZ
  411. This constant defines the maximum buffer size needed to hold an
  412. interface name, including its terminating zero byte.
  413. @end deftypevr
  414. @comment net/if.h
  415. @comment IPv6 basic API
  416. @deftypefun {unsigned int} if_nametoindex (const char *ifname)
  417. This function yields the interface index corresponding to a particular
  418. name. If no interface exists with the name given, it returns 0.
  419. @end deftypefun
  420. @comment net/if.h
  421. @comment IPv6 basic API
  422. @deftypefun {char *} if_indextoname (unsigned int ifindex, char *ifname)
  423. This function maps an interface index to its corresponding name. The
  424. returned name is placed in the buffer pointed to by @code{ifname}, which
  425. must be at least @code{IFNAMSIZ} bytes in length. If the index was
  426. invalid, the function's return value is a null pointer, otherwise it is
  427. @code{ifname}.
  428. @end deftypefun
  429. @comment net/if.h
  430. @comment IPv6 basic API
  431. @deftp {Data Type} {struct if_nameindex}
  432. This data type is used to hold the information about a single
  433. interface. It has the following members:
  434. @table @code
  435. @item unsigned int if_index;
  436. This is the interface index.
  437. @item char *if_name
  438. This is the null-terminated index name.
  439. @end table
  440. @end deftp
  441. @comment net/if.h
  442. @comment IPv6 basic API
  443. @deftypefun {struct if_nameindex *} if_nameindex (void)
  444. This function returns an array of @code{if_nameindex} structures, one
  445. for every interface that is present. The end of the list is indicated
  446. by a structure with an interface of 0 and a null name pointer. If an
  447. error occurs, this function returns a null pointer.
  448. The returned structure must be freed with @code{if_freenameindex} after
  449. use.
  450. @end deftypefun
  451. @comment net/if.h
  452. @comment IPv6 basic API
  453. @deftypefun void if_freenameindex (struct if_nameindex *ptr)
  454. This function frees the structure returned by an earlier call to
  455. @code{if_nameindex}.
  456. @end deftypefun
  457. @node Local Namespace
  458. @section The Local Namespace
  459. @cindex local namespace, for sockets
  460. This section describes the details of the local namespace, whose
  461. symbolic name (required when you create a socket) is @code{PF_LOCAL}.
  462. The local namespace is also known as ``Unix domain sockets''. Another
  463. name is file namespace since socket addresses are normally implemented
  464. as file names.
  465. @menu
  466. * Concepts: Local Namespace Concepts. What you need to understand.
  467. * Details: Local Namespace Details. Address format, symbolic names, etc.
  468. * Example: Local Socket Example. Example of creating a socket.
  469. @end menu
  470. @node Local Namespace Concepts
  471. @subsection Local Namespace Concepts
  472. In the local namespace socket addresses are file names. You can specify
  473. any file name you want as the address of the socket, but you must have
  474. write permission on the directory containing it.
  475. @c XXX The following was said to be wrong.
  476. @c In order to connect to a socket you must have read permission for it.
  477. It's common to put these files in the @file{/tmp} directory.
  478. One peculiarity of the local namespace is that the name is only used
  479. when opening the connection; once open the address is not meaningful and
  480. may not exist.
  481. Another peculiarity is that you cannot connect to such a socket from
  482. another machine--not even if the other machine shares the file system
  483. which contains the name of the socket. You can see the socket in a
  484. directory listing, but connecting to it never succeeds. Some programs
  485. take advantage of this, such as by asking the client to send its own
  486. process ID, and using the process IDs to distinguish between clients.
  487. However, we recommend you not use this method in protocols you design,
  488. as we might someday permit connections from other machines that mount
  489. the same file systems. Instead, send each new client an identifying
  490. number if you want it to have one.
  491. After you close a socket in the local namespace, you should delete the
  492. file name from the file system. Use @code{unlink} or @code{remove} to
  493. do this; see @ref{Deleting Files}.
  494. The local namespace supports just one protocol for any communication
  495. style; it is protocol number @code{0}.
  496. @node Local Namespace Details
  497. @subsection Details of Local Namespace
  498. @pindex sys/socket.h
  499. To create a socket in the local namespace, use the constant
  500. @code{PF_LOCAL} as the @var{namespace} argument to @code{socket} or
  501. @code{socketpair}. This constant is defined in @file{sys/socket.h}.
  502. @comment sys/socket.h
  503. @comment POSIX
  504. @deftypevr Macro int PF_LOCAL
  505. This designates the local namespace, in which socket addresses are local
  506. names, and its associated family of protocols. @code{PF_Local} is the
  507. macro used by Posix.1g.
  508. @end deftypevr
  509. @comment sys/socket.h
  510. @comment BSD
  511. @deftypevr Macro int PF_UNIX
  512. This is a synonym for @code{PF_LOCAL}, for compatibility's sake.
  513. @end deftypevr
  514. @comment sys/socket.h
  515. @comment GNU
  516. @deftypevr Macro int PF_FILE
  517. This is a synonym for @code{PF_LOCAL}, for compatibility's sake.
  518. @end deftypevr
  519. The structure for specifying socket names in the local namespace is
  520. defined in the header file @file{sys/un.h}:
  521. @pindex sys/un.h
  522. @comment sys/un.h
  523. @comment BSD
  524. @deftp {Data Type} {struct sockaddr_un}
  525. This structure is used to specify local namespace socket addresses. It has
  526. the following members:
  527. @table @code
  528. @item short int sun_family
  529. This identifies the address family or format of the socket address.
  530. You should store the value @code{AF_LOCAL} to designate the local
  531. namespace. @xref{Socket Addresses}.
  532. @item char sun_path[108]
  533. This is the file name to use.
  534. @strong{Incomplete:} Why is 108 a magic number? RMS suggests making
  535. this a zero-length array and tweaking the following example to use
  536. @code{alloca} to allocate an appropriate amount of storage based on
  537. the length of the filename.
  538. @end table
  539. @end deftp
  540. You should compute the @var{length} parameter for a socket address in
  541. the local namespace as the sum of the size of the @code{sun_family}
  542. component and the string length (@emph{not} the allocation size!) of
  543. the file name string. This can be done using the macro @code{SUN_LEN}:
  544. @comment sys/un.h
  545. @comment BSD
  546. @deftypefn {Macro} int SUN_LEN (@emph{struct sockaddr_un *} @var{ptr})
  547. The macro computes the length of socket address in the local namespace.
  548. @end deftypefn
  549. @node Local Socket Example
  550. @subsection Example of Local-Namespace Sockets
  551. Here is an example showing how to create and name a socket in the local
  552. namespace.
  553. @smallexample
  554. @include mkfsock.c.texi
  555. @end smallexample
  556. @node Internet Namespace
  557. @section The Internet Namespace
  558. @cindex Internet namespace, for sockets
  559. This section describes the details of the protocols and socket naming
  560. conventions used in the Internet namespace.
  561. Originally the Internet namespace used only IP version 4 (IPv4). With
  562. the growing number of hosts on the Internet, a new protocol with a
  563. larger address space was necessary: IP version 6 (IPv6). IPv6
  564. introduces 128-bit addresses (IPv4 has 32-bit addresses) and other
  565. features, and will eventually replace IPv4.
  566. To create a socket in the IPv4 Internet namespace, use the symbolic name
  567. @code{PF_INET} of this namespace as the @var{namespace} argument to
  568. @code{socket} or @code{socketpair}. For IPv6 addresses you need the
  569. macro @code{PF_INET6}. These macros are defined in @file{sys/socket.h}.
  570. @pindex sys/socket.h
  571. @comment sys/socket.h
  572. @comment BSD
  573. @deftypevr Macro int PF_INET
  574. This designates the IPv4 Internet namespace and associated family of
  575. protocols.
  576. @end deftypevr
  577. @comment sys/socket.h
  578. @comment X/Open
  579. @deftypevr Macro int PF_INET6
  580. This designates the IPv6 Internet namespace and associated family of
  581. protocols.
  582. @end deftypevr
  583. A socket address for the Internet namespace includes the following components:
  584. @itemize @bullet
  585. @item
  586. The address of the machine you want to connect to. Internet addresses
  587. can be specified in several ways; these are discussed in @ref{Internet
  588. Address Formats}, @ref{Host Addresses} and @ref{Host Names}.
  589. @item
  590. A port number for that machine. @xref{Ports}.
  591. @end itemize
  592. You must ensure that the address and port number are represented in a
  593. canonical format called @dfn{network byte order}. @xref{Byte Order},
  594. for information about this.
  595. @menu
  596. * Internet Address Formats:: How socket addresses are specified in the
  597. Internet namespace.
  598. * Host Addresses:: All about host addresses of Internet host.
  599. * Protocols Database:: Referring to protocols by name.
  600. * Ports:: Internet port numbers.
  601. * Services Database:: Ports may have symbolic names.
  602. * Byte Order:: Different hosts may use different byte
  603. ordering conventions; you need to
  604. canonicalize host address and port number.
  605. * Inet Example:: Putting it all together.
  606. @end menu
  607. @node Internet Address Formats
  608. @subsection Internet Socket Address Formats
  609. In the Internet namespace, for both IPv4 (@code{AF_INET}) and IPv6
  610. (@code{AF_INET6}), a socket address consists of a host address
  611. and a port on that host. In addition, the protocol you choose serves
  612. effectively as a part of the address because local port numbers are
  613. meaningful only within a particular protocol.
  614. The data types for representing socket addresses in the Internet namespace
  615. are defined in the header file @file{netinet/in.h}.
  616. @pindex netinet/in.h
  617. @comment netinet/in.h
  618. @comment BSD
  619. @deftp {Data Type} {struct sockaddr_in}
  620. This is the data type used to represent socket addresses in the
  621. Internet namespace. It has the following members:
  622. @table @code
  623. @item sa_family_t sin_family
  624. This identifies the address family or format of the socket address.
  625. You should store the value @code{AF_INET} in this member.
  626. @xref{Socket Addresses}.
  627. @item struct in_addr sin_addr
  628. This is the Internet address of the host machine. @xref{Host
  629. Addresses}, and @ref{Host Names}, for how to get a value to store
  630. here.
  631. @item unsigned short int sin_port
  632. This is the port number. @xref{Ports}.
  633. @end table
  634. @end deftp
  635. When you call @code{bind} or @code{getsockname}, you should specify
  636. @code{sizeof (struct sockaddr_in)} as the @var{length} parameter if
  637. you are using an IPv4 Internet namespace socket address.
  638. @deftp {Data Type} {struct sockaddr_in6}
  639. This is the data type used to represent socket addresses in the IPv6
  640. namespace. It has the following members:
  641. @table @code
  642. @item sa_family_t sin6_family
  643. This identifies the address family or format of the socket address.
  644. You should store the value of @code{AF_INET6} in this member.
  645. @xref{Socket Addresses}.
  646. @item struct in6_addr sin6_addr
  647. This is the IPv6 address of the host machine. @xref{Host
  648. Addresses}, and @ref{Host Names}, for how to get a value to store
  649. here.
  650. @item uint32_t sin6_flowinfo
  651. This is a currently unimplemented field.
  652. @item uint16_t sin6_port
  653. This is the port number. @xref{Ports}.
  654. @end table
  655. @end deftp
  656. @node Host Addresses
  657. @subsection Host Addresses
  658. Each computer on the Internet has one or more @dfn{Internet addresses},
  659. numbers which identify that computer among all those on the Internet.
  660. Users typically write IPv4 numeric host addresses as sequences of four
  661. numbers, separated by periods, as in @samp{128.52.46.32}, and IPv6
  662. numeric host addresses as sequences of up to eight numbers separated by
  663. colons, as in @samp{5f03:1200:836f:c100::1}.
  664. Each computer also has one or more @dfn{host names}, which are strings
  665. of words separated by periods, as in @samp{mescaline.gnu.org}.
  666. Programs that let the user specify a host typically accept both numeric
  667. addresses and host names. To open a connection a program needs a
  668. numeric address, and so must convert a host name to the numeric address
  669. it stands for.
  670. @menu
  671. * Abstract Host Addresses:: What a host number consists of.
  672. * Data type: Host Address Data Type. Data type for a host number.
  673. * Functions: Host Address Functions. Functions to operate on them.
  674. * Names: Host Names. Translating host names to host numbers.
  675. @end menu
  676. @node Abstract Host Addresses
  677. @subsubsection Internet Host Addresses
  678. @cindex host address, Internet
  679. @cindex Internet host address
  680. @ifinfo
  681. Each computer on the Internet has one or more Internet addresses,
  682. numbers which identify that computer among all those on the Internet.
  683. @end ifinfo
  684. @cindex network number
  685. @cindex local network address number
  686. An IPv4 Internet host address is a number containing four bytes of data.
  687. Historically these are divided into two parts, a @dfn{network number} and a
  688. @dfn{local network address number} within that network. In the
  689. mid-1990s classless addresses were introduced which changed this
  690. behavior. Since some functions implicitly expect the old definitions,
  691. we first describe the class-based network and will then describe
  692. classless addresses. IPv6 uses only classless addresses and therefore
  693. the following paragraphs don't apply.
  694. The class-based IPv4 network number consists of the first one, two or
  695. three bytes; the rest of the bytes are the local address.
  696. IPv4 network numbers are registered with the Network Information Center
  697. (NIC), and are divided into three classes---A, B and C. The local
  698. network address numbers of individual machines are registered with the
  699. administrator of the particular network.
  700. Class A networks have single-byte numbers in the range 0 to 127. There
  701. are only a small number of Class A networks, but they can each support a
  702. very large number of hosts. Medium-sized Class B networks have two-byte
  703. network numbers, with the first byte in the range 128 to 191. Class C
  704. networks are the smallest; they have three-byte network numbers, with
  705. the first byte in the range 192-255. Thus, the first 1, 2, or 3 bytes
  706. of an Internet address specify a network. The remaining bytes of the
  707. Internet address specify the address within that network.
  708. The Class A network 0 is reserved for broadcast to all networks. In
  709. addition, the host number 0 within each network is reserved for broadcast
  710. to all hosts in that network. These uses are obsolete now but for
  711. compatibility reasons you shouldn't use network 0 and host number 0.
  712. The Class A network 127 is reserved for loopback; you can always use
  713. the Internet address @samp{127.0.0.1} to refer to the host machine.
  714. Since a single machine can be a member of multiple networks, it can
  715. have multiple Internet host addresses. However, there is never
  716. supposed to be more than one machine with the same host address.
  717. @c !!! this section could document the IN_CLASS* macros in <netinet/in.h>.
  718. @c No, it shouldn't since they're obsolete.
  719. @cindex standard dot notation, for Internet addresses
  720. @cindex dot notation, for Internet addresses
  721. There are four forms of the @dfn{standard numbers-and-dots notation}
  722. for Internet addresses:
  723. @table @code
  724. @item @var{a}.@var{b}.@var{c}.@var{d}
  725. This specifies all four bytes of the address individually and is the
  726. commonly used representation.
  727. @item @var{a}.@var{b}.@var{c}
  728. The last part of the address, @var{c}, is interpreted as a 2-byte quantity.
  729. This is useful for specifying host addresses in a Class B network with
  730. network address number @code{@var{a}.@var{b}}.
  731. @item @var{a}.@var{b}
  732. The last part of the address, @var{b}, is interpreted as a 3-byte quantity.
  733. This is useful for specifying host addresses in a Class A network with
  734. network address number @var{a}.
  735. @item @var{a}
  736. If only one part is given, this corresponds directly to the host address
  737. number.
  738. @end table
  739. Within each part of the address, the usual C conventions for specifying
  740. the radix apply. In other words, a leading @samp{0x} or @samp{0X} implies
  741. hexadecimal radix; a leading @samp{0} implies octal; and otherwise decimal
  742. radix is assumed.
  743. @subsubheading Classless Addresses
  744. IPv4 addresses (and IPv6 addresses also) are now considered classless;
  745. the distinction between classes A, B and C can be ignored. Instead an
  746. IPv4 host address consists of a 32-bit address and a 32-bit mask. The
  747. mask contains set bits for the network part and cleared bits for the
  748. host part. The network part is contiguous from the left, with the
  749. remaining bits representing the host. As a consequence, the netmask can
  750. simply be specified as the number of set bits. Classes A, B and C are
  751. just special cases of this general rule. For example, class A addresses
  752. have a netmask of @samp{255.0.0.0} or a prefix length of 8.
  753. Classless IPv4 network addresses are written in numbers-and-dots
  754. notation with the prefix length appended and a slash as separator. For
  755. example the class A network 10 is written as @samp{10.0.0.0/8}.
  756. @subsubheading IPv6 Addresses
  757. IPv6 addresses contain 128 bits (IPv4 has 32 bits) of data. A host
  758. address is usually written as eight 16-bit hexadecimal numbers that are
  759. separated by colons. Two colons are used to abbreviate strings of
  760. consecutive zeros. For example, the IPv6 loopback address
  761. @samp{0:0:0:0:0:0:0:1} can just be written as @samp{::1}.
  762. @node Host Address Data Type
  763. @subsubsection Host Address Data Type
  764. IPv4 Internet host addresses are represented in some contexts as integers
  765. (type @code{uint32_t}). In other contexts, the integer is
  766. packaged inside a structure of type @code{struct in_addr}. It would
  767. be better if the usage were made consistent, but it is not hard to extract
  768. the integer from the structure or put the integer into a structure.
  769. You will find older code that uses @code{unsigned long int} for
  770. IPv4 Internet host addresses instead of @code{uint32_t} or @code{struct
  771. in_addr}. Historically @code{unsigned long int} was a 32-bit number but
  772. with 64-bit machines this has changed. Using @code{unsigned long int}
  773. might break the code if it is used on machines where this type doesn't
  774. have 32 bits. @code{uint32_t} is specified by Unix98 and guaranteed to have
  775. 32 bits.
  776. IPv6 Internet host addresses have 128 bits and are packaged inside a
  777. structure of type @code{struct in6_addr}.
  778. The following basic definitions for Internet addresses are declared in
  779. the header file @file{netinet/in.h}:
  780. @pindex netinet/in.h
  781. @comment netinet/in.h
  782. @comment BSD
  783. @deftp {Data Type} {struct in_addr}
  784. This data type is used in certain contexts to contain an IPv4 Internet
  785. host address. It has just one field, named @code{s_addr}, which records
  786. the host address number as an @code{uint32_t}.
  787. @end deftp
  788. @comment netinet/in.h
  789. @comment BSD
  790. @deftypevr Macro {uint32_t} INADDR_LOOPBACK
  791. You can use this constant to stand for ``the address of this machine,''
  792. instead of finding its actual address. It is the IPv4 Internet address
  793. @samp{127.0.0.1}, which is usually called @samp{localhost}. This
  794. special constant saves you the trouble of looking up the address of your
  795. own machine. Also, the system usually implements @code{INADDR_LOOPBACK}
  796. specially, avoiding any network traffic for the case of one machine
  797. talking to itself.
  798. @end deftypevr
  799. @comment netinet/in.h
  800. @comment BSD
  801. @deftypevr Macro {uint32_t} INADDR_ANY
  802. You can use this constant to stand for ``any incoming address'' when
  803. binding to an address. @xref{Setting Address}. This is the usual
  804. address to give in the @code{sin_addr} member of @w{@code{struct
  805. sockaddr_in}} when you want to accept Internet connections.
  806. @end deftypevr
  807. @comment netinet/in.h
  808. @comment BSD
  809. @deftypevr Macro {uint32_t} INADDR_BROADCAST
  810. This constant is the address you use to send a broadcast message.
  811. @c !!! broadcast needs further documented
  812. @end deftypevr
  813. @comment netinet/in.h
  814. @comment BSD
  815. @deftypevr Macro {uint32_t} INADDR_NONE
  816. This constant is returned by some functions to indicate an error.
  817. @end deftypevr
  818. @comment netinet/in.h
  819. @comment IPv6 basic API
  820. @deftp {Data Type} {struct in6_addr}
  821. This data type is used to store an IPv6 address. It stores 128 bits of
  822. data, which can be accessed (via a union) in a variety of ways.
  823. @end deftp
  824. @comment netinet/in.h
  825. @comment IPv6 basic API
  826. @deftypevr Constant {struct in6_addr} in6addr_loopback
  827. This constant is the IPv6 address @samp{::1}, the loopback address. See
  828. above for a description of what this means. The macro
  829. @code{IN6ADDR_LOOPBACK_INIT} is provided to allow you to initialize your
  830. own variables to this value.
  831. @end deftypevr
  832. @comment netinet/in.h
  833. @comment IPv6 basic API
  834. @deftypevr Constant {struct in6_addr} in6addr_any
  835. This constant is the IPv6 address @samp{::}, the unspecified address. See
  836. above for a description of what this means. The macro
  837. @code{IN6ADDR_ANY_INIT} is provided to allow you to initialize your
  838. own variables to this value.
  839. @end deftypevr
  840. @node Host Address Functions
  841. @subsubsection Host Address Functions
  842. @pindex arpa/inet.h
  843. @noindent
  844. These additional functions for manipulating Internet addresses are
  845. declared in the header file @file{arpa/inet.h}. They represent Internet
  846. addresses in network byte order, and network numbers and
  847. local-address-within-network numbers in host byte order. @xref{Byte
  848. Order}, for an explanation of network and host byte order.
  849. @comment arpa/inet.h
  850. @comment BSD
  851. @deftypefun int inet_aton (const char *@var{name}, struct in_addr *@var{addr})
  852. This function converts the IPv4 Internet host address @var{name}
  853. from the standard numbers-and-dots notation into binary data and stores
  854. it in the @code{struct in_addr} that @var{addr} points to.
  855. @code{inet_aton} returns nonzero if the address is valid, zero if not.
  856. @end deftypefun
  857. @comment arpa/inet.h
  858. @comment BSD
  859. @deftypefun {uint32_t} inet_addr (const char *@var{name})
  860. This function converts the IPv4 Internet host address @var{name} from the
  861. standard numbers-and-dots notation into binary data. If the input is
  862. not valid, @code{inet_addr} returns @code{INADDR_NONE}. This is an
  863. obsolete interface to @code{inet_aton}, described immediately above. It
  864. is obsolete because @code{INADDR_NONE} is a valid address
  865. (255.255.255.255), and @code{inet_aton} provides a cleaner way to
  866. indicate error return.
  867. @end deftypefun
  868. @comment arpa/inet.h
  869. @comment BSD
  870. @deftypefun {uint32_t} inet_network (const char *@var{name})
  871. This function extracts the network number from the address @var{name},
  872. given in the standard numbers-and-dots notation. The returned address is
  873. in host order. If the input is not valid, @code{inet_network} returns
  874. @code{-1}.
  875. The function works only with traditional IPv4 class A, B and C network
  876. types. It doesn't work with classless addresses and shouldn't be used
  877. anymore.
  878. @end deftypefun
  879. @comment arpa/inet.h
  880. @comment BSD
  881. @deftypefun {char *} inet_ntoa (struct in_addr @var{addr})
  882. This function converts the IPv4 Internet host address @var{addr} to a
  883. string in the standard numbers-and-dots notation. The return value is
  884. a pointer into a statically-allocated buffer. Subsequent calls will
  885. overwrite the same buffer, so you should copy the string if you need
  886. to save it.
  887. In multi-threaded programs each thread has an own statically-allocated
  888. buffer. But still subsequent calls of @code{inet_ntoa} in the same
  889. thread will overwrite the result of the last call.
  890. Instead of @code{inet_ntoa} the newer function @code{inet_ntop} which is
  891. described below should be used since it handles both IPv4 and IPv6
  892. addresses.
  893. @end deftypefun
  894. @comment arpa/inet.h
  895. @comment BSD
  896. @deftypefun {struct in_addr} inet_makeaddr (uint32_t @var{net}, uint32_t @var{local})
  897. This function makes an IPv4 Internet host address by combining the network
  898. number @var{net} with the local-address-within-network number
  899. @var{local}.
  900. @end deftypefun
  901. @comment arpa/inet.h
  902. @comment BSD
  903. @deftypefun uint32_t inet_lnaof (struct in_addr @var{addr})
  904. This function returns the local-address-within-network part of the
  905. Internet host address @var{addr}.
  906. The function works only with traditional IPv4 class A, B and C network
  907. types. It doesn't work with classless addresses and shouldn't be used
  908. anymore.
  909. @end deftypefun
  910. @comment arpa/inet.h
  911. @comment BSD
  912. @deftypefun uint32_t inet_netof (struct in_addr @var{addr})
  913. This function returns the network number part of the Internet host
  914. address @var{addr}.
  915. The function works only with traditional IPv4 class A, B and C network
  916. types. It doesn't work with classless addresses and shouldn't be used
  917. anymore.
  918. @end deftypefun
  919. @comment arpa/inet.h
  920. @comment IPv6 basic API
  921. @deftypefun int inet_pton (int @var{af}, const char *@var{cp}, void *@var{buf})
  922. This function converts an Internet address (either IPv4 or IPv6) from
  923. presentation (textual) to network (binary) format. @var{af} should be
  924. either @code{AF_INET} or @code{AF_INET6}, as appropriate for the type of
  925. address being converted. @var{cp} is a pointer to the input string, and
  926. @var{buf} is a pointer to a buffer for the result. It is the caller's
  927. responsibility to make sure the buffer is large enough.
  928. @end deftypefun
  929. @comment arpa/inet.h
  930. @comment IPv6 basic API
  931. @deftypefun {const char *} inet_ntop (int @var{af}, const void *@var{cp}, char *@var{buf}, size_t @var{len})
  932. This function converts an Internet address (either IPv4 or IPv6) from
  933. network (binary) to presentation (textual) form. @var{af} should be
  934. either @code{AF_INET} or @code{AF_INET6}, as appropriate. @var{cp} is a
  935. pointer to the address to be converted. @var{buf} should be a pointer
  936. to a buffer to hold the result, and @var{len} is the length of this
  937. buffer. The return value from the function will be this buffer address.
  938. @end deftypefun
  939. @node Host Names
  940. @subsubsection Host Names
  941. @cindex hosts database
  942. @cindex converting host name to address
  943. @cindex converting host address to name
  944. Besides the standard numbers-and-dots notation for Internet addresses,
  945. you can also refer to a host by a symbolic name. The advantage of a
  946. symbolic name is that it is usually easier to remember. For example,
  947. the machine with Internet address @samp{158.121.106.19} is also known as
  948. @samp{alpha.gnu.org}; and other machines in the @samp{gnu.org}
  949. domain can refer to it simply as @samp{alpha}.
  950. @pindex /etc/hosts
  951. @pindex netdb.h
  952. Internally, the system uses a database to keep track of the mapping
  953. between host names and host numbers. This database is usually either
  954. the file @file{/etc/hosts} or an equivalent provided by a name server.
  955. The functions and other symbols for accessing this database are declared
  956. in @file{netdb.h}. They are BSD features, defined unconditionally if
  957. you include @file{netdb.h}.
  958. @comment netdb.h
  959. @comment BSD
  960. @deftp {Data Type} {struct hostent}
  961. This data type is used to represent an entry in the hosts database. It
  962. has the following members:
  963. @table @code
  964. @item char *h_name
  965. This is the ``official'' name of the host.
  966. @item char **h_aliases
  967. These are alternative names for the host, represented as a null-terminated
  968. vector of strings.
  969. @item int h_addrtype
  970. This is the host address type; in practice, its value is always either
  971. @code{AF_INET} or @code{AF_INET6}, with the latter being used for IPv6
  972. hosts. In principle other kinds of addresses could be represented in
  973. the database as well as Internet addresses; if this were done, you
  974. might find a value in this field other than @code{AF_INET} or
  975. @code{AF_INET6}. @xref{Socket Addresses}.
  976. @item int h_length
  977. This is the length, in bytes, of each address.
  978. @item char **h_addr_list
  979. This is the vector of addresses for the host. (Recall that the host
  980. might be connected to multiple networks and have different addresses on
  981. each one.) The vector is terminated by a null pointer.
  982. @item char *h_addr
  983. This is a synonym for @code{h_addr_list[0]}; in other words, it is the
  984. first host address.
  985. @end table
  986. @end deftp
  987. As far as the host database is concerned, each address is just a block
  988. of memory @code{h_length} bytes long. But in other contexts there is an
  989. implicit assumption that you can convert IPv4 addresses to a
  990. @code{struct in_addr} or an @code{uint32_t}. Host addresses in
  991. a @code{struct hostent} structure are always given in network byte
  992. order; see @ref{Byte Order}.
  993. You can use @code{gethostbyname}, @code{gethostbyname2} or
  994. @code{gethostbyaddr} to search the hosts database for information about
  995. a particular host. The information is returned in a
  996. statically-allocated structure; you must copy the information if you
  997. need to save it across calls. You can also use @code{getaddrinfo} and
  998. @code{getnameinfo} to obtain this information.
  999. @comment netdb.h
  1000. @comment BSD
  1001. @deftypefun {struct hostent *} gethostbyname (const char *@var{name})
  1002. The @code{gethostbyname} function returns information about the host
  1003. named @var{name}. If the lookup fails, it returns a null pointer.
  1004. @end deftypefun
  1005. @comment netdb.h
  1006. @comment IPv6 Basic API
  1007. @deftypefun {struct hostent *} gethostbyname2 (const char *@var{name}, int @var{af})
  1008. The @code{gethostbyname2} function is like @code{gethostbyname}, but
  1009. allows the caller to specify the desired address family (e.g.@:
  1010. @code{AF_INET} or @code{AF_INET6}) of the result.
  1011. @end deftypefun
  1012. @comment netdb.h
  1013. @comment BSD
  1014. @deftypefun {struct hostent *} gethostbyaddr (const char *@var{addr}, size_t @var{length}, int @var{format})
  1015. The @code{gethostbyaddr} function returns information about the host
  1016. with Internet address @var{addr}. The parameter @var{addr} is not
  1017. really a pointer to char - it can be a pointer to an IPv4 or an IPv6
  1018. address. The @var{length} argument is the size (in bytes) of the address
  1019. at @var{addr}. @var{format} specifies the address format; for an IPv4
  1020. Internet address, specify a value of @code{AF_INET}; for an IPv6
  1021. Internet address, use @code{AF_INET6}.
  1022. If the lookup fails, @code{gethostbyaddr} returns a null pointer.
  1023. @end deftypefun
  1024. @vindex h_errno
  1025. If the name lookup by @code{gethostbyname} or @code{gethostbyaddr}
  1026. fails, you can find out the reason by looking at the value of the
  1027. variable @code{h_errno}. (It would be cleaner design for these
  1028. functions to set @code{errno}, but use of @code{h_errno} is compatible
  1029. with other systems.)
  1030. Here are the error codes that you may find in @code{h_errno}:
  1031. @table @code
  1032. @comment netdb.h
  1033. @comment BSD
  1034. @item HOST_NOT_FOUND
  1035. @vindex HOST_NOT_FOUND
  1036. No such host is known in the database.
  1037. @comment netdb.h
  1038. @comment BSD
  1039. @item TRY_AGAIN
  1040. @vindex TRY_AGAIN
  1041. This condition happens when the name server could not be contacted. If
  1042. you try again later, you may succeed then.
  1043. @comment netdb.h
  1044. @comment BSD
  1045. @item NO_RECOVERY
  1046. @vindex NO_RECOVERY
  1047. A non-recoverable error occurred.
  1048. @comment netdb.h
  1049. @comment BSD
  1050. @item NO_ADDRESS
  1051. @vindex NO_ADDRESS
  1052. The host database contains an entry for the name, but it doesn't have an
  1053. associated Internet address.
  1054. @end table
  1055. The lookup functions above all have one in common: they are not
  1056. reentrant and therefore unusable in multi-threaded applications.
  1057. Therefore provides the GNU C library a new set of functions which can be
  1058. used in this context.
  1059. @comment netdb.h
  1060. @comment GNU
  1061. @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})
  1062. The @code{gethos

Large files files are truncated, but you can click here to view the full file