1  /* Extended resolver state separate from struct __res_state.
       2     Copyright (C) 2017-2023 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 */