|
Packit |
6c4009 |
@node Name Service Switch, Users and Groups, Job Control, Top
|
|
Packit |
6c4009 |
@chapter System Databases and Name Service Switch
|
|
Packit |
6c4009 |
@c %MENU% Accessing system databases
|
|
Packit |
6c4009 |
@cindex Name Service Switch
|
|
Packit |
6c4009 |
@cindex NSS
|
|
Packit |
6c4009 |
@cindex databases
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Various functions in the C Library need to be configured to work
|
|
Packit |
6c4009 |
correctly in the local environment. Traditionally, this was done by
|
|
Packit |
6c4009 |
using files (e.g., @file{/etc/passwd}), but other nameservices (like the
|
|
Packit |
6c4009 |
Network Information Service (NIS) and the Domain Name Service (DNS))
|
|
Packit |
6c4009 |
became popular, and were hacked into the C library, usually with a fixed
|
|
Packit |
6c4009 |
search order.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@Theglibc{} contains a cleaner solution to this problem. It is
|
|
Packit |
6c4009 |
designed after a method used by Sun Microsystems in the C library of
|
|
Packit |
6c4009 |
@w{Solaris 2}. @Theglibc{} follows their name and calls this
|
|
Packit |
6c4009 |
scheme @dfn{Name Service Switch} (NSS).
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Though the interface might be similar to Sun's version there is no
|
|
Packit |
6c4009 |
common code. We never saw any source code of Sun's implementation and
|
|
Packit |
6c4009 |
so the internal interface is incompatible. This also manifests in the
|
|
Packit |
6c4009 |
file names we use as we will see later.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@menu
|
|
Packit |
6c4009 |
* NSS Basics:: What is this NSS good for.
|
|
Packit |
6c4009 |
* NSS Configuration File:: Configuring NSS.
|
|
Packit |
6c4009 |
* NSS Module Internals:: How does it work internally.
|
|
Packit |
6c4009 |
* Extending NSS:: What to do to add services or databases.
|
|
Packit |
6c4009 |
@end menu
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@node NSS Basics, NSS Configuration File, Name Service Switch, Name Service Switch
|
|
Packit |
6c4009 |
@section NSS Basics
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The basic idea is to put the implementation of the different services
|
|
Packit |
6c4009 |
offered to access the databases in separate modules. This has some
|
|
Packit |
6c4009 |
advantages:
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@enumerate
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
Contributors can add new services without adding them to @theglibc{}.
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
The modules can be updated separately.
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
The C library image is smaller.
|
|
Packit |
6c4009 |
@end enumerate
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
To fulfill the first goal above, the ABI of the modules will be described
|
|
Packit |
6c4009 |
below. For getting the implementation of a new service right it is
|
|
Packit |
6c4009 |
important to understand how the functions in the modules get called.
|
|
Packit |
6c4009 |
They are in no way designed to be used by the programmer directly.
|
|
Packit |
6c4009 |
Instead the programmer should only use the documented and standardized
|
|
Packit |
6c4009 |
functions to access the databases.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@noindent
|
|
Packit |
6c4009 |
The databases available in the NSS are
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@cindex ethers
|
|
Packit |
6c4009 |
@cindex group
|
|
Packit |
6c4009 |
@cindex hosts
|
|
Packit |
6c4009 |
@cindex netgroup
|
|
Packit |
6c4009 |
@cindex networks
|
|
Packit Service |
ca117e |
@cindex protocols
|
|
Packit Service |
3b0880 |
@cindex passwd
|
|
Packit |
6c4009 |
@cindex rpc
|
|
Packit |
6c4009 |
@cindex services
|
|
Packit |
6c4009 |
@cindex shadow
|
|
Packit |
6c4009 |
@table @code
|
|
Packit |
6c4009 |
@item aliases
|
|
Packit |
6c4009 |
Mail aliases
|
|
Packit |
6c4009 |
@comment @pxref{Mail Aliases}.
|
|
Packit |
6c4009 |
@item ethers
|
|
Packit |
6c4009 |
Ethernet numbers,
|
|
Packit |
6c4009 |
@comment @pxref{Ethernet Numbers}.
|
|
Packit |
6c4009 |
@item group
|
|
Packit |
6c4009 |
Groups of users, @pxref{Group Database}.
|
|
Packit |
6c4009 |
@item hosts
|
|
Packit |
6c4009 |
Host names and numbers, @pxref{Host Names}.
|
|
Packit |
6c4009 |
@item netgroup
|
|
Packit |
6c4009 |
Network wide list of host and users, @pxref{Netgroup Database}.
|
|
Packit |
6c4009 |
@item networks
|
|
Packit |
6c4009 |
Network names and numbers, @pxref{Networks Database}.
|
|
Packit Service |
ca117e |
@item protocols
|
|
Packit Service |
ca117e |
Network protocols, @pxref{Protocols Database}.
|
|
Packit Service |
3b0880 |
@item passwd
|
|
Packit Service |
3b0880 |
User identities, @pxref{User Database}.
|
|
Packit |
6c4009 |
@item rpc
|
|
Packit |
6c4009 |
Remote procedure call names and numbers.
|
|
Packit |
6c4009 |
@comment @pxref{RPC Database}.
|
|
Packit |
6c4009 |
@item services
|
|
Packit |
6c4009 |
Network services, @pxref{Services Database}.
|
|
Packit |
6c4009 |
@item shadow
|
|
Packit |
6c4009 |
User passphrase hashes and related information.
|
|
Packit |
6c4009 |
@comment @pxref{Shadow Passphrase Database}.
|
|
Packit |
6c4009 |
@end table
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@noindent
|
|
Packit Service |
3b0880 |
There will be some more added later (@code{automount}, @code{bootparams},
|
|
Packit Service |
3b0880 |
@code{netmasks}, and @code{publickey}).
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@node NSS Configuration File, NSS Module Internals, NSS Basics, Name Service Switch
|
|
Packit |
6c4009 |
@section The NSS Configuration File
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@cindex @file{/etc/nsswitch.conf}
|
|
Packit |
6c4009 |
@cindex @file{nsswitch.conf}
|
|
Packit |
6c4009 |
Somehow the NSS code must be told about the wishes of the user. For
|
|
Packit |
6c4009 |
this reason there is the file @file{/etc/nsswitch.conf}. For each
|
|
Packit |
6c4009 |
database, this file contains a specification of how the lookup process should
|
|
Packit |
6c4009 |
work. The file could look like this:
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@example
|
|
Packit |
6c4009 |
@include nsswitch.texi
|
|
Packit |
6c4009 |
@end example
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The first column is the database as you can guess from the table above.
|
|
Packit |
6c4009 |
The rest of the line specifies how the lookup process works. Please
|
|
Packit |
6c4009 |
note that you specify the way it works for each database individually.
|
|
Packit |
6c4009 |
This cannot be done with the old way of a monolithic implementation.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The configuration specification for each database can contain two
|
|
Packit |
6c4009 |
different items:
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@itemize @bullet
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
the service specification like @code{files}, @code{db}, or @code{nis}.
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
the reaction on lookup result like @code{[NOTFOUND=return]}.
|
|
Packit |
6c4009 |
@end itemize
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@menu
|
|
Packit |
6c4009 |
* Services in the NSS configuration:: Service names in the NSS configuration.
|
|
Packit |
6c4009 |
* Actions in the NSS configuration:: React appropriately to the lookup result.
|
|
Packit |
6c4009 |
* Notes on NSS Configuration File:: Things to take care about while
|
|
Packit |
6c4009 |
configuring NSS.
|
|
Packit |
6c4009 |
@end menu
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@node Services in the NSS configuration, Actions in the NSS configuration, NSS Configuration File, NSS Configuration File
|
|
Packit |
6c4009 |
@subsection Services in the NSS configuration File
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The above example file mentions five different services: @code{files},
|
|
Packit |
6c4009 |
@code{db}, @code{dns}, @code{nis}, and @code{nisplus}. This does not
|
|
Packit |
6c4009 |
mean these
|
|
Packit |
6c4009 |
services are available on all sites and neither does it mean these are
|
|
Packit |
6c4009 |
all the services which will ever be available.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
In fact, these names are simply strings which the NSS code uses to find
|
|
Packit |
6c4009 |
the implicitly addressed functions. The internal interface will be
|
|
Packit |
6c4009 |
described later. Visible to the user are the modules which implement an
|
|
Packit |
6c4009 |
individual service.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Assume the service @var{name} shall be used for a lookup. The code for
|
|
Packit |
6c4009 |
this service is implemented in a module called @file{libnss_@var{name}}.
|
|
Packit |
6c4009 |
On a system supporting shared libraries this is in fact a shared library
|
|
Packit |
6c4009 |
with the name (for example) @file{libnss_@var{name}.so.2}. The number
|
|
Packit |
6c4009 |
at the end is the currently used version of the interface which will not
|
|
Packit |
6c4009 |
change frequently. Normally the user should not have to be cognizant of
|
|
Packit |
6c4009 |
these files since they should be placed in a directory where they are
|
|
Packit |
6c4009 |
found automatically. Only the names of all available services are
|
|
Packit |
6c4009 |
important.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@node Actions in the NSS configuration, Notes on NSS Configuration File, Services in the NSS configuration, NSS Configuration File
|
|
Packit |
6c4009 |
@subsection Actions in the NSS configuration
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The second item in the specification gives the user much finer control
|
|
Packit |
6c4009 |
on the lookup process. Action items are placed between two service
|
|
Packit |
6c4009 |
names and are written within brackets. The general form is
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@display
|
|
Packit |
6c4009 |
@code{[} ( @code{!}? @var{status} @code{=} @var{action} )+ @code{]}
|
|
Packit |
6c4009 |
@end display
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@noindent
|
|
Packit |
6c4009 |
where
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@smallexample
|
|
Packit |
6c4009 |
@var{status} @result{} success | notfound | unavail | tryagain
|
|
Packit |
6c4009 |
@var{action} @result{} return | continue
|
|
Packit |
6c4009 |
@end smallexample
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The case of the keywords is insignificant. The @var{status}
|
|
Packit |
6c4009 |
values are the results of a call to a lookup function of a specific
|
|
Packit |
6c4009 |
service. They mean:
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@ftable @samp
|
|
Packit |
6c4009 |
@item success
|
|
Packit |
6c4009 |
No error occurred and the wanted entry is returned. The default action
|
|
Packit |
6c4009 |
for this is @code{return}.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item notfound
|
|
Packit |
6c4009 |
The lookup process works ok but the needed value was not found. The
|
|
Packit |
6c4009 |
default action is @code{continue}.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item unavail
|
|
Packit |
6c4009 |
@cindex DNS server unavailable
|
|
Packit |
6c4009 |
The service is permanently unavailable. This can either mean the needed
|
|
Packit |
6c4009 |
file is not available, or, for DNS, the server is not available or does
|
|
Packit |
6c4009 |
not allow queries. The default action is @code{continue}.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item tryagain
|
|
Packit |
6c4009 |
The service is temporarily unavailable. This could mean a file is
|
|
Packit |
6c4009 |
locked or a server currently cannot accept more connections. The
|
|
Packit |
6c4009 |
default action is @code{continue}.
|
|
Packit |
6c4009 |
@end ftable
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@noindent
|
|
Packit |
6c4009 |
The @var{action} values mean:
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@ftable @samp
|
|
Packit |
6c4009 |
@item return
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
If the status matches, stop the lookup process at this service
|
|
Packit |
6c4009 |
specification. If an entry is available, provide it to the application.
|
|
Packit |
6c4009 |
If an error occurred, report it to the application. In case of a prior
|
|
Packit |
6c4009 |
@samp{merge} action, the data is combined with previous lookup results,
|
|
Packit |
6c4009 |
as explained below.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item continue
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
If the status matches, proceed with the lookup process at the next
|
|
Packit |
6c4009 |
entry, discarding the result of the current lookup (and any merged
|
|
Packit |
6c4009 |
data). An exception is the @samp{initgroups} database and the
|
|
Packit |
6c4009 |
@samp{success} status, where @samp{continue} acts like @code{merge}
|
|
Packit |
6c4009 |
below.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item merge
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Proceed with the lookup process, retaining the current lookup result.
|
|
Packit |
6c4009 |
This action is useful only with the @samp{success} status. If a
|
|
Packit |
6c4009 |
subsequent service lookup succeeds and has a matching @samp{return}
|
|
Packit |
6c4009 |
specification, the results are merged, the lookup process ends, and the
|
|
Packit |
6c4009 |
merged results are returned to the application. If the following service
|
|
Packit |
6c4009 |
has a matching @samp{merge} action, the lookup process continues,
|
|
Packit |
6c4009 |
retaining the combined data from this and any previous lookups.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
After a @code{merge} action, errors from subsequent lookups are ignored,
|
|
Packit |
6c4009 |
and the data gathered so far will be returned.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The @samp{merge} only applies to the @samp{success} status. It is
|
|
Packit |
6c4009 |
currently implemented for the @samp{group} database and its group
|
|
Packit |
6c4009 |
members field, @samp{gr_mem}. If specified for other databases, it
|
|
Packit |
6c4009 |
causes the lookup to fail (if the @var{status} matches).
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
When processing @samp{merge} for @samp{group} membership, the group GID
|
|
Packit |
6c4009 |
and name must be identical for both entries. If only one or the other is
|
|
Packit |
6c4009 |
a match, the behavior is undefined.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@end ftable
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@noindent
|
|
Packit |
6c4009 |
If we have a line like
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@smallexample
|
|
Packit |
6c4009 |
ethers: nisplus [NOTFOUND=return] db files
|
|
Packit |
6c4009 |
@end smallexample
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@noindent
|
|
Packit |
6c4009 |
this is equivalent to
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@smallexample
|
|
Packit |
6c4009 |
ethers: nisplus [SUCCESS=return NOTFOUND=return UNAVAIL=continue
|
|
Packit |
6c4009 |
TRYAGAIN=continue]
|
|
Packit |
6c4009 |
db [SUCCESS=return NOTFOUND=continue UNAVAIL=continue
|
|
Packit |
6c4009 |
TRYAGAIN=continue]
|
|
Packit |
6c4009 |
files
|
|
Packit |
6c4009 |
@end smallexample
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@noindent
|
|
Packit |
6c4009 |
(except that it would have to be written on one line). The default
|
|
Packit |
6c4009 |
value for the actions are normally what you want, and only need to be
|
|
Packit |
6c4009 |
changed in exceptional cases.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
If the optional @code{!} is placed before the @var{status} this means
|
|
Packit |
6c4009 |
the following action is used for all statuses but @var{status} itself.
|
|
Packit |
6c4009 |
I.e., @code{!} is negation as in the C language (and others).
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Before we explain the exception which makes this action item necessary
|
|
Packit |
6c4009 |
one more remark: obviously it makes no sense to add another action
|
|
Packit |
6c4009 |
item after the @code{files} service. Since there is no other service
|
|
Packit |
6c4009 |
following the action @emph{always} is @code{return}.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@cindex nisplus, and completeness
|
|
Packit |
6c4009 |
Now, why is this @code{[NOTFOUND=return]} action useful? To understand
|
|
Packit |
6c4009 |
this we should know that the @code{nisplus} service is often
|
|
Packit |
6c4009 |
complete; i.e., if an entry is not available in the NIS+ tables it is
|
|
Packit |
6c4009 |
not available anywhere else. This is what is expressed by this action
|
|
Packit |
6c4009 |
item: it is useless to examine further services since they will not give
|
|
Packit |
6c4009 |
us a result.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@cindex nisplus, and booting
|
|
Packit |
6c4009 |
@cindex bootstrapping, and services
|
|
Packit |
6c4009 |
The situation would be different if the NIS+ service is not available
|
|
Packit |
6c4009 |
because the machine is booting. In this case the return value of the
|
|
Packit |
6c4009 |
lookup function is not @code{notfound} but instead @code{unavail}. And
|
|
Packit |
6c4009 |
as you can see in the complete form above: in this situation the
|
|
Packit |
6c4009 |
@code{db} and @code{files} services are used. Neat, isn't it? The
|
|
Packit |
6c4009 |
system administrator need not pay special care for the time the system
|
|
Packit |
6c4009 |
is not completely ready to work (while booting or shutdown or
|
|
Packit |
6c4009 |
network problems).
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@node Notes on NSS Configuration File, , Actions in the NSS configuration, NSS Configuration File
|
|
Packit |
6c4009 |
@subsection Notes on the NSS Configuration File
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Finally a few more hints. The NSS implementation is not completely
|
|
Packit |
6c4009 |
helpless if @file{/etc/nsswitch.conf} does not exist. For
|
|
Packit |
6c4009 |
all supported databases there is a default value so it should normally
|
|
Packit |
6c4009 |
be possible to get the system running even if the file is corrupted or
|
|
Packit |
6c4009 |
missing.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@cindex default value, and NSS
|
|
Packit |
6c4009 |
For the @code{hosts} and @code{networks} databases the default value is
|
|
Packit |
6c4009 |
@code{dns [!UNAVAIL=return] files}. I.e., the system is prepared for
|
|
Packit |
6c4009 |
the DNS service not to be available but if it is available the answer it
|
|
Packit |
6c4009 |
returns is definitive.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The @code{passwd}, @code{group}, and @code{shadow} databases are
|
|
Packit |
6c4009 |
traditionally handled in a special way. The appropriate files in the
|
|
Packit |
6c4009 |
@file{/etc} directory are read but if an entry with a name starting
|
|
Packit |
6c4009 |
with a @code{+} character is found NIS is used. This kind of lookup
|
|
Packit |
6c4009 |
remains possible if @theglibc{} was configured with the
|
|
Packit |
6c4009 |
@code{--enable-obsolete-nsl} option and the special lookup service
|
|
Packit |
6c4009 |
@code{compat} is used. If @theglibc{} was configured with the
|
|
Packit |
6c4009 |
@code{--enable-obsolete-nsl} option the default value for the three
|
|
Packit |
6c4009 |
databases above is @code{compat [NOTFOUND=return] files}. If the
|
|
Packit |
6c4009 |
@code{--enable-obsolete-nsl} option was not used the default value
|
|
Packit |
6c4009 |
for the services is @code{files}.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
For all other databases the default value is @code{files} unless
|
|
Packit |
6c4009 |
@theglibc{} was configured with @code{--enable-obsolete-rpc} option, in
|
|
Packit |
6c4009 |
which case it the default value is @code{nis [NOTFOUND=return] files}.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@cindex optimizing NSS
|
|
Packit |
6c4009 |
A second point is that the user should try to optimize the lookup
|
|
Packit |
6c4009 |
process. The different service have different response times.
|
|
Packit |
6c4009 |
A simple file look up on a local file could be fast, but if the file
|
|
Packit |
6c4009 |
is long and the needed entry is near the end of the file this may take
|
|
Packit |
6c4009 |
quite some time. In this case it might be better to use the @code{db}
|
|
Packit |
6c4009 |
service which allows fast local access to large data sets.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Often the situation is that some global information like NIS must be
|
|
Packit |
6c4009 |
used. So it is unavoidable to use service entries like @code{nis} etc.
|
|
Packit |
6c4009 |
But one should avoid slow services like this if possible.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@node NSS Module Internals, Extending NSS, NSS Configuration File, Name Service Switch
|
|
Packit |
6c4009 |
@section NSS Module Internals
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Now it is time to describe what the modules look like. The functions
|
|
Packit |
6c4009 |
contained in a module are identified by their names. I.e., there is no
|
|
Packit |
6c4009 |
jump table or the like. How this is done is of no interest here; those
|
|
Packit |
6c4009 |
interested in this topic should read about Dynamic Linking.
|
|
Packit |
6c4009 |
@comment @ref{Dynamic Linking}.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@menu
|
|
Packit |
6c4009 |
* NSS Module Names:: Construction of the interface function of
|
|
Packit |
6c4009 |
the NSS modules.
|
|
Packit |
6c4009 |
* NSS Modules Interface:: Programming interface in the NSS module
|
|
Packit |
6c4009 |
functions.
|
|
Packit |
6c4009 |
@end menu
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@node NSS Module Names, NSS Modules Interface, NSS Module Internals, NSS Module Internals
|
|
Packit |
6c4009 |
@subsection The Naming Scheme of the NSS Modules
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@noindent
|
|
Packit |
6c4009 |
The name of each function consists of various parts:
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@quotation
|
|
Packit |
6c4009 |
_nss_@var{service}_@var{function}
|
|
Packit |
6c4009 |
@end quotation
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@var{service} of course corresponds to the name of the module this
|
|
Packit |
6c4009 |
function is found in.@footnote{Now you might ask why this information is
|
|
Packit |
6c4009 |
duplicated. The answer is that we want to make it possible to link
|
|
Packit |
6c4009 |
directly with these shared objects.} The @var{function} part is derived
|
|
Packit |
6c4009 |
from the interface function in the C library itself. If the user calls
|
|
Packit |
6c4009 |
the function @code{gethostbyname} and the service used is @code{files}
|
|
Packit |
6c4009 |
the function
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@smallexample
|
|
Packit |
6c4009 |
_nss_files_gethostbyname_r
|
|
Packit |
6c4009 |
@end smallexample
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@noindent
|
|
Packit |
6c4009 |
in the module
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@smallexample
|
|
Packit |
6c4009 |
libnss_files.so.2
|
|
Packit |
6c4009 |
@end smallexample
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@noindent
|
|
Packit |
6c4009 |
@cindex reentrant NSS functions
|
|
Packit |
6c4009 |
is used. You see, what is explained above in not the whole truth. In
|
|
Packit |
6c4009 |
fact the NSS modules only contain reentrant versions of the lookup
|
|
Packit |
6c4009 |
functions. I.e., if the user would call the @code{gethostbyname_r}
|
|
Packit |
6c4009 |
function this also would end in the above function. For all user
|
|
Packit |
6c4009 |
interface functions the C library maps this call to a call to the
|
|
Packit |
6c4009 |
reentrant function. For reentrant functions this is trivial since the
|
|
Packit |
6c4009 |
interface is (nearly) the same. For the non-reentrant version the
|
|
Packit |
6c4009 |
library keeps internal buffers which are used to replace the user
|
|
Packit |
6c4009 |
supplied buffer.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
I.e., the reentrant functions @emph{can} have counterparts. No service
|
|
Packit |
6c4009 |
module is forced to have functions for all databases and all kinds to
|
|
Packit |
6c4009 |
access them. If a function is not available it is simply treated as if
|
|
Packit |
6c4009 |
the function would return @code{unavail}
|
|
Packit |
6c4009 |
(@pxref{Actions in the NSS configuration}).
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The file name @file{libnss_files.so.2} would be on a @w{Solaris 2}
|
|
Packit |
6c4009 |
system @file{nss_files.so.2}. This is the difference mentioned above.
|
|
Packit |
6c4009 |
Sun's NSS modules are usable as modules which get indirectly loaded
|
|
Packit |
6c4009 |
only.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The NSS modules in @theglibc{} are prepared to be used as normal
|
|
Packit |
6c4009 |
libraries themselves. This is @emph{not} true at the moment, though.
|
|
Packit |
6c4009 |
However, the organization of the name space in the modules does not make it
|
|
Packit |
6c4009 |
impossible like it is for Solaris. Now you can see why the modules are
|
|
Packit |
6c4009 |
still libraries.@footnote{There is a second explanation: we were too
|
|
Packit |
6c4009 |
lazy to change the Makefiles to allow the generation of shared objects
|
|
Packit |
6c4009 |
not starting with @file{lib} but don't tell this to anybody.}
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@node NSS Modules Interface, , NSS Module Names, NSS Module Internals
|
|
Packit |
6c4009 |
@subsection The Interface of the Function in NSS Modules
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Now we know about the functions contained in the modules. It is now
|
|
Packit |
6c4009 |
time to describe the types. When we mentioned the reentrant versions of
|
|
Packit |
6c4009 |
the functions above, this means there are some additional arguments
|
|
Packit |
6c4009 |
(compared with the standard, non-reentrant versions). The prototypes for
|
|
Packit |
6c4009 |
the non-reentrant and reentrant versions of our function above are:
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@smallexample
|
|
Packit |
6c4009 |
struct hostent *gethostbyname (const char *name)
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
int gethostbyname_r (const char *name, struct hostent *result_buf,
|
|
Packit |
6c4009 |
char *buf, size_t buflen, struct hostent **result,
|
|
Packit |
6c4009 |
int *h_errnop)
|
|
Packit |
6c4009 |
@end smallexample
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@noindent
|
|
Packit |
6c4009 |
The actual prototype of the function in the NSS modules in this case is
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@smallexample
|
|
Packit |
6c4009 |
enum nss_status _nss_files_gethostbyname_r (const char *name,
|
|
Packit |
6c4009 |
struct hostent *result_buf,
|
|
Packit |
6c4009 |
char *buf, size_t buflen,
|
|
Packit |
6c4009 |
int *errnop, int *h_errnop)
|
|
Packit |
6c4009 |
@end smallexample
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
I.e., the interface function is in fact the reentrant function with the
|
|
Packit |
6c4009 |
change of the return value, the omission of the @var{result} parameter,
|
|
Packit |
6c4009 |
and the addition of the @var{errnop} parameter. While the user-level
|
|
Packit |
6c4009 |
function returns a pointer to the result the reentrant function return
|
|
Packit |
6c4009 |
an @code{enum nss_status} value:
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@vtable @code
|
|
Packit |
6c4009 |
@item NSS_STATUS_TRYAGAIN
|
|
Packit |
6c4009 |
numeric value @code{-2}
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item NSS_STATUS_UNAVAIL
|
|
Packit |
6c4009 |
numeric value @code{-1}
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item NSS_STATUS_NOTFOUND
|
|
Packit |
6c4009 |
numeric value @code{0}
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item NSS_STATUS_SUCCESS
|
|
Packit |
6c4009 |
numeric value @code{1}
|
|
Packit |
6c4009 |
@end vtable
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@noindent
|
|
Packit |
6c4009 |
Now you see where the action items of the @file{/etc/nsswitch.conf} file
|
|
Packit |
6c4009 |
are used.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
If you study the source code you will find there is a fifth value:
|
|
Packit |
6c4009 |
@code{NSS_STATUS_RETURN}. This is an internal use only value, used by a
|
|
Packit |
6c4009 |
few functions in places where none of the above value can be used. If
|
|
Packit |
6c4009 |
necessary the source code should be examined to learn about the details.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
In case the interface function has to return an error it is important
|
|
Packit |
6c4009 |
that the correct error code is stored in @code{*@var{errnop}}. Some
|
|
Packit |
6c4009 |
return status values have only one associated error code, others have
|
|
Packit |
6c4009 |
more.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@multitable @columnfractions .3 .2 .50
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
@code{NSS_STATUS_TRYAGAIN} @tab
|
|
Packit |
6c4009 |
@code{EAGAIN} @tab One of the functions used ran temporarily out of
|
|
Packit |
6c4009 |
resources or a service is currently not available.
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
@tab
|
|
Packit |
6c4009 |
@code{ERANGE} @tab The provided buffer is not large enough.
|
|
Packit |
6c4009 |
The function should be called again with a larger buffer.
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
@code{NSS_STATUS_UNAVAIL} @tab
|
|
Packit |
6c4009 |
@code{ENOENT} @tab A necessary input file cannot be found.
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
@code{NSS_STATUS_NOTFOUND} @tab
|
|
Packit |
6c4009 |
@code{ENOENT} @tab The requested entry is not available.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
@code{NSS_STATUS_NOTFOUND} @tab
|
|
Packit |
6c4009 |
@code{SUCCESS} @tab There are no entries.
|
|
Packit |
6c4009 |
Use this to avoid returning errors for inactive services which may
|
|
Packit |
6c4009 |
be enabled at a later time. This is not the same as the service
|
|
Packit |
6c4009 |
being temporarily unavailable.
|
|
Packit |
6c4009 |
@end multitable
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
These are proposed values. There can be other error codes and the
|
|
Packit |
6c4009 |
described error codes can have different meaning. @strong{With one
|
|
Packit |
6c4009 |
exception:} when returning @code{NSS_STATUS_TRYAGAIN} the error code
|
|
Packit |
6c4009 |
@code{ERANGE} @emph{must} mean that the user provided buffer is too
|
|
Packit |
6c4009 |
small. Everything else is non-critical.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
In statically linked programs, the main application and NSS modules do
|
|
Packit |
6c4009 |
not share the same thread-local variable @code{errno}, which is the
|
|
Packit |
6c4009 |
reason why there is an explicit @var{errnop} function argument.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The above function has something special which is missing for almost all
|
|
Packit |
6c4009 |
the other module functions. There is an argument @var{h_errnop}. This
|
|
Packit |
6c4009 |
points to a variable which will be filled with the error code in case
|
|
Packit |
6c4009 |
the execution of the function fails for some reason. (In statically
|
|
Packit |
6c4009 |
linked programs, the thread-local variable @code{h_errno} is not shared
|
|
Packit |
6c4009 |
with the main application.)
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The @code{get@var{XXX}by@var{YYY}} functions are the most important
|
|
Packit |
6c4009 |
functions in the NSS modules. But there are others which implement
|
|
Packit |
6c4009 |
the other ways to access system databases (say for the
|
|
Packit |
6c4009 |
user database, there are @code{setpwent}, @code{getpwent}, and
|
|
Packit |
6c4009 |
@code{endpwent}). These will be described in more detail later.
|
|
Packit |
6c4009 |
Here we give a general way to determine the
|
|
Packit |
6c4009 |
signature of the module function:
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@itemize @bullet
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
the return value is @code{enum nss_status};
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
the name (@pxref{NSS Module Names});
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
the first arguments are identical to the arguments of the non-reentrant
|
|
Packit |
6c4009 |
function;
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
the next four arguments are:
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@table @code
|
|
Packit |
6c4009 |
@item STRUCT_TYPE *result_buf
|
|
Packit |
6c4009 |
pointer to buffer where the result is stored. @code{STRUCT_TYPE} is
|
|
Packit |
6c4009 |
normally a struct which corresponds to the database.
|
|
Packit |
6c4009 |
@item char *buffer
|
|
Packit |
6c4009 |
pointer to a buffer where the function can store additional data for
|
|
Packit |
6c4009 |
the result etc.
|
|
Packit |
6c4009 |
@item size_t buflen
|
|
Packit |
6c4009 |
length of the buffer pointed to by @var{buffer}.
|
|
Packit |
6c4009 |
@item int *errnop
|
|
Packit |
6c4009 |
the low-level error code to return to the application. If the return
|
|
Packit |
6c4009 |
value is not @code{NSS_STATUS_SUCCESS}, @code{*@var{errnop}} needs to be
|
|
Packit |
6c4009 |
set to a non-zero value. An NSS module should never set
|
|
Packit |
6c4009 |
@code{*@var{errnop}} to zero. The value @code{ERANGE} is special, as
|
|
Packit |
6c4009 |
described above.
|
|
Packit |
6c4009 |
@end table
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
possibly a last argument @var{h_errnop}, for the host name and network
|
|
Packit |
6c4009 |
name lookup functions. If the return value is not
|
|
Packit |
6c4009 |
@code{NSS_STATUS_SUCCESS}, @code{*@var{h_errnop}} needs to be set to a
|
|
Packit |
6c4009 |
non-zero value. A generic error code is @code{NETDB_INTERNAL}, which
|
|
Packit |
6c4009 |
instructs the caller to examine @code{*@var{errnop}} for further
|
|
Packit |
6c4009 |
details. (This includes the @code{ERANGE} special case.)
|
|
Packit |
6c4009 |
@end itemize
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@noindent
|
|
Packit |
6c4009 |
This table is correct for all functions but the @code{set@dots{}ent}
|
|
Packit |
6c4009 |
and @code{end@dots{}ent} functions.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@node Extending NSS, , NSS Module Internals, Name Service Switch
|
|
Packit |
6c4009 |
@section Extending NSS
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
One of the advantages of NSS mentioned above is that it can be extended
|
|
Packit |
6c4009 |
quite easily. There are two ways in which the extension can happen:
|
|
Packit |
6c4009 |
adding another database or adding another service. The former is
|
|
Packit |
6c4009 |
normally done only by the C library developers. It is
|
|
Packit |
6c4009 |
here only important to remember that adding another database is
|
|
Packit |
6c4009 |
independent from adding another service because a service need not
|
|
Packit |
6c4009 |
support all databases or lookup functions.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
A designer/implementer of a new service is therefore free to choose the
|
|
Packit |
6c4009 |
databases s/he is interested in and leave the rest for later (or
|
|
Packit |
6c4009 |
completely aside).
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@menu
|
|
Packit |
6c4009 |
* Adding another Service to NSS:: What is to do to add a new service.
|
|
Packit |
6c4009 |
* NSS Module Function Internals:: Guidelines for writing new NSS
|
|
Packit |
6c4009 |
service functions.
|
|
Packit |
6c4009 |
@end menu
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@node Adding another Service to NSS, NSS Module Function Internals, Extending NSS, Extending NSS
|
|
Packit |
6c4009 |
@subsection Adding another Service to NSS
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The sources for a new service need not (and should not) be part of @theglibc{}
|
|
Packit |
6c4009 |
itself. The developer retains complete control over the
|
|
Packit |
6c4009 |
sources and its development. The links between the C library and the
|
|
Packit |
6c4009 |
new service module consists solely of the interface functions.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Each module is designed following a specific interface specification.
|
|
Packit |
6c4009 |
For now the version is 2 (the interface in version 1 was not adequate)
|
|
Packit |
6c4009 |
and this manifests in the version number of the shared library object of
|
|
Packit |
6c4009 |
the NSS modules: they have the extension @code{.2}. If the interface
|
|
Packit |
6c4009 |
changes again in an incompatible way, this number will be increased.
|
|
Packit |
6c4009 |
Modules using the old interface will still be usable.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Developers of a new service will have to make sure that their module is
|
|
Packit |
6c4009 |
created using the correct interface number. This means the file itself
|
|
Packit |
6c4009 |
must have the correct name and on ELF systems the @dfn{soname} (Shared
|
|
Packit |
6c4009 |
Object Name) must also have this number. Building a module from a bunch
|
|
Packit |
6c4009 |
of object files on an ELF system using GNU CC could be done like this:
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@smallexample
|
|
Packit |
6c4009 |
gcc -shared -o libnss_NAME.so.2 -Wl,-soname,libnss_NAME.so.2 OBJECTS
|
|
Packit |
6c4009 |
@end smallexample
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@noindent
|
|
Packit |
6c4009 |
@ref{Link Options, Options for Linking, , gcc, GNU CC}, to learn
|
|
Packit |
6c4009 |
more about this command line.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
To use the new module the library must be able to find it. This can be
|
|
Packit |
6c4009 |
achieved by using options for the dynamic linker so that it will search
|
|
Packit |
6c4009 |
the directory where the binary is placed. For an ELF system this could be
|
|
Packit |
6c4009 |
done by adding the wanted directory to the value of
|
|
Packit |
6c4009 |
@code{LD_LIBRARY_PATH}.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
But this is not always possible since some programs (those which run
|
|
Packit |
6c4009 |
under IDs which do not belong to the user) ignore this variable.
|
|
Packit |
6c4009 |
Therefore the stable version of the module should be placed into a
|
|
Packit |
6c4009 |
directory which is searched by the dynamic linker. Normally this should
|
|
Packit |
6c4009 |
be the directory @file{$prefix/lib}, where @file{$prefix} corresponds to
|
|
Packit |
6c4009 |
the value given to configure using the @code{--prefix} option. But be
|
|
Packit |
6c4009 |
careful: this should only be done if it is clear the module does not
|
|
Packit |
6c4009 |
cause any harm. System administrators should be careful.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@node NSS Module Function Internals, , Adding another Service to NSS, Extending NSS
|
|
Packit |
6c4009 |
@subsection Internals of the NSS Module Functions
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Until now we only provided the syntactic interface for the functions in
|
|
Packit |
6c4009 |
the NSS module. In fact there is not much more we can say since the
|
|
Packit |
6c4009 |
implementation obviously is different for each function. But a few
|
|
Packit |
6c4009 |
general rules must be followed by all functions.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
In fact there are four kinds of different functions which may appear in
|
|
Packit |
6c4009 |
the interface. All derive from the traditional ones for system databases.
|
|
Packit |
6c4009 |
@var{db} in the following table is normally an abbreviation for the
|
|
Packit |
6c4009 |
database (e.g., it is @code{pw} for the user database).
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@table @code
|
|
Packit |
6c4009 |
@item enum nss_status _nss_@var{database}_set@var{db}ent (void)
|
|
Packit |
6c4009 |
This function prepares the service for following operations. For a
|
|
Packit |
6c4009 |
simple file based lookup this means files could be opened, for other
|
|
Packit |
6c4009 |
services this function simply is a noop.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
One special case for this function is that it takes an additional
|
|
Packit |
6c4009 |
argument for some @var{database}s (i.e., the interface is
|
|
Packit |
6c4009 |
@code{int set@var{db}ent (int)}). @ref{Host Names}, which describes the
|
|
Packit |
6c4009 |
@code{sethostent} function.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The return value should be @var{NSS_STATUS_SUCCESS} or according to the
|
|
Packit |
6c4009 |
table above in case of an error (@pxref{NSS Modules Interface}).
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item enum nss_status _nss_@var{database}_end@var{db}ent (void)
|
|
Packit |
6c4009 |
This function simply closes all files which are still open or removes
|
|
Packit |
6c4009 |
buffer caches. If there are no files or buffers to remove this is again
|
|
Packit |
6c4009 |
a simple noop.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
There normally is no return value other than @var{NSS_STATUS_SUCCESS}.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item enum nss_status _nss_@var{database}_get@var{db}ent_r (@var{STRUCTURE} *result, char *buffer, size_t buflen, int *errnop)
|
|
Packit |
6c4009 |
Since this function will be called several times in a row to retrieve
|
|
Packit |
6c4009 |
one entry after the other it must keep some kind of state. But this
|
|
Packit |
6c4009 |
also means the functions are not really reentrant. They are reentrant
|
|
Packit |
6c4009 |
only in that simultaneous calls to this function will not try to
|
|
Packit |
6c4009 |
write the retrieved data in the same place (as it would be the case for
|
|
Packit |
6c4009 |
the non-reentrant functions); instead, it writes to the structure
|
|
Packit |
6c4009 |
pointed to by the @var{result} parameter. But the calls share a common
|
|
Packit |
6c4009 |
state and in the case of a file access this means they return neighboring
|
|
Packit |
6c4009 |
entries in the file.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The buffer of length @var{buflen} pointed to by @var{buffer} can be used
|
|
Packit |
6c4009 |
for storing some additional data for the result. It is @emph{not}
|
|
Packit |
6c4009 |
guaranteed that the same buffer will be passed for the next call of this
|
|
Packit |
6c4009 |
function. Therefore one must not misuse this buffer to save some state
|
|
Packit |
6c4009 |
information from one call to another.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Before the function returns with a failure code, the implementation
|
|
Packit |
6c4009 |
should store the value of the local @var{errno} variable in the variable
|
|
Packit |
6c4009 |
pointed to be @var{errnop}. This is important to guarantee the module
|
|
Packit |
6c4009 |
working in statically linked programs. The stored value must not be
|
|
Packit |
6c4009 |
zero.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
As explained above this function could also have an additional last
|
|
Packit |
6c4009 |
argument. This depends on the database used; it happens only for
|
|
Packit |
6c4009 |
@code{host} and @code{networks}.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The function shall return @code{NSS_STATUS_SUCCESS} as long as there are
|
|
Packit |
6c4009 |
more entries. When the last entry was read it should return
|
|
Packit |
6c4009 |
@code{NSS_STATUS_NOTFOUND}. When the buffer given as an argument is too
|
|
Packit |
6c4009 |
small for the data to be returned @code{NSS_STATUS_TRYAGAIN} should be
|
|
Packit |
6c4009 |
returned. When the service was not formerly initialized by a call to
|
|
Packit |
6c4009 |
@code{_nss_@var{DATABASE}_set@var{db}ent} all return values allowed for
|
|
Packit |
6c4009 |
this function can also be returned here.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item enum nss_status _nss_@var{DATABASE}_get@var{db}by@var{XX}_r (@var{PARAMS}, @var{STRUCTURE} *result, char *buffer, size_t buflen, int *errnop)
|
|
Packit |
6c4009 |
This function shall return the entry from the database which is
|
|
Packit |
6c4009 |
addressed by the @var{PARAMS}. The type and number of these arguments
|
|
Packit |
6c4009 |
vary. It must be individually determined by looking to the user-level
|
|
Packit |
6c4009 |
interface functions. All arguments given to the non-reentrant version
|
|
Packit |
6c4009 |
are here described by @var{PARAMS}.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The result must be stored in the structure pointed to by @var{result}.
|
|
Packit |
6c4009 |
If there are additional data to return (say strings, where the
|
|
Packit |
6c4009 |
@var{result} structure only contains pointers) the function must use the
|
|
Packit |
6c4009 |
@var{buffer} of length @var{buflen}. There must not be any references
|
|
Packit |
6c4009 |
to non-constant global data.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The implementation of this function should honor the @var{stayopen}
|
|
Packit |
6c4009 |
flag set by the @code{set@var{DB}ent} function whenever this makes sense.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Before the function returns, the implementation should store the value of
|
|
Packit |
6c4009 |
the local @var{errno} variable in the variable pointed to by
|
|
Packit |
6c4009 |
@var{errnop}. This is important to guarantee the module works in
|
|
Packit |
6c4009 |
statically linked programs.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Again, this function takes an additional last argument for the
|
|
Packit |
6c4009 |
@code{host} and @code{networks} database.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The return value should as always follow the rules given above
|
|
Packit |
6c4009 |
(@pxref{NSS Modules Interface}).
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@end table
|