int
nsdispatch(
void *nsdrv
const ns_dtab dtab[]
const char *database
const char *name
const ns_src defaults[]
...
)
)
function invokes the callback functions specified in
dtab
in the order given in
/etc/nsswitch.conf
for the database
database
until the action criteria for a source of that database is fulfilled.
nsdrv
is passed to each callback function to use as necessary
(to pass back to the caller of
nsdispatch()).
dtab
is an array of
ns_dtab
structures, which have the following format:
typedef struct { const char *src; nss_method cb; void *cb_data; } ns_dtab;The
dtab
array should consist of one entry for each source type that has a static implementation, withsrc
as the name of the source,cb
as a callback function which handles that source, andcb_data
as a pointer to arbitrary data to be passed to the callback function. The last entry indtab
should containNULL
values forsrc
,cb
, andcb_data
.The callback function signature is described by the typedef:
typedef
int
*nss_method(
void *cbrv
void *cbdata
va_list ap
);
cbrv
nsdrv
that
nsdispatch(
)
was invoked with.
cbdata
cb_data
member of the array entry for the source that this
callback function implements in the
dtab
argument of
nsdispatch(
).
ap
...
arguments to
nsdispatch(
),
converted to a
va_list
.
database
and
name
are used to select methods from optional per-source
dynamically-loaded modules.
name
is usually the name of the function calling
nsdispatch().
Note that the callback functions provided by
dtab
take priority over those implemented in dynamically-loaded modules in the
event of a conflict.
defaults
contains a list of default sources to try in the case of
a missing or corrupt
nsswitch.conf(5),
or if there isn't a relevant entry for
database
.
It is an array of
ns_src
structures, which have the following format:
typedef struct { const char *src; uint32_t flags; } ns_src;The
defaults
array should consist of one entry for each source to consult by default indicated bysrc
, andflags
set to the desired behavior (usuallyNS_SUCCESS
; refer to Callback function return values for more information). The last entry indefaults
should havesrc
set toNULL
andflags
set to 0.Some invokers of nsdispatch(
) (such as setgrent(3)) need to force all callback functions to be invoked, irrespective of the action criteria listed in nsswitch.conf(5). This can be achieved by adding
NS_FORCEALL
todefaults[0].flags
before invoking nsdispatch(). The return value of nsdispatch(
) will be the result of the final callback function invoked.
For convenience, a global variable defined as:
extern
const
ns_src
__nsdefaultsrc[];
exists which contains a single default entry for `files' for use by callers which don't require complicated default rules.
...
are optional extra arguments, which
are passed to the appropriate callback function as a
stdarg(3)
variable argument
list of the type
va_list
.
nsdispatch
returns the value of the callback function that caused the dispatcher
to finish, or
NS_NOTFOUND
otherwise.
)
function loads callback functions from the run-time link-editor's search
path using the following naming convention:
nss_<source>.so.<version>
NSS_MODULE_INTERFACE_VERSION
,
which has the value 0.
When a module is loaded,
nsdispatch()
looks for and calls the following function in the module:
ns_mtab
*
nss_module_register(
const char *source
u_int *nelems
nss_module_unregister_fn *unreg
);
source
)
to construct the module's name.
nelems
)
should set to the number of elements in the
ns_mtab
array returned by
nss_module_register(
),
or
0
if there was a failure.
unreg
)
can optionally set to an unregister function to be invoked when the module is
unloaded, or
NULL
if there isn't one.
The unregister function signature is described by the typedef:
typedef
void
*nss_module_unregister_fn(
ns_mtab *mtab
u_int nelems
);
mtab
ns_mtab
structures returned by
nss_module_register(
).
nelems
*nelems
value set by
nss_module_register(
).
nss_module_register()
returns an array of
ns_mtab
structures
(with
*nelems
entries), or
NULL
if there was a failure.
The
ns_mtab
structures have the following format:
typedef struct { const char *database; const char *name; nss_method method; void *mdata; } ns_mtab;The
mtab
array should consist of one entry for each callback function (method) that is implemented, withdatabase
as the name of the database,name
as the name of the callback function,method
as thenss_method
callback function that implements the method, andmdata
as a pointer to arbitrary data to be passed to the callback function as itscbdata
argument.
NSSRC_FILES "files" |
NSSRC_DNS "dns" |
NSSRC_NIS "nis" |
NSSRC_COMPAT "compat" |
Refer to nsswitch.conf(5) for a complete description of what each source type is.
NSDB_HOSTS "hosts" |
NSDB_GROUP "group" |
NSDB_GROUP_COMPAT "group_compat" |
NSDB_NETGROUP "netgroup" |
NSDB_NETWORKS "networks" |
NSDB_PASSWD "passwd" |
NSDB_PASSWD_COMPAT "passwd_compat" |
NSDB_SHELLS "shells" |
Refer to nsswitch.conf(5) for a complete description of what each database is.
NS_SUCCESS The requested entry was found. |
NS_NOTFOUND The entry is not present at this source. |
NS_TRYAGAIN The source is busy, and may respond to retries. |
NS_UNAVAIL The source is not responding, or entry is corrupt. |
ap
argument for an
nss_method(
)
callback function for a standard method in a standard database is:
For example, given the standard function getgrnam(3):
struct
group
*
getgrnam(const char *name
)
ap
organization used by the callback functions is:
struct group **
const char *
NOTE: Not all standard databases are using this calling convention yet; those that aren't are noted below. These will be changed in the future.
The callback function names and
va_list
organization for various standard database callback functions are:
char *name
,
const struct addrinfo *pai
Returns
struct addrinfo *
via
void *cbrv
.
unsigned char *addr
,
int addrlen
,
int af
Returns
struct hostent *
via
void *cbrv
.
char *name
,
int namelen
,
int af
Returns
struct hostent *
via
void *cbrv
.
ap
.
All methods for all sources are invoked for this method name.
struct group **retval
*retval
should be set to a pointer to an internal static
struct group
on success,
NULL
otherwise.
getgrent(3)
returns
*retval
if
nsdispatch()
returns
NS_SUCCESS
,
NULL
otherwise.
int *retval
,
struct group *grp
,
char *buffer
,
size_t buflen
,
struct group **result
*retval
should be set to an appropriate
errno(2)
on failure.
getgrent_r(3)
returns 0
if
nsdispatch()
returns
NS_SUCCESS
or
NS_NOTFOUND
,
and
*retval
otherwise.
struct group **retval
,
gid_t gid
*retval
should be set to a pointer to an internal static
struct group
on success,
NULL
otherwise.
getgrgid(3)
returns
*retval
if
nsdispatch()
returns
NS_SUCCESS
,
NULL
otherwise.
int *retval
,
gid_t gid
,
struct group *grp
,
char *buffer
,
size_t buflen
,
struct group **result
*retval
should be set to an appropriate
errno(2)
on failure.
getgrgid_r(3)
returns 0
if
nsdispatch()
returns
NS_SUCCESS
or
NS_NOTFOUND
,
and
*retval
otherwise.
struct group **retval
,
const char *name
*retval
should be set to a pointer to an internal static
struct group
on success,
NULL
otherwise.
getgrnam(3)
returns
*retval
if
nsdispatch()
returns
NS_SUCCESS
,
NULL
otherwise.
int *retval
,
const char *name
,
struct group *grp
,
char *buffer
,
size_t buflen
,
struct group **result
*retval
should be set to an appropriate
errno(2)
on failure.
getgrnam_r(3)
returns 0
if
nsdispatch()
returns
NS_SUCCESS
or
NS_NOTFOUND
,
and
*retval
otherwise.
int *retval
,
const char *name
,
gid_t basegid
,
gid_t *groups
,
int maxgrp
,
int *groupc
retval
is unused.
Lookups for
group_compat
are also stopped if
NS_SUCCESS
was returned to prevent multiple
``+:''
compat entries from being expanded.
getgroupmembership(3)
returns
is -1 if
*groupc
is greater than to
maxgrp
,
and 0 otherwise.
int *retval
,
int stayopen
retval
should be set to 0 on failure and 1 on success.
All methods for all sources are invoked for this method name.
ap
.
All methods for all sources are invoked for this method name.
ap
.
char *name
,
char **line
,
int bywhat
Find the given
name
and return its value in
line
.
bywhat
is one of
_NG_KEYBYNAME
,
_NG_KEYBYUSER
,
or
_NG_KEYBYHOST
.
int *retval
,
const char **host
,
const char **user
,
const char **domain
*retval
should be set to 0 for no more netgroup members and 1 otherwise.
getnetgrent(3)
returns
*retval
if
nsdispatch()
returns
NS_SUCCESS
,
0 otherwise.
int *retval
,
const char *grp
,
const char *host
,
const char *user
,
const char *domain
*retval
should be set to 1 for a successful match and 0 otherwise.
const char *netgroup
struct netent **retval
,
uint32_t net
,
int type
*retval
should be set to a pointer to an internal static
struct netent
on success,
NULL
otherwise.
getnetbyaddr(3)
returns
*retval
if
nsdispatch()
returns
NS_SUCCESS
,
NULL
otherwise.
struct netent **retval
,
const char *name
*retval
should be set to a pointer to an internal static
struct netent
on success,
NULL
otherwise.
getnetbyname(3)
returns
*retval
if
nsdispatch()
returns
NS_SUCCESS
,
NULL
otherwise.
ap
.
All methods for all sources are invoked for this method name.
struct passwd **retval
*retval
should be set to a pointer to an internal static
struct passwd
on success,
NULL
otherwise.
getpwent(3)
returns
*retval
if
nsdispatch()
returns
NS_SUCCESS
,
NULL
otherwise.
int *retval
,
struct passwd *pw
,
char *buffer
,
size_t buflen
,
struct passwd **result
*retval
should be set to an appropriate
errno(2)
on failure.
getpwent_r(3)
returns 0
if
nsdispatch()
returns
NS_SUCCESS
or
NS_NOTFOUND
,
and
*retval
otherwise.
struct passwd **retval
,
const char *name
*retval
should be set to a pointer to an internal static
struct passwd
on success,
NULL
otherwise.
getpwnam(3)
returns
*retval
if
nsdispatch()
returns
NS_SUCCESS
,
NULL
otherwise.
int *retval
,
const char *name
,
struct passwd *pw
,
char *buffer
,
size_t buflen
,
struct passwd **result
*retval
should be set to an appropriate
errno(2)
on failure.
getpwnam_r(3)
returns 0
if
nsdispatch()
returns
NS_SUCCESS
or
NS_NOTFOUND
,
and
*retval
otherwise.
struct passwd **retval
,
uid_t uid
*retval
should be set to a pointer to an internal static
struct passwd
on success,
NULL
otherwise.
getpwuid(3)
returns
*retval
if
nsdispatch()
returns
NS_SUCCESS
,
NULL
otherwise.
int *retval
,
uid_t uid
,
struct passwd *pw
,
char *buffer
,
size_t buflen
,
struct passwd **result
*retval
should be set to an appropriate
errno(2)
on failure.
getpwuid_r
returns 0
if
nsdispatch()
returns
NS_SUCCESS
or
NS_NOTFOUND
,
and
*retval
otherwise.
int *retval
,
int stayopen
retval
should be set to 0 on failure and 1 on success.
All methods for all sources are invoked for this method name.
ap
.
All methods for all sources are invoked for this method name.
ap
.
All methods for all sources are invoked for this method name.
char **retval
getusershell(3)
returns
*retval
if
nsdispatch()
returns
NS_SUCCESS
,
and 0 otherwise.
ap
.
All methods for all sources are invoked for this method name.