]>
Commit | Line | Data |
---|---|---|
28f540f4 | 1 | @node System Information, System Configuration, Users and Groups, Top |
7a68c94a | 2 | @c %MENU% Getting information about the hardware and operating system |
28f540f4 RM |
3 | @chapter System Information |
4 | ||
5 | This chapter describes functions that return information about the | |
6 | particular machine that is in use---the type of hardware, the type of | |
7 | software, and the individual machine's name. | |
8 | ||
9 | @menu | |
10 | * Host Identification:: Determining the name of the machine. | |
11 | * Hardware/Software Type ID:: Determining the hardware type of the | |
12 | machine and what operating system it is | |
37742e84 UD |
13 | running. |
14 | * Filesystem handling:: Which is mounted and/or available? | |
28f540f4 RM |
15 | @end menu |
16 | ||
17 | ||
18 | @node Host Identification | |
19 | @section Host Identification | |
20 | ||
21 | This section explains how to identify the particular machine that your | |
22 | program is running on. The identification of a machine consists of its | |
23 | Internet host name and Internet address; see @ref{Internet Namespace}. | |
24 | The host name should always be a fully qualified domain name, like | |
25 | @w{@samp{crispy-wheats-n-chicken.ai.mit.edu}}, not a simple name like | |
26 | just @w{@samp{crispy-wheats-n-chicken}}. | |
27 | ||
28 | @pindex hostname | |
29 | @pindex hostid | |
30 | @pindex unistd.h | |
31 | Prototypes for these functions appear in @file{unistd.h}. The shell | |
32 | commands @code{hostname} and @code{hostid} work by calling them. | |
33 | ||
34 | @comment unistd.h | |
35 | @comment BSD | |
36 | @deftypefun int gethostname (char *@var{name}, size_t @var{size}) | |
37 | This function returns the name of the host machine in the array | |
38 | @var{name}. The @var{size} argument specifies the size of this array, | |
39 | in bytes. | |
40 | ||
41 | The return value is @code{0} on success and @code{-1} on failure. In | |
42 | the GNU C library, @code{gethostname} fails if @var{size} is not large | |
43 | enough; then you can try again with a larger array. The following | |
44 | @code{errno} error condition is defined for this function: | |
45 | ||
46 | @table @code | |
47 | @item ENAMETOOLONG | |
48 | The @var{size} argument is less than the size of the host name plus one. | |
49 | @end table | |
50 | ||
51 | @pindex sys/param.h | |
52 | On some systems, there is a symbol for the maximum possible host name | |
53 | length: @code{MAXHOSTNAMELEN}. It is defined in @file{sys/param.h}. | |
54 | But you can't count on this to exist, so it is cleaner to handle | |
55 | failure and try again. | |
56 | ||
57 | @code{gethostname} stores the beginning of the host name in @var{name} | |
58 | even if the host name won't entirely fit. For some purposes, a | |
59 | truncated host name is good enough. If it is, you can ignore the | |
60 | error code. | |
61 | @end deftypefun | |
62 | ||
63 | @comment unistd.h | |
64 | @comment BSD | |
65 | @deftypefun int sethostname (const char *@var{name}, size_t @var{length}) | |
66 | The @code{sethostname} function sets the name of the host machine to | |
67 | @var{name}, a string with length @var{length}. Only privileged | |
68 | processes are allowed to do this. Usually it happens just once, at | |
69 | system boot time. | |
70 | ||
71 | The return value is @code{0} on success and @code{-1} on failure. | |
72 | The following @code{errno} error condition is defined for this function: | |
73 | ||
74 | @table @code | |
75 | @item EPERM | |
76 | This process cannot set the host name because it is not privileged. | |
77 | @end table | |
78 | @end deftypefun | |
79 | ||
80 | @comment unistd.h | |
81 | @comment BSD | |
82 | @deftypefun {long int} gethostid (void) | |
83 | This function returns the ``host ID'' of the machine the program is | |
84 | running on. By convention, this is usually the primary Internet address | |
85 | of that machine, converted to a @w{@code{long int}}. However, some | |
86 | systems it is a meaningless but unique number which is hard-coded for | |
87 | each machine. | |
88 | @end deftypefun | |
89 | ||
90 | @comment unistd.h | |
91 | @comment BSD | |
92 | @deftypefun int sethostid (long int @var{id}) | |
93 | The @code{sethostid} function sets the ``host ID'' of the host machine | |
94 | to @var{id}. Only privileged processes are allowed to do this. Usually | |
95 | it happens just once, at system boot time. | |
96 | ||
97 | The return value is @code{0} on success and @code{-1} on failure. | |
98 | The following @code{errno} error condition is defined for this function: | |
99 | ||
100 | @table @code | |
101 | @item EPERM | |
102 | This process cannot set the host name because it is not privileged. | |
103 | ||
104 | @item ENOSYS | |
105 | The operating system does not support setting the host ID. On some | |
106 | systems, the host ID is a meaningless but unique number hard-coded for | |
107 | each machine. | |
108 | @end table | |
109 | @end deftypefun | |
110 | ||
111 | @node Hardware/Software Type ID | |
112 | @section Hardware/Software Type Identification | |
113 | ||
114 | You can use the @code{uname} function to find out some information about | |
115 | the type of computer your program is running on. This function and the | |
116 | associated data type are declared in the header file | |
117 | @file{sys/utsname.h}. | |
118 | @pindex sys/utsname.h | |
119 | ||
120 | @comment sys/utsname.h | |
121 | @comment POSIX.1 | |
122 | @deftp {Data Type} {struct utsname} | |
123 | The @code{utsname} structure is used to hold information returned | |
124 | by the @code{uname} function. It has the following members: | |
125 | ||
126 | @table @code | |
127 | @item char sysname[] | |
128 | This is the name of the operating system in use. | |
129 | ||
130 | @item char nodename[] | |
131 | This is the network name of this particular computer. In the GNU | |
132 | library, the value is the same as that returned by @code{gethostname}; | |
133 | see @ref{Host Identification}. | |
134 | ||
135 | @item char release[] | |
136 | This is the current release level of the operating system implementation. | |
137 | ||
138 | @item char version[] | |
139 | This is the current version level within the release of the operating | |
140 | system. | |
141 | ||
142 | @item char machine[] | |
143 | This is a description of the type of hardware that is in use. | |
144 | ||
145 | Some systems provide a mechanism to interrogate the kernel directly for | |
146 | this information. On systems without such a mechanism, the GNU C | |
147 | library fills in this field based on the configuration name that was | |
148 | specified when building and installing the library. | |
149 | ||
150 | GNU uses a three-part name to describe a system configuration; the three | |
151 | parts are @var{cpu}, @var{manufacturer} and @var{system-type}, and they | |
152 | are separated with dashes. Any possible combination of three names is | |
153 | potentially meaningful, but most such combinations are meaningless in | |
154 | practice and even the meaningful ones are not necessarily supported by | |
155 | any particular GNU program. | |
156 | ||
157 | Since the value in @code{machine} is supposed to describe just the | |
158 | hardware, it consists of the first two parts of the configuration name: | |
159 | @samp{@var{cpu}-@var{manufacturer}}. For example, it might be one of these: | |
160 | ||
161 | @quotation | |
37742e84 | 162 | @code{"sparc-sun"}, |
28f540f4 | 163 | @code{"i386-@var{anything}"}, |
37742e84 | 164 | @code{"m68k-hp"}, |
28f540f4 RM |
165 | @code{"m68k-sony"}, |
166 | @code{"m68k-sun"}, | |
167 | @code{"mips-dec"} | |
168 | @end quotation | |
169 | @end table | |
170 | @end deftp | |
171 | ||
172 | @comment sys/utsname.h | |
173 | @comment POSIX.1 | |
174 | @deftypefun int uname (struct utsname *@var{info}) | |
175 | The @code{uname} function fills in the structure pointed to by | |
176 | @var{info} with information about the operating system and host machine. | |
177 | A non-negative value indicates that the data was successfully stored. | |
178 | ||
179 | @code{-1} as the value indicates an error. The only error possible is | |
180 | @code{EFAULT}, which we normally don't mention as it is always a | |
181 | possibility. | |
182 | @end deftypefun | |
37742e84 UD |
183 | |
184 | ||
185 | @node Filesystem handling | |
186 | @section Which filesystems are mounted and/or available? | |
187 | ||
188 | The Unix concept of @emph{Everything is a file} is based on the | |
189 | possibility to @dfn{mount} filesystems or other things into the | |
190 | filesystem. For some programs it is desirable and necessary to access | |
c756c71c | 191 | the information whether and, if yes, where a certain filesystem is |
37742e84 UD |
192 | mounted or simply to get lists of all the available filesystems. The |
193 | GNU libc provides some functions to retrieve this information portably. | |
194 | ||
195 | Traditionally Unix systems have a file named @file{/etc/fstab} which | |
196 | describes all possibly mounted filesystems. The @code{mount} program | |
197 | uses this file to mount at startup time of the system all the necessary | |
198 | filesystems. The information about all the filesystems actually mounted | |
c756c71c UD |
199 | is normally kept in a file named @file{/etc/mtab}. Both files share |
200 | the same syntax and it is crucial that this syntax is followed all the | |
37742e84 UD |
201 | time. Therefore it is best to never directly write the files. The |
202 | functions described in this section can do this and they also provide | |
203 | the functionality to convert the external textual representation to the | |
204 | internal representation. | |
205 | ||
206 | @vindex _PATH_FSTAB | |
207 | @vindex _PATH_MNTTAB | |
208 | @vindex FSTAB | |
209 | @vindex _PATH_MOUNTED | |
210 | The filenames given above should never be used directly. The portable | |
211 | way to handle these file is to use the macros @code{_PATH_FSTAB}, | |
c756c71c | 212 | defined in @file{fstab.h} and @code{_PATH_MNTTAB}, defined in |
37742e84 UD |
213 | @file{mntent.h}, respectively. There are also two alternate macro names |
214 | @code{FSTAB} and @code{_PATH_MOUNTED} defined but both names are | |
c756c71c UD |
215 | deprecated and kept only for backward compatibility. The two former |
216 | names should always be used. | |
37742e84 UD |
217 | |
218 | The internal representation for entries of the file is @w{@code{struct | |
219 | fstab}}, defined in @file{fstab.h}. | |
220 | ||
221 | @comment fstab.h | |
222 | @comment BSD | |
223 | @deftp {Data Type} {struct fstab} | |
224 | This structure is used with the @code{getfsent}, @code{getfsspec}, and | |
225 | @code{getfsfile} functions. | |
226 | ||
227 | @table @code | |
228 | @item char *fs_spec | |
fed8f7f7 | 229 | This element describes the device from which the filesystem is mounted. |
37742e84 UD |
230 | Normally this is the name of a special device, such as a hard disk |
231 | partition, but it could also be a more or less generic string. For | |
232 | @dfn{NFS} it would be a hostname and directory name combination. | |
233 | ||
234 | Even though the element is not declared @code{const} it shouldn't be | |
235 | modified. The missing @code{const} has historic reasons, since this | |
236 | function predates @w{ISO C}. The same is true for the other string | |
237 | elements of this structure. | |
238 | ||
239 | @item char *fs_file | |
fed8f7f7 UD |
240 | This describes the mount point on the local system. I.e., accessing any |
241 | file in this filesystem has implicitly or explicitly this string as a | |
37742e84 UD |
242 | prefix. |
243 | ||
244 | @item char *fs_vfstype | |
245 | This is the type of the filesystem. Depending on what the underlying | |
246 | kernel understands it can be any string. | |
247 | ||
248 | @item char *fs_mntops | |
249 | This is a string containing options passed to the kernel with the | |
250 | @code{mount} call. Again, this can be almost anything. There can be | |
251 | more than one option, separated from the others by a comma. Each option | |
252 | consists of a name and an optional value part, introduced by an @code{=} | |
253 | character. | |
254 | ||
c756c71c | 255 | If the value of this element must be processed it should best happen |
37742e84 UD |
256 | using the @code{getsubopt} function; see @ref{Suboptions}. |
257 | ||
258 | @item const char *fs_type | |
c756c71c | 259 | This name is poorly chosen. This element points to a string (possibly |
37742e84 UD |
260 | in the @code{fs_mntops} string) which describes the modes with which the |
261 | filesystem is mounted. @file{fstab} defines five macros to describe the | |
262 | possible values: | |
263 | ||
264 | @vtable @code | |
265 | @item FSTAB_RW | |
266 | The filesystems gets mounted with read and write enabled. | |
267 | @item FSTAB_RQ | |
268 | The filesystems gets mounted with read and write enabled. Write access | |
269 | is restricted by quotas. | |
270 | @item FSTAB_RO | |
c756c71c | 271 | The filesystem gets mounted read-only. |
37742e84 | 272 | @item FSTAB_SW |
c756c71c | 273 | This is not a real filesystem, it is a swap device. |
37742e84 UD |
274 | @item FSTAB_XX |
275 | This entry from the @file{fstab} file is totally ignored. | |
276 | @end vtable | |
277 | ||
278 | Testing for equality with these value must happen using @code{strcmp} | |
c756c71c | 279 | since these are all strings. Comparing the pointer will probably always |
37742e84 UD |
280 | fail. |
281 | ||
282 | @item int fs_freq | |
283 | This element describes the dump frequency in days. | |
284 | ||
285 | @item int fs_passno | |
286 | This element describes the pass number on parallel dumps. It is closely | |
c756c71c | 287 | related to the @code{dump} utility used on Unix systems. |
37742e84 UD |
288 | @end table |
289 | @end deftp | |
290 | ||
291 | ||
292 | To read the entire content of the of the @file{fstab} file the GNU libc | |
293 | contains a set of three functions which are designed in the usual way. | |
294 | ||
295 | @comment fstab.h | |
296 | @comment BSD | |
297 | @deftypefun int setfsent (void) | |
298 | This function makes sure that the internal read pointer for the | |
299 | @file{fstab} file is at the beginning of the file. This is done by | |
300 | either opening the file or resetting the read pointer. | |
301 | ||
302 | Since the file handle is internal to the libc this function is not | |
303 | thread-safe. | |
304 | ||
305 | This function returns a non-zero value if the operation was successful | |
306 | and the @code{getfs*} functions can be used to read the entries of the | |
307 | file. | |
308 | @end deftypefun | |
309 | ||
310 | @comment fstab.h | |
311 | @comment BSD | |
312 | @deftypefun void endfsent (void) | |
313 | This function makes sure that all resources acquired by a prior call to | |
c756c71c | 314 | @code{setfsent} (explicitly or implicitly by calling @code{getfsent}) are |
37742e84 UD |
315 | freed. |
316 | @end deftypefun | |
317 | ||
318 | @comment fstab.h | |
319 | @comment BSD | |
320 | @deftypefun {struct fstab *} getfsent (void) | |
321 | This function returns the next entry of the @file{fstab} file. If this | |
322 | is the first call to any of the functions handling @file{fstab} since | |
323 | program start or the last call of @code{endfsent}, the file will be | |
324 | opened. | |
325 | ||
326 | The function returns a pointer to an variable of type @code{struct | |
327 | fstab}. This variable is shared by all threads and therefore this | |
328 | function is not thread-safe. If an error occurred @code{getfsent} | |
c756c71c | 329 | returns a @code{NULL} pointer. |
37742e84 UD |
330 | @end deftypefun |
331 | ||
332 | @comment fstab.h | |
333 | @comment BSD | |
334 | @deftypefun {struct fstab *} getfsspec (const char *@var{name}) | |
335 | This function returns the next entry of the @file{fstab} file which has | |
336 | a string equal to @var{name} pointed to by the @code{fs_spec} element. | |
337 | Since there is normally exactly one entry for each special device it | |
338 | makes no sense to call this function more than once for the same | |
339 | argument. If this is the first call to any of the functions handling | |
340 | @file{fstab} since program start or the last call of @code{endfsent}, | |
341 | the file will be opened. | |
342 | ||
343 | The function returns a pointer to an variable of type @code{struct | |
344 | fstab}. This variable is shared by all threads and therefore this | |
345 | function is not thread-safe. If an error occurred @code{getfsent} | |
c756c71c | 346 | returns a @code{NULL} pointer. |
37742e84 UD |
347 | @end deftypefun |
348 | ||
349 | @comment fstab.h | |
350 | @comment BSD | |
351 | @deftypefun {struct fstab *} getfsfile (const char *@var{name}) | |
352 | This function returns the next entry of the @file{fstab} file which has | |
353 | a string equal to @var{name} pointed to by the @code{fs_file} element. | |
354 | Since there is normally exactly one entry for each mount point it | |
355 | makes no sense to call this function more than once for the same | |
356 | argument. If this is the first call to any of the functions handling | |
357 | @file{fstab} since program start or the last call of @code{endfsent}, | |
358 | the file will be opened. | |
359 | ||
360 | The function returns a pointer to an variable of type @code{struct | |
361 | fstab}. This variable is shared by all threads and therefore this | |
362 | function is not thread-safe. If an error occurred @code{getfsent} | |
c756c71c | 363 | returns a @code{NULL} pointer. |
37742e84 UD |
364 | @end deftypefun |
365 | ||
c756c71c | 366 | To access the @file{mtab} file there is a different set of functions and |
37742e84 UD |
367 | also a different structure to describe the results. |
368 | ||
369 | ||
370 | @comment fstab.h | |
371 | @comment BSD | |
372 | @deftp {Data Type} {struct mntent} | |
373 | This structure is used with the @code{getmntent}, @code{getmntent_t}, | |
374 | @code{addmntent}, and @code{hasmntopt} functions. | |
375 | ||
376 | @table @code | |
377 | @item char *mnt_fsname | |
378 | This element contains a pointer to a string describing the name of the | |
379 | special device from which the filesystem is mounted. It corresponds to | |
380 | the @code{fs_spec} element in @code{struct fstab}. | |
381 | ||
382 | @item char *mnt_dir | |
383 | This element points to a string describing the mount point of the | |
384 | filesystem. It corresponds to the @code{fs_file} element in | |
385 | @code{struct fstab}. | |
386 | ||
387 | @item char *mnt_type | |
388 | @code{mnt_type} describes the filesystem type and is therefore | |
389 | equivalent to @code{fs_vfstype} in @code{struct fstab}. @file{mntent.h} | |
390 | defines a few symbolic names for some of the value this string can have. | |
391 | But since the kernel can support an arbitrary filesystems it does not | |
392 | make much sense to give them symbolic names. If one knows the symbol | |
393 | name one also knows the filesystem name. Nevertheless here follows the | |
394 | list of the symbol provided in @file{mntent.h}. | |
395 | ||
396 | @vtable @code | |
397 | @item MNTTYPE_IGNORE | |
398 | This symbol expands to @code{"ignore"}. The value is sometime used in | |
399 | @file{fstab} files to make sure entries are not used without removing them. | |
400 | @item MNTTYPE_NFS | |
401 | Expands to @code{"nfs"}. Using this macro sometimes could make sense | |
402 | since it names the default NFS implementation, in case both version 2 | |
403 | and 3 are supported. | |
404 | @item MNTTYPE_SWAP | |
405 | This symbol expands to @code{"swap"}. It names the special @file{fstab} | |
406 | entry which names one of the possibly multiple swap partitions. | |
407 | @end vtable | |
408 | ||
409 | @item char *mnt_opts | |
410 | The element contains a string describing the options used while mounting | |
411 | the filesystem. As for the equivalent element @code{fs_mntops} of | |
412 | @code{struct fstab} it is best to use the function @code{getsubopt} | |
413 | (@pxref{Suboptions}) to access the parts of this string. | |
414 | ||
415 | The @file{mntent.h} file defines a number of macros with string values | |
416 | which correspond to some of the options understood by the kernel. There | |
417 | might be many more options which are possible so it makes not much sense | |
418 | to rely on these macros but to be consistent here is the list: | |
419 | ||
420 | @vtable @code | |
421 | @item MNTOPT_DEFAULTS | |
422 | Expands to @code{"defaults"}. This option should be used alone since it | |
423 | indicates all values for the custumizable values are chosen to be the | |
424 | default. | |
425 | @item MNTOPT_RO | |
fed8f7f7 | 426 | Expands to @code{"ro"}. See the @code{FSTAB_RO} value, it means the |
37742e84 UD |
427 | filesystem is mounted read-only. |
428 | @item MNTOPT_RW | |
fed8f7f7 | 429 | Expand to @code{"rw"}. See the @code{FSTAB_RW} value, it means the |
37742e84 UD |
430 | filesystem is mounted with read and write permissions. |
431 | @item MNTOPT_SUID | |
432 | Expands to @code{"suid"}. This means that the SUID bit (@pxref{How | |
433 | Change Persona}) is respected when a program from the filesystem is | |
434 | started. | |
435 | @item MNTOPT_NOSUID | |
436 | Expands to @code{"nosuid"}. This is the opposite of @code{MNTOPT_SUID}, | |
c756c71c | 437 | the SUID bit for all files from the filesystem is ignored. |
37742e84 UD |
438 | @item MNTOPT_NOAUTO |
439 | Expands to @code{"noauto"}. At startup time the @code{mount} program | |
440 | will ignore this entry if it is started with the @code{-a} option to | |
441 | mount all filesystems mentioned in the @file{fstab} file. | |
442 | @end vtable | |
443 | ||
444 | As for the @code{FSTAB_*} entries introduced above it is important to | |
445 | use @code{strcmp} to check for equality. | |
446 | ||
447 | @item mnt_freq | |
448 | This elements corresponds to @code{fs_freq} and also specifies the | |
449 | frequency in days in which dumps are made. | |
450 | ||
451 | @item mnt_passno | |
452 | This element is equivalent to @code{fs_passno} with the same meaning | |
453 | which is uninteresting for all programs beside @code{dump}. | |
454 | @end table | |
455 | @end deftp | |
456 | ||
457 | For accessing the @file{mtab} file there is again a set of three | |
458 | functions to access all entries in a row. Unlike the functions to | |
459 | handle @file{fstab} these functions do not access a fixed file and there | |
c756c71c UD |
460 | is even a thread safe variant of the get function. Beside this the GNU |
461 | libc contains functions to alter the file and test for specific options. | |
37742e84 UD |
462 | |
463 | @comment mntent.h | |
464 | @comment BSD | |
465 | @deftypefun {FILE *} setmntent (const char *@var{file}, const char *@var{mode}) | |
466 | The @code{setmntent} function prepares the file named @var{FILE} which | |
467 | must be in the format of a @file{fstab} and @file{mtab} file for the | |
468 | upcoming processing through the other functions of the family. The | |
469 | @var{mode} parameter can be chosen in the way the @var{opentype} | |
470 | parameter for @code{fopen} (@pxref{Opening Streams}) can be chosen. If | |
471 | the file is opened for writing the file is also allowed to be empty. | |
472 | ||
473 | If the file was successfully opened @code{setmntent} returns a file | |
474 | descriptor for future use. Otherwise the return value is @code{NULL} | |
475 | and @code{errno} is set accordingly. | |
476 | @end deftypefun | |
477 | ||
478 | @comment mntent.h | |
479 | @comment BSD | |
480 | @deftypefun int endmntent (FILE *@var{stream}) | |
481 | This function takes for the @var{stream} parameter a file handle which | |
482 | previously was returned from the @code{setmntent} call. | |
483 | @code{endmntent} closes the stream and frees all resources. | |
484 | ||
c756c71c UD |
485 | The return value is @math{1} unless an error occurred in which case it |
486 | is @math{0}. | |
37742e84 UD |
487 | @end deftypefun |
488 | ||
489 | @comment mntent.h | |
490 | @comment BSD | |
491 | @deftypefun {struct mntent *} getmntent (FILE *@var{stream}) | |
492 | The @code{getmntent} function takes as the parameter a file handle | |
493 | previously returned by successful call to @code{setmntent}. It returns | |
494 | a pointer to a static variable of type @code{struct mntent} which is | |
495 | filled with the information from the next entry from the file currently | |
496 | read. | |
497 | ||
c7f7281e UD |
498 | The file format used prescribes the use of spaces or tab characters to |
499 | separate the fields. This makes it harder to use name containing one of | |
500 | these characters (e.g., mount points using spaces). Therefore these | |
501 | characters are encoded in the files and the @code{getmntent} function | |
502 | takes care of the decoding while reading the entries back in. | |
503 | @code{'\040'} is used to encode a space character, @code{'\012'} to | |
504 | encode a tab character and @code{'\\'} to encode a backslash. | |
505 | ||
37742e84 UD |
506 | If there was an error or the end of the file is reached the return value |
507 | is @code{NULL}. | |
508 | ||
509 | This function is not thread-safe since all calls to this function return | |
510 | a pointer to the same static variable. @code{getmntent_r} should be | |
c756c71c | 511 | used in situations where multiple threads access the file. |
37742e84 UD |
512 | @end deftypefun |
513 | ||
514 | @comment mntent.h | |
515 | @comment BSD | |
516 | @deftypefun {struct mntent *} getmntent_r (FILE *@var{stream}, struct mentent *@var{result}, char *@var{buffer}, int @var{bufsize}) | |
517 | The @code{getmntent_r} function is the reentrant variant of | |
518 | @code{getmntent}. It also returns the next entry from the file and | |
519 | returns a pointer. The actual variable the values are stored in is not | |
520 | static, though. Instead the function stores the values in the variable | |
521 | pointed to by the @var{result} parameter. Additional information (e.g., | |
522 | the strings pointed to by the elements of the result) are kept in the | |
523 | buffer of size @var{bufsize} pointed to by @var{buffer}. | |
524 | ||
c7f7281e UD |
525 | Escaped characters (space, tab, backslash) are converted back in the |
526 | same way as it happens for @code{getmentent}. | |
527 | ||
c756c71c | 528 | The function returns a @code{NULL} pointer in error cases. Errors could be: |
37742e84 UD |
529 | @itemize @bullet |
530 | @item | |
531 | error while reading the file, | |
532 | @item | |
533 | end of file reached, | |
534 | @item | |
535 | @var{bufsize} is too small for reading a complete new entry. | |
536 | @end itemize | |
537 | @end deftypefun | |
538 | ||
539 | @comment mntent.h | |
540 | @comment BSD | |
541 | @deftypefun int addmntent (FILE *@var{stream}, const struct mntent *@var{mnt}) | |
c756c71c | 542 | The @code{addmntent} function allows to add a new entry to the file |
37742e84 UD |
543 | previously opened with @code{setmntent}. The new entries are always |
544 | appended. I.e., even if the position of the file descriptor is not at | |
c756c71c | 545 | the end of the file this function does not overwrite an existing entry |
37742e84 UD |
546 | following the current position. |
547 | ||
548 | The implication of this is that to remove an entry from a file one has | |
549 | to create a new file while leaving out the entry to be removed and after | |
550 | closing the file remove the old one and rename the new file to the | |
551 | chosen name. | |
552 | ||
c7f7281e UD |
553 | This function takes care of spaces and tab characters in the names to be |
554 | written to the file. It converts them and the backslash character into | |
555 | the format describe in the @code{getmntent} description above. | |
556 | ||
c756c71c UD |
557 | This function returns @math{0} in case the operation was successful. |
558 | Otherwise the return value is @math{1} and @code{errno} is set | |
37742e84 UD |
559 | appropriately. |
560 | @end deftypefun | |
561 | ||
562 | @comment mntent.h | |
563 | @comment BSD | |
564 | @deftypefun {char *} hasmntopt (const struct mntent *@var{mnt}, const char *@var{opt}) | |
565 | This function can be used to check whether the string pointed to by the | |
566 | @code{mnt_opts} element of the variable pointed to by @var{mnt} contains | |
567 | the option @var{opt}. If this is true a pointer to the beginning of the | |
568 | option in the @code{mnt_opts} element is returned. If no such option | |
c756c71c | 569 | exists the function returns @code{NULL}. |
37742e84 UD |
570 | |
571 | This function is useful to test whether a specific option is present but | |
572 | when all options have to be processed one is better off with using the | |
573 | @code{getsubopt} function to iterate over all options in the string. | |
574 | @end deftypefun |