resolv/netdb.h

   1 /* Copyright (C) 1996,1997,1998,1999,2000,2001 Free Software Foundation, Inc.
   2    This file is part of the GNU C Library.
   3
   4    The GNU C Library is free software; you can redistribute it and/or
   5    modify it under the terms of the GNU Lesser General Public
   6    License as published by the Free Software Foundation; either
   7    version 2.1 of the License, or (at your option) any later version.
   8
   9    The GNU C Library is distributed in the hope that it will be useful,
  10    but WITHOUT ANY WARRANTY; without even the implied warranty of
  11    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12    Lesser General Public License for more details.
  13
  14    You should have received a copy of the GNU Lesser General Public
  15    License along with the GNU C Library; if not, write to the Free
  16    Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  17    02111-1307 USA.  */
  18
  19 /* All data returned by the network data base library are supplied in
  20    host order and returned in network order (suitable for use in
  21    system calls).  */
  22
  23 #ifndef _NETDB_H
  24 #define _NETDB_H        1
  25
  26 #include <features.h>
  27
  28 #include <netinet/in.h>
  29 #include <stdint.h>
  30 #ifdef __USE_MISC
  31 /* This is necessary to make this include file properly replace the
  32    Sun version.  */
  33 # include <rpc/netdb.h>
  34 #endif
  35
  36 #ifdef __USE_GNU
  37 # define __need_sigevent_t
  38 # include <bits/siginfo.h>
  39 # define __need_timespec
  40 # include <time.h>
  41 #endif
  42
  43 #include <bits/netdb.h>
  44
  45 /* Absolute file name for network data base files.  */
  46 #define _PATH_HEQUIV            "/etc/hosts.equiv"
  47 #define _PATH_HOSTS             "/etc/hosts"
  48 #define _PATH_NETWORKS          "/etc/networks"
  49 #define _PATH_NSSWITCH_CONF     "/etc/nsswitch.conf"
  50 #define _PATH_PROTOCOLS         "/etc/protocols"
  51 #define _PATH_SERVICES          "/etc/services"
  52
  53
  54 __BEGIN_DECLS
  55
  56 /* Error status for non-reentrant lookup functions.  */
  57 extern int h_errno;
  58
  59 /* Function to get address of global `h_errno' variable.  */
  60 extern int *__h_errno_location (void) __THROW __attribute__ ((__const__));
  61
  62 #ifdef _LIBC
  63 # ifdef _LIBC_REENTRANT
  64 static inline int
  65 __set_h_errno (int __err)
  66 {
  67   return *__h_errno_location () = __err;
  68 }
  69 # else
  70 #  define __set_h_errno(x) (h_errno = (x))
  71 # endif /* _LIBC_REENTRANT */
  72 #endif /* _LIBC */
  73
  74
  75 #if !defined _LIBC || defined _LIBC_REENTRANT
  76 /* Use a macro to access always the thread specific `h_errno' variable.  */
  77 # define h_errno (*__h_errno_location ())
  78 #endif
  79
  80
  81 /* Possible values left in `h_errno'.  */
  82 #define NETDB_INTERNAL  -1      /* See errno.  */
  83 #define NETDB_SUCCESS   0       /* No problem.  */
  84 #define HOST_NOT_FOUND  1       /* Authoritative Answer Host not found.  */
  85 #define TRY_AGAIN       2       /* Non-Authoritative Host not found,
  86                                    or SERVERFAIL.  */
  87 #define NO_RECOVERY     3       /* Non recoverable errors, FORMERR, REFUSED,
  88                                    NOTIMP.  */
  89 #define NO_DATA         4       /* Valid name, no data record of requested
  90                                    type.  */
  91 #define NO_ADDRESS      NO_DATA /* No address, look for MX record.  */
  92
  93 #ifdef __USE_XOPEN2K
  94 /* Highest reserved Internet port number.  */
  95 # define IPPORT_RESERVED        1024
  96 #endif
  97
  98 #ifdef __USE_GNU
  99 /* Scope delimiter for getaddrinfo(), getnameinfo().  */
 100 # define SCOPE_DELIMITER        '%'
 101 #endif
 102
 103 /* Print error indicated by `h_errno' variable on standard error.  STR
 104    if non-null is printed before the error string.  */
 105 extern void herror (__const char *__str) __THROW;
 106
 107 /* Return string associated with error ERR_NUM.  */
 108 extern __const char *hstrerror (int __err_num) __THROW;
 109
 110
 111
 112 /* Description of data base entry for a single host.  */
 113 struct hostent
 114 {
 115   char *h_name;                 /* Official name of host.  */
 116   char **h_aliases;             /* Alias list.  */
 117   int h_addrtype;               /* Host address type.  */
 118   int h_length;                 /* Length of address.  */
 119   char **h_addr_list;           /* List of addresses from name server.  */
 120 #define h_addr  h_addr_list[0]  /* Address, for backward compatibility.  */
 121 };
 122
 123 /* Open host data base files and mark them as staying open even after
 124    a later search if STAY_OPEN is non-zero.  */
 125 extern void sethostent (int __stay_open) __THROW;
 126
 127 /* Close host data base files and clear `stay open' flag.  */
 128 extern void endhostent (void) __THROW;
 129
 130 /* Get next entry from host data base file.  Open data base if
 131    necessary.  */
 132 extern struct hostent *gethostent (void) __THROW;
 133
 134 /* Return entry from host data base which address match ADDR with
 135    length LEN and type TYPE.  */
 136 extern struct hostent *gethostbyaddr (__const void *__addr, __socklen_t __len,
 137                                       int __type) __THROW;
 138
 139 /* Return entry from host data base for host with NAME.  */
 140 extern struct hostent *gethostbyname (__const char *__name) __THROW;
 141
 142 #ifdef __USE_MISC
 143 /* Return entry from host data base for host with NAME.  AF must be
 144    set to the address type which is `AF_INET' for IPv4 or `AF_INET6'
 145    for IPv6.  */
 146 extern struct hostent *gethostbyname2 (__const char *__name, int __af) __THROW;
 147
 148 /* Reentrant versions of the functions above.  The additional
 149    arguments specify a buffer of BUFLEN starting at BUF.  The last
 150    argument is a pointer to a variable which gets the value which
 151    would be stored in the global variable `herrno' by the
 152    non-reentrant functions.  */
 153 extern int gethostent_r (struct hostent *__restrict __result_buf,
 154                          char *__restrict __buf, size_t __buflen,
 155                          struct hostent **__restrict __result,
 156                          int *__restrict __h_errnop) __THROW;
 157
 158 extern int gethostbyaddr_r (__const void *__restrict __addr, __socklen_t __len,
 159                             int __type,
 160                             struct hostent *__restrict __result_buf,
 161                             char *__restrict __buf, size_t __buflen,
 162                             struct hostent **__restrict __result,
 163                             int *__restrict __h_errnop) __THROW;
 164
 165 extern int gethostbyname_r (__const char *__restrict __name,
 166                             struct hostent *__restrict __result_buf,
 167                             char *__restrict __buf, size_t __buflen,
 168                             struct hostent **__restrict __result,
 169                             int *__restrict __h_errnop) __THROW;
 170
 171 extern int gethostbyname2_r (__const char *__restrict __name, int __af,
 172                              struct hostent *__restrict __result_buf,
 173                              char *__restrict __buf, size_t __buflen,
 174                              struct hostent **__restrict __result,
 175                              int *__restrict __h_errnop) __THROW;
 176 #endif  /* misc */
 177
 178
 179 /* Open network data base files and mark them as staying open even
 180    after a later search if STAY_OPEN is non-zero.  */
 181 extern void setnetent (int __stay_open) __THROW;
 182
 183 /* Close network data base files and clear `stay open' flag.  */
 184 extern void endnetent (void) __THROW;
 185
 186 /* Get next entry from network data base file.  Open data base if
 187    necessary.  */
 188 extern struct netent *getnetent (void) __THROW;
 189
 190 /* Return entry from network data base which address match NET and
 191    type TYPE.  */
 192 extern struct netent *getnetbyaddr (uint32_t __net, int __type)
 193      __THROW;
 194
 195 /* Return entry from network data base for network with NAME.  */
 196 extern struct netent *getnetbyname (__const char *__name) __THROW;
 197
 198 #ifdef  __USE_MISC
 199 /* Reentrant versions of the functions above.  The additional
 200    arguments specify a buffer of BUFLEN starting at BUF.  The last
 201    argument is a pointer to a variable which gets the value which
 202    would be stored in the global variable `herrno' by the
 203    non-reentrant functions.  */
 204 extern int getnetent_r (struct netent *__restrict __result_buf,
 205                         char *__restrict __buf, size_t __buflen,
 206                         struct netent **__restrict __result,
 207                         int *__restrict __h_errnop) __THROW;
 208
 209 extern int getnetbyaddr_r (uint32_t __net, int __type,
 210                            struct netent *__restrict __result_buf,
 211                            char *__restrict __buf, size_t __buflen,
 212                            struct netent **__restrict __result,
 213                            int *__restrict __h_errnop) __THROW;
 214
 215 extern int getnetbyname_r (__const char *__restrict __name,
 216                            struct netent *__restrict __result_buf,
 217                            char *__restrict __buf, size_t __buflen,
 218                            struct netent **__restrict __result,
 219                            int *__restrict __h_errnop) __THROW;
 220 #endif  /* misc */
 221
 222
 223 /* Description of data base entry for a single service.  */
 224 struct servent
 225 {
 226   char *s_name;                 /* Official service name.  */
 227   char **s_aliases;             /* Alias list.  */
 228   int s_port;                   /* Port number.  */
 229   char *s_proto;                /* Protocol to use.  */
 230 };
 231
 232 /* Open service data base files and mark them as staying open even
 233    after a later search if STAY_OPEN is non-zero.  */
 234 extern void setservent (int __stay_open) __THROW;
 235
 236 /* Close service data base files and clear `stay open' flag.  */
 237 extern void endservent (void) __THROW;
 238
 239 /* Get next entry from service data base file.  Open data base if
 240    necessary.  */
 241 extern struct servent *getservent (void) __THROW;
 242
 243 /* Return entry from network data base for network with NAME and
 244    protocol PROTO.  */
 245 extern struct servent *getservbyname (__const char *__name,
 246                                       __const char *__proto) __THROW;
 247
 248 /* Return entry from service data base which matches port PORT and
 249    protocol PROTO.  */
 250 extern struct servent *getservbyport (int __port, __const char *__proto)
 251      __THROW;
 252
 253
 254 #ifdef  __USE_MISC
 255 /* Reentrant versions of the functions above.  The additional
 256    arguments specify a buffer of BUFLEN starting at BUF.  */
 257 extern int getservent_r (struct servent *__restrict __result_buf,
 258                          char *__restrict __buf, size_t __buflen,
 259                          struct servent **__restrict __result) __THROW;
 260
 261 extern int getservbyname_r (__const char *__restrict __name,
 262                             __const char *__restrict __proto,
 263                             struct servent *__restrict __result_buf,
 264                             char *__restrict __buf, size_t __buflen,
 265                             struct servent **__restrict __result) __THROW;
 266
 267 extern int getservbyport_r (int __port, __const char *__restrict __proto,
 268                             struct servent *__restrict __result_buf,
 269                             char *__restrict __buf, size_t __buflen,
 270                             struct servent **__restrict __result) __THROW;
 271 #endif  /* misc */
 272
 273
 274 /* Description of data base entry for a single service.  */
 275 struct protoent
 276 {
 277   char *p_name;                 /* Official protocol name.  */
 278   char **p_aliases;             /* Alias list.  */
 279   int p_proto;                  /* Protocol number.  */
 280 };
 281
 282 /* Open protocol data base files and mark them as staying open even
 283    after a later search if STAY_OPEN is non-zero.  */
 284 extern void setprotoent (int __stay_open) __THROW;
 285
 286 /* Close protocol data base files and clear `stay open' flag.  */
 287 extern void endprotoent (void) __THROW;
 288
 289 /* Get next entry from protocol data base file.  Open data base if
 290    necessary.  */
 291 extern struct protoent *getprotoent (void) __THROW;
 292
 293 /* Return entry from protocol data base for network with NAME.  */
 294 extern struct protoent *getprotobyname (__const char *__name) __THROW;
 295
 296 /* Return entry from protocol data base which number is PROTO.  */
 297 extern struct protoent *getprotobynumber (int __proto) __THROW;
 298
 299
 300 #ifdef  __USE_MISC
 301 /* Reentrant versions of the functions above.  The additional
 302    arguments specify a buffer of BUFLEN starting at BUF.  */
 303 extern int getprotoent_r (struct protoent *__restrict __result_buf,
 304                           char *__restrict __buf, size_t __buflen,
 305                           struct protoent **__restrict __result) __THROW;
 306
 307 extern int getprotobyname_r (__const char *__restrict __name,
 308                              struct protoent *__restrict __result_buf,
 309                              char *__restrict __buf, size_t __buflen,
 310                              struct protoent **__restrict __result) __THROW;
 311
 312 extern int getprotobynumber_r (int __proto,
 313                                struct protoent *__restrict __result_buf,
 314                                char *__restrict __buf, size_t __buflen,
 315                                struct protoent **__restrict __result) __THROW;
 316 #endif  /* misc */
 317
 318
 319 /* Establish network group NETGROUP for enumeration.  */
 320 extern int setnetgrent (__const char *__netgroup) __THROW;
 321
 322 /* Free all space allocated by previous `setnetgrent' call.  */
 323 extern void endnetgrent (void) __THROW;
 324
 325 /* Get next member of netgroup established by last `setnetgrent' call
 326    and return pointers to elements in HOSTP, USERP, and DOMAINP.  */
 327 extern int getnetgrent (char **__restrict __hostp,
 328                         char **__restrict __userp,
 329                         char **__restrict __domainp) __THROW;
 330
 331 #ifdef  __USE_MISC
 332 /* Test whether NETGROUP contains the triple (HOST,USER,DOMAIN).  */
 333 extern int innetgr (__const char *__netgroup, __const char *__host,
 334                     __const char *__user, __const char *domain) __THROW;
 335
 336 /* Reentrant version of `getnetgrent' where result is placed in BUFFER.  */
 337 extern int getnetgrent_r (char **__restrict __hostp,
 338                           char **__restrict __userp,
 339                           char **__restrict __domainp,
 340                           char *__restrict __buffer, size_t __buflen) __THROW;
 341 #endif  /* misc */
 342
 343
 344 #ifdef __USE_BSD
 345 /* Call `rshd' at port RPORT on remote machine *AHOST to execute CMD.
 346    The local user is LOCUSER, on the remote machine the command is
 347    executed as REMUSER.  In *FD2P the descriptor to the socket for the
 348    connection is returned.  The caller must have the right to use a
 349    reserved port.  When the function returns *AHOST contains the
 350    official host name.  */
 351 extern int rcmd (char **__restrict __ahost, unsigned short int __rport,
 352                  __const char *__restrict __locuser,
 353                  __const char *__restrict __remuser,
 354                  __const char *__restrict __cmd, int *__restrict __fd2p)
 355      __THROW;
 356
 357 /* This is the equivalent function where the protocol can be selected
 358    and which therefore can be used for IPv6.  */
 359 extern int rcmd_af (char **__restrict __ahost, unsigned short int __rport,
 360                     __const char *__restrict __locuser,
 361                     __const char *__restrict __remuser,
 362                     __const char *__restrict __cmd, int *__restrict __fd2p,
 363                     sa_family_t __af) __THROW;
 364
 365 /* Call `rexecd' at port RPORT on remote machine *AHOST to execute
 366    CMD.  The process runs at the remote machine using the ID of user
 367    NAME whose cleartext password is PASSWD.  In *FD2P the descriptor
 368    to the socket for the connection is returned.  When the function
 369    returns *AHOST contains the official host name.  */
 370 extern int rexec (char **__restrict __ahost, int __rport,
 371                   __const char *__restrict __name,
 372                   __const char *__restrict __pass,
 373                   __const char *__restrict __cmd, int *__restrict __fd2p)
 374      __THROW;
 375
 376 /* This is the equivalent function where the protocol can be selected
 377    and which therefore can be used for IPv6.  */
 378 extern int rexec_af (char **__restrict __ahost, int __rport,
 379                      __const char *__restrict __name,
 380                      __const char *__restrict __pass,
 381                      __const char *__restrict __cmd, int *__restrict __fd2p,
 382                      sa_family_t __af) __THROW;
 383
 384 /* Check whether user REMUSER on system RHOST is allowed to login as LOCUSER.
 385    If SUSER is not zero the user tries to become superuser.  Return 0 if
 386    it is possible.  */
 387 extern int ruserok (__const char *__rhost, int __suser,
 388                     __const char *__remuser, __const char *__locuser) __THROW;
 389
 390 /* This is the equivalent function where the protocol can be selected
 391    and which therefore can be used for IPv6.  */
 392 extern int ruserok_af (__const char *__rhost, int __suser,
 393                        __const char *__remuser, __const char *__locuser,
 394                        sa_family_t __af) __THROW;
 395
 396 /* Try to allocate reserved port, returning a descriptor for a socket opened
 397    at this port or -1 if unsuccessful.  The search for an available port
 398    will start at ALPORT and continues with lower numbers.  */
 399 extern int rresvport (int *__alport) __THROW;
 400
 401 /* This is the equivalent function where the protocol can be selected
 402    and which therefore can be used for IPv6.  */
 403 extern int rresvport_af (int *__alport, sa_family_t __af) __THROW;
 404 #endif
 405
 406
 407 /* Extension from POSIX.1g.  */
 408 #ifdef  __USE_POSIX
 409 /* Structure to contain information about address of a service provider.  */
 410 struct addrinfo
 411 {
 412   int ai_flags;                 /* Input flags.  */
 413   int ai_family;                /* Protocol family for socket.  */
 414   int ai_socktype;              /* Socket type.  */
 415   int ai_protocol;              /* Protocol for socket.  */
 416   socklen_t ai_addrlen;         /* Length of socket address.  */
 417   struct sockaddr *ai_addr;     /* Socket address for socket.  */
 418   char *ai_canonname;           /* Canonical name for service location.  */
 419   struct addrinfo *ai_next;     /* Pointer to next in list.  */
 420 };
 421
 422 # ifdef __USE_GNU
 423 /* Structure used as control block for asynchronous lookup.  */
 424 struct gaicb
 425 {
 426   const char *ar_name;          /* Name to look up.  */
 427   const char *ar_service;       /* Service name.  */
 428   const struct addrinfo *ar_request; /* Additional request specification.  */
 429   struct addrinfo *ar_result;   /* Pointer to result.  */
 430   /* The following are internal elements.  */
 431   int __return;
 432   int __unused[5];
 433 };
 434
 435 /* Lookup mode.  */
 436 #  define GAI_WAIT      0
 437 #  define GAI_NOWAIT    1
 438 # endif
 439
 440 /* Possible values for `ai_flags' field in `addrinfo' structure.  */
 441 # define AI_PASSIVE     0x0001  /* Socket address is intended for `bind'.  */
 442 # define AI_CANONNAME   0x0002  /* Request for canonical name.  */
 443 # define AI_NUMERICHOST 0x0004  /* Don't use name resolution.  */
 444
 445 /* Error values for `getaddrinfo' function.  */
 446 # define EAI_BADFLAGS     -1    /* Invalid value for `ai_flags' field.  */
 447 # define EAI_NONAME       -2    /* NAME or SERVICE is unknown.  */
 448 # define EAI_AGAIN        -3    /* Temporary failure in name resolution.  */
 449 # define EAI_FAIL         -4    /* Non-recoverable failure in name res.  */
 450 # define EAI_NODATA       -5    /* No address associated with NAME.  */
 451 # define EAI_FAMILY       -6    /* `ai_family' not supported.  */
 452 # define EAI_SOCKTYPE     -7    /* `ai_socktype' not supported.  */
 453 # define EAI_SERVICE      -8    /* SERVICE not supported for `ai_socktype'.  */
 454 # define EAI_ADDRFAMILY   -9    /* Address family for NAME not supported.  */
 455 # define EAI_MEMORY       -10   /* Memory allocation failure.  */
 456 # define EAI_SYSTEM       -11   /* System error returned in `errno'.  */
 457 # ifdef __USE_GNU
 458 #  define EAI_INPROGRESS  -100  /* Processing request in progress.  */
 459 #  define EAI_CANCELED    -101  /* Request canceled.  */
 460 #  define EAI_NOTCANCELED -102  /* Request not canceled.  */
 461 #  define EAI_ALLDONE     -103  /* All requests done.  */
 462 #  define EAI_INTR        -104  /* Interrupted by a signal.  */
 463 # endif
 464
 465 # define NI_MAXHOST      1025
 466 # define NI_MAXSERV      32
 467
 468 # define NI_NUMERICHOST 1       /* Don't try to look up hostname.  */
 469 # define NI_NUMERICSERV 2       /* Don't convert port number to name.  */
 470 # define NI_NOFQDN      4       /* Only return nodename portion.  */
 471 # define NI_NAMEREQD    8       /* Don't return numeric addresses.  */
 472 # define NI_DGRAM       16      /* Look up UDP service rather than TCP.  */
 473
 474 /* Translate name of a service location and/or a service name to set of
 475    socket addresses.  */
 476 extern int getaddrinfo (__const char *__restrict __name,
 477                         __const char *__restrict __service,
 478                         __const struct addrinfo *__restrict __req,
 479                         struct addrinfo **__restrict __pai) __THROW;
 480
 481 /* Free `addrinfo' structure AI including associated storage.  */
 482 extern void freeaddrinfo (struct addrinfo *__ai) __THROW;
 483
 484 /* Convert error return from getaddrinfo() to a string.  */
 485 extern __const char *gai_strerror (int __ecode) __THROW;
 486
 487 /* Translate a socket address to a location and service name.  */
 488 extern int getnameinfo (__const struct sockaddr *__restrict __sa,
 489                         socklen_t __salen, char *__restrict __host,
 490                         socklen_t __hostlen, char *__restrict __serv,
 491                         socklen_t __servlen, unsigned int __flags) __THROW;
 492
 493 # ifdef __USE_GNU
 494 /* Enqueue ENT requests from the LIST.  If MODE is GAI_WAIT wait until all
 495    requests are handled.  If WAIT is GAI_NOWAIT return immediately after
 496    queueing the requests and signal completion according to SIG.  */
 497 extern int getaddrinfo_a (int __mode, struct gaicb *__list[__restrict_arr],
 498                           int __ent, struct sigevent *__restrict __sig)
 499      __THROW;
 500
 501 /* Suspend execution of the thread until at least one of the ENT requests
 502    in LIST is handled.  If TIMEOUT is not a null pointer it specifies the
 503    longest time the function keeps waiting before returning with an error.  */
 504 extern int gai_suspend (__const struct gaicb *__const __list[], int __ent,
 505                         __const struct timespec *__timeout) __THROW;
 506
 507 /* Get the error status of the request REQ.  */
 508 extern int gai_error (struct gaicb *__req) __THROW;
 509
 510 /* Cancel the requests associated with GAICBP.  */
 511 extern int gai_cancel (struct gaicb *__gaicbp) __THROW;
 512 # endif /* GNU */
 513 #endif  /* POSIX */
 514
 515 __END_DECLS
 516
 517 #endif  /* netdb.h */