]>
Commit | Line | Data |
---|---|---|
7a68c94a | 1 | @node Name Service Switch, Users and Groups, Job Control, Top |
706074a5 | 2 | @chapter System Databases and Name Service Switch |
7a68c94a | 3 | @c %MENU% Accessing system databases |
2c6fe0bd UD |
4 | @cindex Name Service Switch |
5 | @cindex NSS | |
6d52618b | 6 | @cindex databases |
7a68c94a | 7 | |
706074a5 UD |
8 | Various functions in the C Library need to be configured to work |
9 | correctly in the local environment. Traditionally, this was done by | |
6952e59e | 10 | using files (e.g., @file{/etc/passwd}), but other nameservices (like the |
706074a5 UD |
11 | Network Information Service (NIS) and the Domain Name Service (DNS)) |
12 | became popular, and were hacked into the C library, usually with a fixed | |
41f49342 | 13 | search order. |
706074a5 | 14 | |
5455692a | 15 | @Theglibc{} contains a cleaner solution to this problem. It is |
706074a5 | 16 | designed after a method used by Sun Microsystems in the C library of |
1f77f049 | 17 | @w{Solaris 2}. @Theglibc{} follows their name and calls this |
706074a5 UD |
18 | scheme @dfn{Name Service Switch} (NSS). |
19 | ||
20 | Though the interface might be similar to Sun's version there is no | |
21 | common code. We never saw any source code of Sun's implementation and | |
6952e59e | 22 | so the internal interface is incompatible. This also manifests in the |
706074a5 UD |
23 | file names we use as we will see later. |
24 | ||
25 | ||
26 | @menu | |
27 | * NSS Basics:: What is this NSS good for. | |
28 | * NSS Configuration File:: Configuring NSS. | |
29 | * NSS Module Internals:: How does it work internally. | |
30 | * Extending NSS:: What to do to add services or databases. | |
31 | @end menu | |
32 | ||
33 | @node NSS Basics, NSS Configuration File, Name Service Switch, Name Service Switch | |
34 | @section NSS Basics | |
35 | ||
36 | The basic idea is to put the implementation of the different services | |
37 | offered to access the databases in separate modules. This has some | |
38 | advantages: | |
39 | ||
40 | @enumerate | |
41 | @item | |
1f77f049 | 42 | Contributors can add new services without adding them to @theglibc{}. |
706074a5 UD |
43 | @item |
44 | The modules can be updated separately. | |
45 | @item | |
46 | The C library image is smaller. | |
47 | @end enumerate | |
48 | ||
5455692a | 49 | To fulfill the first goal above, the ABI of the modules will be described |
706074a5 UD |
50 | below. For getting the implementation of a new service right it is |
51 | important to understand how the functions in the modules get called. | |
52 | They are in no way designed to be used by the programmer directly. | |
53 | Instead the programmer should only use the documented and standardized | |
54 | functions to access the databases. | |
55 | ||
56 | @noindent | |
57 | The databases available in the NSS are | |
58 | ||
4b7c7417 | 59 | @cindex aliases |
706074a5 UD |
60 | @cindex ethers |
61 | @cindex group | |
4b7c7417 | 62 | @cindex gshadow |
706074a5 | 63 | @cindex hosts |
4b7c7417 | 64 | @cindex initgroups |
ba1ffaa1 | 65 | @cindex netgroup |
b3a86ae1 | 66 | @cindex networks |
706074a5 | 67 | @cindex passwd |
4b7c7417 CD |
68 | @cindex protocols |
69 | @cindex publickey | |
706074a5 UD |
70 | @cindex rpc |
71 | @cindex services | |
72 | @cindex shadow | |
2fe82ca6 | 73 | @table @code |
26dee9c4 UD |
74 | @item aliases |
75 | Mail aliases | |
76 | @comment @pxref{Mail Aliases}. | |
706074a5 UD |
77 | @item ethers |
78 | Ethernet numbers, | |
79 | @comment @pxref{Ethernet Numbers}. | |
80 | @item group | |
81 | Groups of users, @pxref{Group Database}. | |
4b7c7417 CD |
82 | @item gshadow |
83 | Group passphrase hashes and related information. | |
706074a5 UD |
84 | @item hosts |
85 | Host names and numbers, @pxref{Host Names}. | |
4b7c7417 CD |
86 | @item initgroups |
87 | Supplementary group access list. | |
ba1ffaa1 UD |
88 | @item netgroup |
89 | Network wide list of host and users, @pxref{Netgroup Database}. | |
b3a86ae1 | 90 | @item networks |
706074a5 | 91 | Network names and numbers, @pxref{Networks Database}. |
706074a5 | 92 | @item passwd |
841785ba | 93 | User identities, @pxref{User Database}. |
4b7c7417 CD |
94 | @item protocols |
95 | Network protocols, @pxref{Protocols Database}. | |
96 | @item publickey | |
97 | Public keys for Secure RPC. | |
706074a5 | 98 | @item rpc |
841785ba | 99 | Remote procedure call names and numbers. |
706074a5 UD |
100 | @comment @pxref{RPC Database}. |
101 | @item services | |
102 | Network services, @pxref{Services Database}. | |
103 | @item shadow | |
841785ba ZW |
104 | User passphrase hashes and related information. |
105 | @comment @pxref{Shadow Passphrase Database}. | |
2fe82ca6 | 106 | @end table |
706074a5 UD |
107 | |
108 | @noindent | |
4b7c7417 CD |
109 | @c We currently don't implement automount, netmasks, or bootparams. |
110 | More databases may be added later. | |
706074a5 UD |
111 | |
112 | @node NSS Configuration File, NSS Module Internals, NSS Basics, Name Service Switch | |
113 | @section The NSS Configuration File | |
114 | ||
115 | @cindex @file{/etc/nsswitch.conf} | |
116 | @cindex @file{nsswitch.conf} | |
117 | Somehow the NSS code must be told about the wishes of the user. For | |
118 | this reason there is the file @file{/etc/nsswitch.conf}. For each | |
5455692a | 119 | database, this file contains a specification of how the lookup process should |
706074a5 UD |
120 | work. The file could look like this: |
121 | ||
122 | @example | |
123 | @include nsswitch.texi | |
124 | @end example | |
125 | ||
126 | The first column is the database as you can guess from the table above. | |
127 | The rest of the line specifies how the lookup process works. Please | |
128 | note that you specify the way it works for each database individually. | |
129 | This cannot be done with the old way of a monolithic implementation. | |
130 | ||
131 | The configuration specification for each database can contain two | |
132 | different items: | |
133 | ||
134 | @itemize @bullet | |
135 | @item | |
136 | the service specification like @code{files}, @code{db}, or @code{nis}. | |
137 | @item | |
26dee9c4 | 138 | the reaction on lookup result like @code{[NOTFOUND=return]}. |
706074a5 UD |
139 | @end itemize |
140 | ||
141 | @menu | |
ba1ffaa1 | 142 | * Services in the NSS configuration:: Service names in the NSS configuration. |
6d52618b | 143 | * Actions in the NSS configuration:: React appropriately to the lookup result. |
706074a5 UD |
144 | * Notes on NSS Configuration File:: Things to take care about while |
145 | configuring NSS. | |
146 | @end menu | |
147 | ||
148 | @node Services in the NSS configuration, Actions in the NSS configuration, NSS Configuration File, NSS Configuration File | |
149 | @subsection Services in the NSS configuration File | |
150 | ||
16d2c631 JM |
151 | The above example file mentions five different services: @code{files}, |
152 | @code{db}, @code{dns}, @code{nis}, and @code{nisplus}. This does not | |
153 | mean these | |
5455692a | 154 | services are available on all sites and neither does it mean these are |
706074a5 UD |
155 | all the services which will ever be available. |
156 | ||
157 | In fact, these names are simply strings which the NSS code uses to find | |
158 | the implicitly addressed functions. The internal interface will be | |
159 | described later. Visible to the user are the modules which implement an | |
160 | individual service. | |
161 | ||
162 | Assume the service @var{name} shall be used for a lookup. The code for | |
163 | this service is implemented in a module called @file{libnss_@var{name}}. | |
164 | On a system supporting shared libraries this is in fact a shared library | |
c66dbe00 | 165 | with the name (for example) @file{libnss_@var{name}.so.2}. The number |
706074a5 UD |
166 | at the end is the currently used version of the interface which will not |
167 | change frequently. Normally the user should not have to be cognizant of | |
168 | these files since they should be placed in a directory where they are | |
169 | found automatically. Only the names of all available services are | |
170 | important. | |
171 | ||
4b7c7417 CD |
172 | Lastly, some system software may make use of the NSS configuration file |
173 | to store their own configuration for similar purposes. Examples of this | |
174 | include the @code{automount} service which is used by @code{autofs}. | |
175 | ||
706074a5 UD |
176 | @node Actions in the NSS configuration, Notes on NSS Configuration File, Services in the NSS configuration, NSS Configuration File |
177 | @subsection Actions in the NSS configuration | |
178 | ||
179 | The second item in the specification gives the user much finer control | |
180 | on the lookup process. Action items are placed between two service | |
181 | names and are written within brackets. The general form is | |
182 | ||
2de99474 | 183 | @display |
57ba7bb4 | 184 | @code{[} ( @code{!}? @var{status} @code{=} @var{action} )+ @code{]} |
2de99474 | 185 | @end display |
706074a5 UD |
186 | |
187 | @noindent | |
188 | where | |
189 | ||
190 | @smallexample | |
191 | @var{status} @result{} success | notfound | unavail | tryagain | |
192 | @var{action} @result{} return | continue | |
193 | @end smallexample | |
194 | ||
195 | The case of the keywords is insignificant. The @var{status} | |
196 | values are the results of a call to a lookup function of a specific | |
ced8f893 | 197 | service. They mean: |
706074a5 UD |
198 | |
199 | @ftable @samp | |
200 | @item success | |
6d52618b | 201 | No error occurred and the wanted entry is returned. The default action |
706074a5 UD |
202 | for this is @code{return}. |
203 | ||
204 | @item notfound | |
205 | The lookup process works ok but the needed value was not found. The | |
206 | default action is @code{continue}. | |
207 | ||
208 | @item unavail | |
209 | @cindex DNS server unavailable | |
210 | The service is permanently unavailable. This can either mean the needed | |
211 | file is not available, or, for DNS, the server is not available or does | |
212 | not allow queries. The default action is @code{continue}. | |
213 | ||
214 | @item tryagain | |
215 | The service is temporarily unavailable. This could mean a file is | |
216 | locked or a server currently cannot accept more connections. The | |
217 | default action is @code{continue}. | |
218 | @end ftable | |
219 | ||
ced8f893 SG |
220 | @noindent |
221 | The @var{action} values mean: | |
222 | ||
223 | @ftable @samp | |
224 | @item return | |
225 | ||
226 | If the status matches, stop the lookup process at this service | |
227 | specification. If an entry is available, provide it to the application. | |
228 | If an error occurred, report it to the application. In case of a prior | |
229 | @samp{merge} action, the data is combined with previous lookup results, | |
230 | as explained below. | |
231 | ||
232 | @item continue | |
233 | ||
234 | If the status matches, proceed with the lookup process at the next | |
235 | entry, discarding the result of the current lookup (and any merged | |
236 | data). An exception is the @samp{initgroups} database and the | |
237 | @samp{success} status, where @samp{continue} acts like @code{merge} | |
238 | below. | |
239 | ||
240 | @item merge | |
241 | ||
242 | Proceed with the lookup process, retaining the current lookup result. | |
243 | This action is useful only with the @samp{success} status. If a | |
244 | subsequent service lookup succeeds and has a matching @samp{return} | |
245 | specification, the results are merged, the lookup process ends, and the | |
246 | merged results are returned to the application. If the following service | |
247 | has a matching @samp{merge} action, the lookup process continues, | |
248 | retaining the combined data from this and any previous lookups. | |
249 | ||
250 | After a @code{merge} action, errors from subsequent lookups are ignored, | |
251 | and the data gathered so far will be returned. | |
252 | ||
253 | The @samp{merge} only applies to the @samp{success} status. It is | |
254 | currently implemented for the @samp{group} database and its group | |
255 | members field, @samp{gr_mem}. If specified for other databases, it | |
256 | causes the lookup to fail (if the @var{status} matches). | |
257 | ||
258 | When processing @samp{merge} for @samp{group} membership, the group GID | |
259 | and name must be identical for both entries. If only one or the other is | |
260 | a match, the behavior is undefined. | |
261 | ||
262 | @end ftable | |
263 | ||
706074a5 UD |
264 | @noindent |
265 | If we have a line like | |
266 | ||
267 | @smallexample | |
268 | ethers: nisplus [NOTFOUND=return] db files | |
269 | @end smallexample | |
270 | ||
271 | @noindent | |
272 | this is equivalent to | |
273 | ||
274 | @smallexample | |
275 | ethers: nisplus [SUCCESS=return NOTFOUND=return UNAVAIL=continue | |
276 | TRYAGAIN=continue] | |
277 | db [SUCCESS=return NOTFOUND=continue UNAVAIL=continue | |
278 | TRYAGAIN=continue] | |
279 | files | |
280 | @end smallexample | |
281 | ||
282 | @noindent | |
283 | (except that it would have to be written on one line). The default | |
284 | value for the actions are normally what you want, and only need to be | |
285 | changed in exceptional cases. | |
286 | ||
287 | If the optional @code{!} is placed before the @var{status} this means | |
4f8dbcb1 | 288 | the following action is used for all statuses but @var{status} itself. |
706074a5 UD |
289 | I.e., @code{!} is negation as in the C language (and others). |
290 | ||
291 | Before we explain the exception which makes this action item necessary | |
292 | one more remark: obviously it makes no sense to add another action | |
293 | item after the @code{files} service. Since there is no other service | |
294 | following the action @emph{always} is @code{return}. | |
295 | ||
296 | @cindex nisplus, and completeness | |
297 | Now, why is this @code{[NOTFOUND=return]} action useful? To understand | |
298 | this we should know that the @code{nisplus} service is often | |
299 | complete; i.e., if an entry is not available in the NIS+ tables it is | |
300 | not available anywhere else. This is what is expressed by this action | |
301 | item: it is useless to examine further services since they will not give | |
302 | us a result. | |
303 | ||
304 | @cindex nisplus, and booting | |
305 | @cindex bootstrapping, and services | |
306 | The situation would be different if the NIS+ service is not available | |
307 | because the machine is booting. In this case the return value of the | |
308 | lookup function is not @code{notfound} but instead @code{unavail}. And | |
309 | as you can see in the complete form above: in this situation the | |
310 | @code{db} and @code{files} services are used. Neat, isn't it? The | |
311 | system administrator need not pay special care for the time the system | |
312 | is not completely ready to work (while booting or shutdown or | |
313 | network problems). | |
314 | ||
315 | ||
316 | @node Notes on NSS Configuration File, , Actions in the NSS configuration, NSS Configuration File | |
317 | @subsection Notes on the NSS Configuration File | |
318 | ||
319 | Finally a few more hints. The NSS implementation is not completely | |
320 | helpless if @file{/etc/nsswitch.conf} does not exist. For | |
321 | all supported databases there is a default value so it should normally | |
322 | be possible to get the system running even if the file is corrupted or | |
323 | missing. | |
324 | ||
ba1ffaa1 | 325 | @cindex default value, and NSS |
b3a86ae1 | 326 | For the @code{hosts} and @code{networks} databases the default value is |
ba1ffaa1 UD |
327 | @code{dns [!UNAVAIL=return] files}. I.e., the system is prepared for |
328 | the DNS service not to be available but if it is available the answer it | |
04b9968b | 329 | returns is definitive. |
ba1ffaa1 | 330 | |
ae7a94e5 | 331 | The @code{passwd}, @code{group}, and @code{shadow} databases was |
10dc2a90 | 332 | traditionally handled in a special way. The appropriate files in the |
ae7a94e5 PV |
333 | @file{/etc} directory were read but if an entry with a name starting |
334 | with a @code{+} character was found NIS was used. This kind of lookup | |
335 | was removed and now the default value for the services is @code{files}. | |
336 | libnss_compat no longer depends on libnsl and can be used without NIS. | |
a1a78204 | 337 | |
5500cdba | 338 | For all other databases the default value is @code{files}. |
ba1ffaa1 UD |
339 | |
340 | @cindex optimizing NSS | |
706074a5 | 341 | A second point is that the user should try to optimize the lookup |
10dc2a90 UD |
342 | process. The different service have different response times. |
343 | A simple file look up on a local file could be fast, but if the file | |
344 | is long and the needed entry is near the end of the file this may take | |
345 | quite some time. In this case it might be better to use the @code{db} | |
346 | service which allows fast local access to large data sets. | |
706074a5 UD |
347 | |
348 | Often the situation is that some global information like NIS must be | |
349 | used. So it is unavoidable to use service entries like @code{nis} etc. | |
350 | But one should avoid slow services like this if possible. | |
351 | ||
352 | ||
353 | @node NSS Module Internals, Extending NSS, NSS Configuration File, Name Service Switch | |
354 | @section NSS Module Internals | |
355 | ||
04b9968b | 356 | Now it is time to describe what the modules look like. The functions |
706074a5 UD |
357 | contained in a module are identified by their names. I.e., there is no |
358 | jump table or the like. How this is done is of no interest here; those | |
359 | interested in this topic should read about Dynamic Linking. | |
360 | @comment @ref{Dynamic Linking}. | |
361 | ||
362 | ||
363 | @menu | |
364 | * NSS Module Names:: Construction of the interface function of | |
365 | the NSS modules. | |
366 | * NSS Modules Interface:: Programming interface in the NSS module | |
367 | functions. | |
368 | @end menu | |
369 | ||
370 | @node NSS Module Names, NSS Modules Interface, NSS Module Internals, NSS Module Internals | |
371 | @subsection The Naming Scheme of the NSS Modules | |
372 | ||
373 | @noindent | |
5455692a | 374 | The name of each function consists of various parts: |
706074a5 UD |
375 | |
376 | @quotation | |
377 | _nss_@var{service}_@var{function} | |
378 | @end quotation | |
379 | ||
380 | @var{service} of course corresponds to the name of the module this | |
04b9968b UD |
381 | function is found in.@footnote{Now you might ask why this information is |
382 | duplicated. The answer is that we want to make it possible to link | |
706074a5 UD |
383 | directly with these shared objects.} The @var{function} part is derived |
384 | from the interface function in the C library itself. If the user calls | |
385 | the function @code{gethostbyname} and the service used is @code{files} | |
386 | the function | |
387 | ||
388 | @smallexample | |
389 | _nss_files_gethostbyname_r | |
390 | @end smallexample | |
391 | ||
392 | @noindent | |
393 | in the module | |
394 | ||
395 | @smallexample | |
c66dbe00 | 396 | libnss_files.so.2 |
706074a5 UD |
397 | @end smallexample |
398 | ||
399 | @noindent | |
400 | @cindex reentrant NSS functions | |
401 | is used. You see, what is explained above in not the whole truth. In | |
402 | fact the NSS modules only contain reentrant versions of the lookup | |
403 | functions. I.e., if the user would call the @code{gethostbyname_r} | |
404 | function this also would end in the above function. For all user | |
405 | interface functions the C library maps this call to a call to the | |
406 | reentrant function. For reentrant functions this is trivial since the | |
5455692a | 407 | interface is (nearly) the same. For the non-reentrant version the |
26dee9c4 UD |
408 | library keeps internal buffers which are used to replace the user |
409 | supplied buffer. | |
706074a5 UD |
410 | |
411 | I.e., the reentrant functions @emph{can} have counterparts. No service | |
412 | module is forced to have functions for all databases and all kinds to | |
413 | access them. If a function is not available it is simply treated as if | |
414 | the function would return @code{unavail} | |
415 | (@pxref{Actions in the NSS configuration}). | |
416 | ||
c66dbe00 UD |
417 | The file name @file{libnss_files.so.2} would be on a @w{Solaris 2} |
418 | system @file{nss_files.so.2}. This is the difference mentioned above. | |
2de99474 UD |
419 | Sun's NSS modules are usable as modules which get indirectly loaded |
420 | only. | |
421 | ||
1f77f049 | 422 | The NSS modules in @theglibc{} are prepared to be used as normal |
b642f101 | 423 | libraries themselves. This is @emph{not} true at the moment, though. |
04b9968b | 424 | However, the organization of the name space in the modules does not make it |
2de99474 UD |
425 | impossible like it is for Solaris. Now you can see why the modules are |
426 | still libraries.@footnote{There is a second explanation: we were too | |
427 | lazy to change the Makefiles to allow the generation of shared objects | |
04b9968b | 428 | not starting with @file{lib} but don't tell this to anybody.} |
2de99474 | 429 | |
706074a5 UD |
430 | |
431 | @node NSS Modules Interface, , NSS Module Names, NSS Module Internals | |
432 | @subsection The Interface of the Function in NSS Modules | |
433 | ||
434 | Now we know about the functions contained in the modules. It is now | |
435 | time to describe the types. When we mentioned the reentrant versions of | |
436 | the functions above, this means there are some additional arguments | |
5455692a | 437 | (compared with the standard, non-reentrant versions). The prototypes for |
706074a5 UD |
438 | the non-reentrant and reentrant versions of our function above are: |
439 | ||
440 | @smallexample | |
441 | struct hostent *gethostbyname (const char *name) | |
442 | ||
a18f587d UD |
443 | int gethostbyname_r (const char *name, struct hostent *result_buf, |
444 | char *buf, size_t buflen, struct hostent **result, | |
445 | int *h_errnop) | |
706074a5 UD |
446 | @end smallexample |
447 | ||
448 | @noindent | |
ba1ffaa1 | 449 | The actual prototype of the function in the NSS modules in this case is |
706074a5 UD |
450 | |
451 | @smallexample | |
ba1ffaa1 UD |
452 | enum nss_status _nss_files_gethostbyname_r (const char *name, |
453 | struct hostent *result_buf, | |
a18f587d | 454 | char *buf, size_t buflen, |
c66dbe00 | 455 | int *errnop, int *h_errnop) |
706074a5 UD |
456 | @end smallexample |
457 | ||
ba1ffaa1 | 458 | I.e., the interface function is in fact the reentrant function with the |
3a35923e FW |
459 | change of the return value, the omission of the @var{result} parameter, |
460 | and the addition of the @var{errnop} parameter. While the user-level | |
461 | function returns a pointer to the result the reentrant function return | |
462 | an @code{enum nss_status} value: | |
706074a5 | 463 | |
b642f101 | 464 | @vtable @code |
706074a5 UD |
465 | @item NSS_STATUS_TRYAGAIN |
466 | numeric value @code{-2} | |
467 | ||
468 | @item NSS_STATUS_UNAVAIL | |
469 | numeric value @code{-1} | |
470 | ||
471 | @item NSS_STATUS_NOTFOUND | |
472 | numeric value @code{0} | |
473 | ||
474 | @item NSS_STATUS_SUCCESS | |
475 | numeric value @code{1} | |
b642f101 | 476 | @end vtable |
706074a5 UD |
477 | |
478 | @noindent | |
479 | Now you see where the action items of the @file{/etc/nsswitch.conf} file | |
480 | are used. | |
481 | ||
ba1ffaa1 UD |
482 | If you study the source code you will find there is a fifth value: |
483 | @code{NSS_STATUS_RETURN}. This is an internal use only value, used by a | |
484 | few functions in places where none of the above value can be used. If | |
485 | necessary the source code should be examined to learn about the details. | |
486 | ||
7be8096f UD |
487 | In case the interface function has to return an error it is important |
488 | that the correct error code is stored in @code{*@var{errnop}}. Some | |
5455692a | 489 | return status values have only one associated error code, others have |
7be8096f UD |
490 | more. |
491 | ||
492 | @multitable @columnfractions .3 .2 .50 | |
493 | @item | |
494 | @code{NSS_STATUS_TRYAGAIN} @tab | |
04b9968b | 495 | @code{EAGAIN} @tab One of the functions used ran temporarily out of |
7be8096f UD |
496 | resources or a service is currently not available. |
497 | @item | |
498 | @tab | |
499 | @code{ERANGE} @tab The provided buffer is not large enough. | |
500 | The function should be called again with a larger buffer. | |
501 | @item | |
502 | @code{NSS_STATUS_UNAVAIL} @tab | |
503 | @code{ENOENT} @tab A necessary input file cannot be found. | |
504 | @item | |
505 | @code{NSS_STATUS_NOTFOUND} @tab | |
506 | @code{ENOENT} @tab The requested entry is not available. | |
d4e301c5 CD |
507 | |
508 | @item | |
509 | @code{NSS_STATUS_NOTFOUND} @tab | |
510 | @code{SUCCESS} @tab There are no entries. | |
511 | Use this to avoid returning errors for inactive services which may | |
512 | be enabled at a later time. This is not the same as the service | |
513 | being temporarily unavailable. | |
7be8096f UD |
514 | @end multitable |
515 | ||
516 | These are proposed values. There can be other error codes and the | |
517 | described error codes can have different meaning. @strong{With one | |
518 | exception:} when returning @code{NSS_STATUS_TRYAGAIN} the error code | |
519 | @code{ERANGE} @emph{must} mean that the user provided buffer is too | |
5455692a | 520 | small. Everything else is non-critical. |
7be8096f | 521 | |
3a35923e FW |
522 | In statically linked programs, the main application and NSS modules do |
523 | not share the same thread-local variable @code{errno}, which is the | |
524 | reason why there is an explicit @var{errnop} function argument. | |
525 | ||
ba1ffaa1 | 526 | The above function has something special which is missing for almost all |
706074a5 UD |
527 | the other module functions. There is an argument @var{h_errnop}. This |
528 | points to a variable which will be filled with the error code in case | |
3a35923e FW |
529 | the execution of the function fails for some reason. (In statically |
530 | linked programs, the thread-local variable @code{h_errno} is not shared | |
531 | with the main application.) | |
706074a5 UD |
532 | |
533 | The @code{get@var{XXX}by@var{YYY}} functions are the most important | |
534 | functions in the NSS modules. But there are others which implement | |
535 | the other ways to access system databases (say for the | |
841785ba | 536 | user database, there are @code{setpwent}, @code{getpwent}, and |
706074a5 UD |
537 | @code{endpwent}). These will be described in more detail later. |
538 | Here we give a general way to determine the | |
539 | signature of the module function: | |
540 | ||
541 | @itemize @bullet | |
542 | @item | |
3a35923e | 543 | the return value is @code{enum nss_status}; |
706074a5 | 544 | @item |
3a35923e | 545 | the name (@pxref{NSS Module Names}); |
706074a5 UD |
546 | @item |
547 | the first arguments are identical to the arguments of the non-reentrant | |
548 | function; | |
549 | @item | |
3a35923e | 550 | the next four arguments are: |
706074a5 UD |
551 | |
552 | @table @code | |
26dee9c4 | 553 | @item STRUCT_TYPE *result_buf |
706074a5 UD |
554 | pointer to buffer where the result is stored. @code{STRUCT_TYPE} is |
555 | normally a struct which corresponds to the database. | |
556 | @item char *buffer | |
0bc93a2f | 557 | pointer to a buffer where the function can store additional data for |
706074a5 | 558 | the result etc. |
26dee9c4 | 559 | @item size_t buflen |
706074a5 | 560 | length of the buffer pointed to by @var{buffer}. |
3a35923e FW |
561 | @item int *errnop |
562 | the low-level error code to return to the application. If the return | |
563 | value is not @code{NSS_STATUS_SUCCESS}, @code{*@var{errnop}} needs to be | |
564 | set to a non-zero value. An NSS module should never set | |
565 | @code{*@var{errnop}} to zero. The value @code{ERANGE} is special, as | |
566 | described above. | |
706074a5 UD |
567 | @end table |
568 | ||
569 | @item | |
570 | possibly a last argument @var{h_errnop}, for the host name and network | |
3a35923e FW |
571 | name lookup functions. If the return value is not |
572 | @code{NSS_STATUS_SUCCESS}, @code{*@var{h_errnop}} needs to be set to a | |
573 | non-zero value. A generic error code is @code{NETDB_INTERNAL}, which | |
574 | instructs the caller to examine @code{*@var{errnop}} for further | |
575 | details. (This includes the @code{ERANGE} special case.) | |
706074a5 UD |
576 | @end itemize |
577 | ||
578 | @noindent | |
579 | This table is correct for all functions but the @code{set@dots{}ent} | |
580 | and @code{end@dots{}ent} functions. | |
581 | ||
582 | ||
583 | @node Extending NSS, , NSS Module Internals, Name Service Switch | |
584 | @section Extending NSS | |
585 | ||
586 | One of the advantages of NSS mentioned above is that it can be extended | |
587 | quite easily. There are two ways in which the extension can happen: | |
588 | adding another database or adding another service. The former is | |
589 | normally done only by the C library developers. It is | |
590 | here only important to remember that adding another database is | |
591 | independent from adding another service because a service need not | |
592 | support all databases or lookup functions. | |
593 | ||
ef48b196 | 594 | A designer/implementer of a new service is therefore free to choose the |
706074a5 UD |
595 | databases s/he is interested in and leave the rest for later (or |
596 | completely aside). | |
597 | ||
598 | @menu | |
599 | * Adding another Service to NSS:: What is to do to add a new service. | |
600 | * NSS Module Function Internals:: Guidelines for writing new NSS | |
601 | service functions. | |
602 | @end menu | |
603 | ||
604 | @node Adding another Service to NSS, NSS Module Function Internals, Extending NSS, Extending NSS | |
605 | @subsection Adding another Service to NSS | |
606 | ||
1f77f049 JM |
607 | The sources for a new service need not (and should not) be part of @theglibc{} |
608 | itself. The developer retains complete control over the | |
706074a5 UD |
609 | sources and its development. The links between the C library and the |
610 | new service module consists solely of the interface functions. | |
611 | ||
612 | Each module is designed following a specific interface specification. | |
c66dbe00 UD |
613 | For now the version is 2 (the interface in version 1 was not adequate) |
614 | and this manifests in the version number of the shared library object of | |
615 | the NSS modules: they have the extension @code{.2}. If the interface | |
616 | changes again in an incompatible way, this number will be increased. | |
706074a5 UD |
617 | Modules using the old interface will still be usable. |
618 | ||
619 | Developers of a new service will have to make sure that their module is | |
620 | created using the correct interface number. This means the file itself | |
0bc93a2f | 621 | must have the correct name and on ELF systems the @dfn{soname} (Shared |
706074a5 UD |
622 | Object Name) must also have this number. Building a module from a bunch |
623 | of object files on an ELF system using GNU CC could be done like this: | |
624 | ||
625 | @smallexample | |
c66dbe00 | 626 | gcc -shared -o libnss_NAME.so.2 -Wl,-soname,libnss_NAME.so.2 OBJECTS |
706074a5 UD |
627 | @end smallexample |
628 | ||
629 | @noindent | |
630 | @ref{Link Options, Options for Linking, , gcc, GNU CC}, to learn | |
631 | more about this command line. | |
632 | ||
633 | To use the new module the library must be able to find it. This can be | |
634 | achieved by using options for the dynamic linker so that it will search | |
04b9968b | 635 | the directory where the binary is placed. For an ELF system this could be |
706074a5 UD |
636 | done by adding the wanted directory to the value of |
637 | @code{LD_LIBRARY_PATH}. | |
638 | ||
04b9968b | 639 | But this is not always possible since some programs (those which run |
706074a5 UD |
640 | under IDs which do not belong to the user) ignore this variable. |
641 | Therefore the stable version of the module should be placed into a | |
642 | directory which is searched by the dynamic linker. Normally this should | |
643 | be the directory @file{$prefix/lib}, where @file{$prefix} corresponds to | |
644 | the value given to configure using the @code{--prefix} option. But be | |
645 | careful: this should only be done if it is clear the module does not | |
646 | cause any harm. System administrators should be careful. | |
647 | ||
648 | ||
649 | @node NSS Module Function Internals, , Adding another Service to NSS, Extending NSS | |
650 | @subsection Internals of the NSS Module Functions | |
651 | ||
652 | Until now we only provided the syntactic interface for the functions in | |
04b9968b | 653 | the NSS module. In fact there is not much more we can say since the |
706074a5 UD |
654 | implementation obviously is different for each function. But a few |
655 | general rules must be followed by all functions. | |
656 | ||
657 | In fact there are four kinds of different functions which may appear in | |
658 | the interface. All derive from the traditional ones for system databases. | |
659 | @var{db} in the following table is normally an abbreviation for the | |
841785ba | 660 | database (e.g., it is @code{pw} for the user database). |
706074a5 UD |
661 | |
662 | @table @code | |
a18f587d | 663 | @item enum nss_status _nss_@var{database}_set@var{db}ent (void) |
706074a5 UD |
664 | This function prepares the service for following operations. For a |
665 | simple file based lookup this means files could be opened, for other | |
666 | services this function simply is a noop. | |
667 | ||
668 | One special case for this function is that it takes an additional | |
669 | argument for some @var{database}s (i.e., the interface is | |
670 | @code{int set@var{db}ent (int)}). @ref{Host Names}, which describes the | |
671 | @code{sethostent} function. | |
672 | ||
673 | The return value should be @var{NSS_STATUS_SUCCESS} or according to the | |
674 | table above in case of an error (@pxref{NSS Modules Interface}). | |
675 | ||
a18f587d | 676 | @item enum nss_status _nss_@var{database}_end@var{db}ent (void) |
706074a5 UD |
677 | This function simply closes all files which are still open or removes |
678 | buffer caches. If there are no files or buffers to remove this is again | |
679 | a simple noop. | |
680 | ||
5455692a | 681 | There normally is no return value other than @var{NSS_STATUS_SUCCESS}. |
706074a5 | 682 | |
c66dbe00 | 683 | @item enum nss_status _nss_@var{database}_get@var{db}ent_r (@var{STRUCTURE} *result, char *buffer, size_t buflen, int *errnop) |
706074a5 UD |
684 | Since this function will be called several times in a row to retrieve |
685 | one entry after the other it must keep some kind of state. But this | |
686 | also means the functions are not really reentrant. They are reentrant | |
687 | only in that simultaneous calls to this function will not try to | |
688 | write the retrieved data in the same place (as it would be the case for | |
689 | the non-reentrant functions); instead, it writes to the structure | |
690 | pointed to by the @var{result} parameter. But the calls share a common | |
691 | state and in the case of a file access this means they return neighboring | |
692 | entries in the file. | |
693 | ||
694 | The buffer of length @var{buflen} pointed to by @var{buffer} can be used | |
695 | for storing some additional data for the result. It is @emph{not} | |
696 | guaranteed that the same buffer will be passed for the next call of this | |
697 | function. Therefore one must not misuse this buffer to save some state | |
698 | information from one call to another. | |
699 | ||
3a35923e | 700 | Before the function returns with a failure code, the implementation |
010fe231 | 701 | should store the value of the local @code{errno} variable in the variable |
3a35923e FW |
702 | pointed to be @var{errnop}. This is important to guarantee the module |
703 | working in statically linked programs. The stored value must not be | |
704 | zero. | |
c66dbe00 | 705 | |
706074a5 UD |
706 | As explained above this function could also have an additional last |
707 | argument. This depends on the database used; it happens only for | |
b3a86ae1 | 708 | @code{host} and @code{networks}. |
706074a5 | 709 | |
04b9968b | 710 | The function shall return @code{NSS_STATUS_SUCCESS} as long as there are |
706074a5 UD |
711 | more entries. When the last entry was read it should return |
712 | @code{NSS_STATUS_NOTFOUND}. When the buffer given as an argument is too | |
713 | small for the data to be returned @code{NSS_STATUS_TRYAGAIN} should be | |
714 | returned. When the service was not formerly initialized by a call to | |
5455692a | 715 | @code{_nss_@var{DATABASE}_set@var{db}ent} all return values allowed for |
706074a5 UD |
716 | this function can also be returned here. |
717 | ||
c66dbe00 | 718 | @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) |
706074a5 UD |
719 | This function shall return the entry from the database which is |
720 | addressed by the @var{PARAMS}. The type and number of these arguments | |
721 | vary. It must be individually determined by looking to the user-level | |
722 | interface functions. All arguments given to the non-reentrant version | |
723 | are here described by @var{PARAMS}. | |
724 | ||
725 | The result must be stored in the structure pointed to by @var{result}. | |
5455692a | 726 | If there are additional data to return (say strings, where the |
706074a5 | 727 | @var{result} structure only contains pointers) the function must use the |
5455692a | 728 | @var{buffer} of length @var{buflen}. There must not be any references |
706074a5 UD |
729 | to non-constant global data. |
730 | ||
0bc93a2f | 731 | The implementation of this function should honor the @var{stayopen} |
706074a5 UD |
732 | flag set by the @code{set@var{DB}ent} function whenever this makes sense. |
733 | ||
5455692a | 734 | Before the function returns, the implementation should store the value of |
010fe231 | 735 | the local @code{errno} variable in the variable pointed to by |
5455692a | 736 | @var{errnop}. This is important to guarantee the module works in |
c66dbe00 UD |
737 | statically linked programs. |
738 | ||
706074a5 | 739 | Again, this function takes an additional last argument for the |
b3a86ae1 | 740 | @code{host} and @code{networks} database. |
706074a5 UD |
741 | |
742 | The return value should as always follow the rules given above | |
743 | (@pxref{NSS Modules Interface}). | |
744 | ||
745 | @end table |