[apple/libc.git] / gen / getfsent.3

.\" Copyright (c) 1983, 1991, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     @(#)getfsent.3	8.1 (Berkeley) 6/4/93
.\" $FreeBSD: src/lib/libc/gen/getfsent.3,v 1.9 2001/10/01 16:08:51 ru Exp $
.\"
.Dd June 4, 1993
.Dt GETFSENT 3
.Os
.Sh NAME
.Nm getfsent ,
.Nm getfsspec ,
.Nm getfsfile ,
.Nm setfsent ,
.Nm endfsent
.Nd get file system descriptor file entry
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In fstab.h
.Ft struct fstab *
.Fn getfsent void
.Ft struct fstab *
.Fn getfsspec "const char *spec"
.Ft struct fstab *
.Fn getfsfile "const char *file"
.Ft int
.Fn setfsent void
.Ft void
.Fn endfsent void
.Sh DESCRIPTION
The
.Fn getfsent ,
.Fn getfsspec ,
and
.Fn getfsfile
functions
each return a pointer to an object with the following structure
containing the broken-out fields of a line in the file system
description file,
.Aq Pa fstab.h .
.Bd -literal -offset indent
struct fstab {
	char	*fs_spec;	/* block special device name */
	char	*fs_file;	/* file system path prefix */
	char	*fs_vfstype;	/* File system type, ufs, nfs */
	char	*fs_mntops;	/* Mount options ala -o */
	char	*fs_type;	/* FSTAB_* from fs_mntops */
	int	fs_freq;	/* dump frequency, in days */
	int	fs_passno;	/* pass number on parallel fsck */
};
.Ed
.Pp
The fields have meanings described in
.Xr fstab 5 .
.Pp
The
.Fn setfsent
function
opens the file (closing any previously opened file) or rewinds it
if it is already open.
.Pp
The
.Fn endfsent
function
closes the file.
.Pp
The
.Fn getfsspec
and
.Fn getfsfile
functions
search the entire file (opening it if necessary) for a matching special
file name or file system file name.
.Pp
For programs wishing to read the entire database,
.Fn getfsent
reads the next entry (opening the file if necessary).
.Pp
All entries in the file with a type field equivalent to
.Dv FSTAB_XX
are ignored.
.Sh RETURN VALUES
The
.Fn getfsent ,
.Fn getfsspec ,
and
.Fn getfsfile
functions
return a
.Dv NULL
pointer on
.Dv EOF
or error.
The
.Fn setfsent
function
returns 0 on failure, 1 on success.
The
.Fn endfsent
function
returns nothing.
.Sh FILES
.Bl -tag -width /etc/fstab -compact
.It Pa /etc/fstab
.El
.Sh SEE ALSO
.Xr fstab 5
.Sh HISTORY
The
.Fn getfsent
function appeared in
.Bx 4.0 ;
the
.Fn endfsent ,
.Fn getfsfile ,
.Fn getfsspec ,
and
.Fn setfsent
functions appeared in
.Bx 4.3 .
.Sh BUGS
These functions use static data storage;
if the data is needed for future use, it should be
copied before any subsequent calls overwrite it.
Commit	Line	Data
5b2abdfb A	1	.\" Copyright (c) 1983, 1991, 1993
	2	.\" The Regents of the University of California. All rights reserved.
	3	.\"
	4	.\" Redistribution and use in source and binary forms, with or without
	5	.\" modification, are permitted provided that the following conditions
	6	.\" are met:
	7	.\" 1. Redistributions of source code must retain the above copyright
	8	.\" notice, this list of conditions and the following disclaimer.
	9	.\" 2. Redistributions in binary form must reproduce the above copyright
	10	.\" notice, this list of conditions and the following disclaimer in the
	11	.\" documentation and/or other materials provided with the distribution.
	12	.\" 3. All advertising materials mentioning features or use of this software
	13	.\" must display the following acknowledgement:
	14	.\" This product includes software developed by the University of
	15	.\" California, Berkeley and its contributors.
	16	.\" 4. Neither the name of the University nor the names of its contributors
	17	.\" may be used to endorse or promote products derived from this software
	18	.\" without specific prior written permission.
	19	.\"
	20	.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
	21	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	22	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	23	.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
	24	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	25	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	26	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	27	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	28	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	29	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	30	.\" SUCH DAMAGE.
	31	.\"
	32	.\" @(#)getfsent.3 8.1 (Berkeley) 6/4/93
	33	.\" $FreeBSD: src/lib/libc/gen/getfsent.3,v 1.9 2001/10/01 16:08:51 ru Exp $
	34	.\"
	35	.Dd June 4, 1993
	36	.Dt GETFSENT 3
	37	.Os
	38	.Sh NAME
	39	.Nm getfsent ,
	40	.Nm getfsspec ,
	41	.Nm getfsfile ,
	42	.Nm setfsent ,
	43	.Nm endfsent
	44	.Nd get file system descriptor file entry
	45	.Sh LIBRARY
	46	.Lb libc
	47	.Sh SYNOPSIS
	48	.In fstab.h
	49	.Ft struct fstab *
	50	.Fn getfsent void
	51	.Ft struct fstab *
	52	.Fn getfsspec "const char *spec"
	53	.Ft struct fstab *
	54	.Fn getfsfile "const char *file"
	55	.Ft int
	56	.Fn setfsent void
	57	.Ft void
	58	.Fn endfsent void
	59	.Sh DESCRIPTION
	60	The
	61	.Fn getfsent ,
	62	.Fn getfsspec ,
	63	and
	64	.Fn getfsfile
