[unix-history] / usr / src / lib / libc / gen / getfsent.3

.\" Copyright (c) 1983, 1991 The Regents of the University of California.
.\" All rights reserved.
.\"
.\" %sccs.include.redist.man%
.\"
.\"     @(#)getfsent.3	6.9 (Berkeley) %G%
.\"
.Dd 
.Dt GETFSENT 3
.Os BSD 4
.Sh NAME
.Nm getfsent ,
.Nm getfsspec ,
.Nm getfsfile ,
.Nm setfsent ,
.Nm endfsent
.Nd get file system descriptor file entry
.Sh SYNOPSIS
.Fd #include <fstab.h>
.Ft 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;	/* type of file system */
	char	*fs_mntops;	/* comma separated mount options */
	char	*fs_type;	/* rw, ro, sw, or xx */
	int	fs_freq;	/* dump frequency, in days */
	int	fs_passno;	/* pass number on parallel dump */
};
.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 null pointer (0) 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
ae59e04c	1	.\" Copyright (c) 1983, 1991 The Regents of the University of California.
12568253	2	.\" All rights reserved.
2f4571d9	3	.\"
91cff1e1	4	.\" %sccs.include.redist.man%
12568253	5	.\"
ae59e04c	6	.\" @(#)getfsent.3 6.9 (Berkeley) %G%
2f4571d9	7	.\"
ae59e04c CL	8	.Dd
	9	.Dt GETFSENT 3
	10	.Os BSD 4
	11	.Sh NAME
	12	.Nm getfsent ,
	13	.Nm getfsspec ,
	14	.Nm getfsfile ,
	15	.Nm setfsent ,
	16	.Nm endfsent
	17	.Nd get file system descriptor file entry
	18	.Sh SYNOPSIS
	19	.Fd #include <fstab.h>
	20	.Ft fstab *
	21	.Fn getfsent void
	22	.Ft struct fstab *
	23	.Fn getfsspec "const char *spec"
	24	.Ft struct fstab *
	25	.Fn getfsfile "const char *file"
	26	.Ft int
	27	.Fn setfsent void
	28	.Ft void
	29	.Fn endfsent void
	30	.Sh DESCRIPTION
	31	The
	32	.Fn getfsent ,
	33	.Fn getfsspec ,
2f4571d9	34	and
ae59e04c CL	35	.Fn getfsfile
ae59e04c CL	36	functions
55cdef46	37	each return a pointer to an object with the following structure
b467b8ca KB	38	containing the broken-out fields of a line in the file system
b467b8ca KB	39	description file,
ae59e04c CL	40	.Aq Pa fstab.h .
ae59e04c CL	41	.Bd -literal -offset indent
9dbe8c98	42	struct fstab {
1e24342d KM	43	char fs_spec; / block special device name */
	44	char fs_file; / file system path prefix */
	45	char fs_vfstype; / type of file system */
	46	char fs_mntops; / comma separated mount options */
	47	char fs_type; / rw, ro, sw, or xx */
	48	int fs_freq; /* dump frequency, in days */
	49	int fs_passno; /* pass number on parallel dump */
2f4571d9	50	};
ae59e04c CL	51	.Ed
ae59e04c CL	52	.Pp
2f4571d9	53	The fields have meanings described in
ae59e04c CL	54	.Xr fstab 5 .
	55	.Pp
	56	The
	57	.Fn setfsent
	58	function
62ab31a2 KB	59	opens the file (closing any previously opened file) or rewinds it
62ab31a2 KB	60	if it is already open.
ae59e04c CL	61	.Pp
	62	The
	63	.Fn endfsent
	64	function
2f4571d9	65	closes the file.
ae59e04c CL	66	.Pp
	67	The
	68	.Fn getfsspec
2f4571d9	69	and
ae59e04c CL	70	.Fn getfsfile
ae59e04c CL	71	functions
62ab31a2 KB	72	search the entire file (opening it if necessary) for a matching special
62ab31a2 KB	73	file name or file system file name.
ae59e04c	74	.Pp
62ab31a2	75	For programs wishing to read the entire database,
ae59e04c	76	.Fn getfsent
62ab31a2	77	reads the next entry (opening the file if necessary).
ae59e04c	78	.Pp
62ab31a2	79	All entries in the file with a type field equivalent to
ae59e04c	80	.Dv FSTAB_XX
b467b8ca	81	are ignored.
ae59e04c CL	82	.Sh RETURN VALUES
	83	The
	84	.Fn getfsent ,
	85	.Fn getfsspec ,
12568253	86	and
ae59e04c CL	87	.Fn getfsfile
	88	functions
	89	return a null pointer (0) on
	90	.Dv EOF
	91	or error.
	92	The
	93	.Fn setfsent
	94	function
62ab31a2	95	returns 0 on failure, 1 on success.
ae59e04c CL	96	The
	97	.Fn endfsent
	98	function
12568253	99	returns nothing.
ae59e04c CL	100	.Sh FILES
	101	.Bl -tag -width /etc/fstab -compact
	102	.It Pa /etc/fstab
	103	.El
	104	.Sh SEE ALSO
	105	.Xr fstab 5
	106	.Sh HISTORY
	107	The
	108	.Fn getfsent
	109	function appeared in
	110	.Bx 4.0 ;
	111	the
	112	.Fn endfsent ,
	113	.Fn getfsfile ,
	114	.Fn getfsspec ,
	115	and
	116	.Fn setfsent
	117	functions appeared in
	118	.Bx 4.3 .
	119	.Sh BUGS
	120	These functions use static data storage;
	121	if the data is needed for future use, it should be
	122	copied before any subsequent calls overwrite it.