resolv/resolv_conf.h

   1 /* Extended resolver state separate from struct __res_state.
   2    Copyright (C) 2017-2024 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    <https://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 struct file_change_detection;
  67
  68 /* Read /etc/resolv.conf and return a configuration object, or NULL if
  69    /etc/resolv.conf cannot be read due to memory allocation errors.
  70    If PREINIT is not NULL, some configuration values are taken from
  71    the struct __res_state object.  If CHANGE is not null, file change
  72    detection data is written to *CHANGE, based on the state of the
  73    file after reading it.  */
  74 struct resolv_conf *__resolv_conf_load (struct __res_state *preinit,
  75                                         struct file_change_detection *change)
  76   attribute_hidden __attribute__ ((warn_unused_result));
  77
  78 /* Return a configuration object for the current /etc/resolv.conf
  79    settings, or NULL on failure.  The object is cached.  */
  80 struct resolv_conf *__resolv_conf_get_current (void)
  81   attribute_hidden __attribute__ ((warn_unused_result));
  82
  83 /* Return the extended resolver state for *RESP, or NULL if it cannot
  84    be determined.  A call to this function must be paired with a call
  85    to __resolv_conf_put.  */
  86 struct resolv_conf *__resolv_conf_get (struct __res_state *) attribute_hidden;
  87
  88 /* Converse of __resolv_conf_get.  */
  89 void __resolv_conf_put (struct resolv_conf *) attribute_hidden;
  90
  91 /* Allocate a new struct resolv_conf object and copy the
  92    pre-configured values from *INIT.  Return NULL on allocation
  93    failure.  The object must be deallocated using
  94    __resolv_conf_put.  */
  95 struct resolv_conf *__resolv_conf_allocate (const struct resolv_conf *init)
  96   attribute_hidden __attribute__ ((nonnull (1), warn_unused_result));
  97
  98 /* Associate an existing extended resolver state with *RESP.  Return
  99    false on allocation failure.  In addition, update *RESP with the
 100    overlapping non-extended resolver state.  */
 101 bool __resolv_conf_attach (struct __res_state *, struct resolv_conf *)
 102   attribute_hidden;
 103
 104 /* Detach the extended resolver state from *RESP.  */
 105 void __resolv_conf_detach (struct __res_state *resp) attribute_hidden;
 106
 107 #endif /* RESOLV_STATE_H */