65	functions
66	each return a pointer to an object with the following structure
67	containing the broken-out fields of a line in the file system
68	description file,
69	.Aq Pa fstab.h .
70	.Bd -literal -offset indent
71	struct fstab {
72	char fs_spec; / block special device name */
73	char fs_file; / file system path prefix */
74	char fs_vfstype; / File system type, ufs, nfs */
75	char fs_mntops; / Mount options ala -o */
76	char fs_type; / FSTAB_* from fs_mntops */
77	int fs_freq; /* dump frequency, in days */
78	int fs_passno; /* pass number on parallel fsck */
79	};
80	.Ed
81	.Pp
82	The fields have meanings described in
83	.Xr fstab 5 .
84	.Pp
85	The
86	.Fn setfsent
87	function
88	opens the file (closing any previously opened file) or rewinds it
89	if it is already open.
90	.Pp
91	The
92	.Fn endfsent
93	function
94	closes the file.
95	.Pp
96	The
97	.Fn getfsspec
98	and
99	.Fn getfsfile
100	functions
101	search the entire file (opening it if necessary) for a matching special
102	file name or file system file name.
103	.Pp
104	For programs wishing to read the entire database,
105	.Fn getfsent
106	reads the next entry (opening the file if necessary).
107	.Pp
108	All entries in the file with a type field equivalent to
109	.Dv FSTAB_XX
110	are ignored.
111	.Sh RETURN VALUES
112	The
113	.Fn getfsent ,
114	.Fn getfsspec ,
115	and
116	.Fn getfsfile
117	functions
118	return a
119	.Dv NULL
120	pointer on
121	.Dv EOF
122	or error.
123	The
124	.Fn setfsent
125	function
126	returns 0 on failure, 1 on success.
127	The
128	.Fn endfsent
129	function
130	returns nothing.
131	.Sh FILES
132	.Bl -tag -width /etc/fstab -compact
133	.It Pa /etc/fstab
134	.El
135	.Sh SEE ALSO
136	.Xr fstab 5
137	.Sh HISTORY
138	The
139	.Fn getfsent
140	function appeared in
141	.Bx 4.0 ;
142	the
143	.Fn endfsent ,
144	.Fn getfsfile ,
145	.Fn getfsspec ,
146	and
147	.Fn setfsent
148	functions appeared in
149	.Bx 4.3 .
150	.Sh BUGS
151	These functions use static data storage;
152	if the data is needed for future use, it should be
153	copied before any subsequent calls overwrite it.