resolv/resolv_conf.h

   1 /* Extended resolver state separate from struct __res_state.
   2    Copyright (C) 2017-2018 Free Software Foundation, Inc.
   3    This file is part of the GNU C Library.
   4
   5    The GNU C Library is free software; you can redistribute it and/or
   6    modify it under the terms of the GNU Lesser General Public
   7    License as published by the Free Software Foundation; either
   8    version 2.1 of the License, or (at your option) any later version.
   9
  10    The GNU C Library is distributed in the hope that it will be useful,
  11    but WITHOUT ANY WARRANTY; without even the implied warranty of
  12    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13    Lesser General Public License for more details.
  14
  15    You should have received a copy of the GNU Lesser General Public
  16    License along with the GNU C Library; if not, see
  17    <http://www.gnu.org/licenses/>.  */
  18
  19 #ifndef RESOLV_STATE_H
  20 #define RESOLV_STATE_H
  21
  22 #include <netinet/in.h>
  23 #include <stdbool.h>
  24 #include <stddef.h>
  25
  26 /* This type corresponds to members of the _res.sort_list array.  */
  27 struct resolv_sortlist_entry
  28 {
  29   struct in_addr addr;
  30   uint32_t mask;
  31 };
  32
  33 /* Extended resolver state associated with res_state objects.  Client
  34    code can reach this state through a struct resolv_context
  35    object.  */
  36 struct resolv_conf
  37 {
  38   /* Reference counter.  The object is deallocated once it reaches
  39      zero.  For internal use within resolv_conf only.  */
  40   size_t __refcount;
  41
  42   /* List of IPv4 and IPv6 name server addresses.  */
  43   const struct sockaddr **nameserver_list;
  44   size_t nameserver_list_size;
  45
  46   /* The domain names forming the search list.  */
  47   const char *const *search_list;
  48   size_t search_list_size;
  49
  50   /* IPv4 address preference rules.  */
  51   const struct resolv_sortlist_entry *sort_list;
  52   size_t sort_list_size;
  53
  54   /* _res.options has type unsigned long, but we can only use 32 bits
  55      for portability across all architectures.  */
  56   unsigned int options;
  57   unsigned int retrans;         /* Timeout.  */
  58   unsigned int retry;           /* Number of times to retry.  */
  59   unsigned int ndots; /* Dots needed for initial non-search query.  */
  60 };
  61
  62 /* The functions below are for use by the res_init resolv.conf parser
  63    and the struct resolv_context facility.  */
  64
  65 struct __res_state;
  66
  67 /* Read /etc/resolv.conf and return a configuration object, or NULL if
  68    /etc/resolv.conf cannot be read due to memory allocation errors.
  69    If PREINIT is not NULL, some configuration values are taken from the
  70    struct __res_state object.  */
  71 struct resolv_conf *__resolv_conf_load (struct __res_state *preinit)
  72   attribute_hidden __attribute__ ((warn_unused_result));
  73
  74 /* Return a configuration object for the current /etc/resolv.conf
  75    settings, or NULL on failure.  The object is cached.  */
  76 struct resolv_conf *__resolv_conf_get_current (void)
  77   attribute_hidden __attribute__ ((warn_unused_result));
  78
  79 /* Return the extended resolver state for *RESP, or NULL if it cannot
  80    be determined.  A call to this function must be paired with a call
  81    to __resolv_conf_put.  */
  82 struct resolv_conf *__resolv_conf_get (struct __res_state *) attribute_hidden;
  83
  84 /* Converse of __resolv_conf_get.  */
  85 void __resolv_conf_put (struct resolv_conf *) attribute_hidden;
  86
  87 /* Allocate a new struct resolv_conf object and copy the
  88    pre-configured values from *INIT.  Return NULL on allocation
  89    failure.  The object must be deallocated using
  90    __resolv_conf_put.  */
  91 struct resolv_conf *__resolv_conf_allocate (const struct resolv_conf *init)
  92   attribute_hidden __attribute__ ((nonnull (1), warn_unused_result));
  93
  94 /* Associate an existing extended resolver state with *RESP.  Return
  95    false on allocation failure.  In addition, update *RESP with the
  96    overlapping non-extended resolver state.  */
  97 bool __resolv_conf_attach (struct __res_state *, struct resolv_conf *)
  98   attribute_hidden;
  99
 100 /* Detach the extended resolver state from *RESP.  */
 101 void __resolv_conf_detach (struct __res_state *resp) attribute_hidden;
 102
 103 #endif /* RESOLV_STATE_H */