nss/nss_module.h

   1 /* Global list of NSS service modules.
   2    Copyright (c) 2020-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 _NSS_MODULE_H
  20 #define _NSS_MODULE_H
  21
  22 #include <nss.h>
  23 #include <stdbool.h>
  24
  25 /* See nss_database.h for a summary of how this relates.  */
  26
  27 /* Typed function pointers for all functions that can be defined by a
  28    service module.  */
  29 struct nss_module_functions
  30 {
  31 #undef DEFINE_NSS_FUNCTION
  32 #define DEFINE_NSS_FUNCTION(f) nss_##f *f;
  33 #include "function.def"
  34 };
  35
  36 /* Number of elements of the nss_module_functions_untyped array.  */
  37 enum
  38   {
  39     nss_module_functions_count = (sizeof (struct nss_module_functions)
  40                                   / sizeof (void *))
  41   };
  42
  43 /* Untyped version of struct nss_module_functions, for consistent
  44    processing purposes.  */
  45 typedef void *nss_module_functions_untyped[nss_module_functions_count];
  46
  47 /* Locate the nss_files functions, as if by dlopen/dlsym.  */
  48 void __nss_files_functions (nss_module_functions_untyped pointers)
  49   attribute_hidden;
  50
  51 /* Initialization state of a NSS module.  */
  52 enum nss_module_state
  53 {
  54   nss_module_uninitialized,
  55   nss_module_loaded,
  56   nss_module_failed,
  57 };
  58
  59 /* A NSS service module (potentially unloaded).  Client code should
  60    use the functions below.  */
  61 struct nss_module
  62 {
  63   /* Actual type is enum nss_module_state.  Use int due to atomic
  64      access.  Used in a double-checked locking idiom.  */
  65   int state;
  66
  67   /* The function pointers in the module.  */
  68   union
  69   {
  70     struct nss_module_functions typed;
  71     nss_module_functions_untyped untyped;
  72   } functions;
  73
  74   /* Only used for __libc_freeres unloading.  */
  75   void *handle;
  76
  77   /* The next module in the list. */
  78   struct nss_module *next;
  79
  80   /* The name of the module (as it appears in /etc/nsswitch.conf).  */
  81   char name[];
  82 };
  83
  84 /* Allocates the NSS module NAME (of NAME_LENGTH bytes) and places it
  85    into the global list.  If it already exists in the list, return the
  86    pre-existing module.  This does not actually load the module.
  87    Returns NULL on memory allocation failure.  */
  88 struct nss_module *__nss_module_allocate (const char *name,
  89                                           size_t name_length) attribute_hidden;
  90
  91 /* Ensures that MODULE is in a loaded or failed state.  */
  92 bool __nss_module_load (struct nss_module *module) attribute_hidden;
  93
  94 /* Ensures that MODULE is loaded and returns a pointer to the function
  95    NAME defined in it.  Returns NULL if MODULE could not be loaded, or
  96    if the function NAME is not defined in the module.  */
  97 void *__nss_module_get_function (struct nss_module *module, const char *name)
  98   attribute_hidden;
  99
 100 /* Block attempts to dlopen any module we haven't already opened.  */
 101 void __nss_module_disable_loading (void);
 102
 103 /* Called from __libc_freeres.  */
 104 void __nss_module_freeres (void) attribute_hidden;
 105
 106 #endif /* NSS_MODULE_H */