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

.\"	$NetBSD: getusershell.3,v 1.6 1999/03/22 19:44:42 garbled Exp $
.\"	$FreeBSD: src/lib/libc/gen/getusershell.3,v 1.10 2001/10/01 16:08:51 ru Exp $
.\"
.\" Copyright (c) 1985, 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.
.\"
.\"     @(#)getusershell.3	8.1 (Berkeley) 6/4/93
.\"
.Dd January 16, 1999
.Dt GETUSERSHELL 3
.Os
.Sh NAME
.Nm getusershell ,
.Nm setusershell ,
.Nm endusershell
.Nd get valid user shells
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In unistd.h
.Ft char *
.Fn getusershell void
.Ft void
.Fn setusershell void
.Ft void
.Fn endusershell void
.Sh DESCRIPTION
The
.Fn getusershell
function
returns a pointer to a valid user shell as defined by the
system manager in the shells database as described in
.Xr shells 5 .
If the shells database is not available,
.Fn getusershell
behaves as if
.Pa /bin/sh
and
.Pa /bin/csh
were listed.
.Pp
The
.Fn getusershell
function
reads the next
line (opening the file if necessary);
.Fn setusershell
rewinds the file;
.Fn endusershell
closes it.
.Sh FILES
.Bl -tag -width /etc/shells -compact
.It Pa /etc/shells
.El
.Sh DIAGNOSTICS
The routine
.Fn getusershell
returns a null pointer (0) on
.Dv EOF .
.Sh SEE ALSO
.Xr shells 5
.Sh HISTORY
The
.Fn getusershell
function appeared in
.Bx 4.3 .
.Sh BUGS
The
.Fn getusershell
function leaves its result in an internal static object and returns
a pointer to that object.
Subsequent calls to
.Fn getusershell
will modify the same object.
Commit	Line	Data
5b2abdfb A	1	.\" $NetBSD: getusershell.3,v 1.6 1999/03/22 19:44:42 garbled Exp $
	2	.\" $FreeBSD: src/lib/libc/gen/getusershell.3,v 1.10 2001/10/01 16:08:51 ru Exp $
	3	.\"
	4	.\" Copyright (c) 1985, 1991, 1993
e9ce8d39 A	5	.\" The Regents of the University of California. All rights reserved.
	6	.\"
	7	.\" Redistribution and use in source and binary forms, with or without
	8	.\" modification, are permitted provided that the following conditions
	9	.\" are met:
	10	.\" 1. Redistributions of source code must retain the above copyright
	11	.\" notice, this list of conditions and the following disclaimer.
	12	.\" 2. Redistributions in binary form must reproduce the above copyright
	13	.\" notice, this list of conditions and the following disclaimer in the
	14	.\" documentation and/or other materials provided with the distribution.
	15	.\" 3. All advertising materials mentioning features or use of this software
	16	.\" must display the following acknowledgement:
	17	.\" This product includes software developed by the University of
	18	.\" California, Berkeley and its contributors.
	19	.\" 4. Neither the name of the University nor the names of its contributors
	20	.\" may be used to endorse or promote products derived from this software
	21	.\" without specific prior written permission.
	22	.\"
	23	.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
	24	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	25	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	26	.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
	27	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	28	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	29	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	30	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	31	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	32	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	33	.\" SUCH DAMAGE.
	34	.\"
5b2abdfb	35	.\" @(#)getusershell.3 8.1 (Berkeley) 6/4/93
e9ce8d39	36	.\"
5b2abdfb A	37	.Dd January 16, 1999
5b2abdfb A	38	.Dt GETUSERSHELL 3
e9ce8d39 A	39	.Os
e9ce8d39 A	40	.Sh NAME
5b2abdfb A	41	.Nm getusershell ,
	42	.Nm setusershell ,
	43	.Nm endusershell
	44	.Nd get valid user shells
e9ce8d39 A	45	.Sh LIBRARY
	46	.Lb libc
	47	.Sh SYNOPSIS
5b2abdfb A	48	.In unistd.h
	49	.Ft char *
	50	.Fn getusershell void
	51	.Ft void
	52	.Fn setusershell void
	53	.Ft void
	54	.Fn endusershell void
e9ce8d39 A	55	.Sh DESCRIPTION
e9ce8d39 A	56	The
5b2abdfb A	57	.Fn getusershell
	58	function
	59	returns a pointer to a valid user shell as defined by the
	60	system manager in the shells database as described in
	61	.Xr shells 5 .
	62	If the shells database is not available,
	63	.Fn getusershell
	64	behaves as if
	65	.Pa /bin/sh
e9ce8d39	66	and
5b2abdfb A	67	.Pa /bin/csh
	68	were listed.
	69	.Pp
e9ce8d39	70	The
5b2abdfb A	71	.Fn getusershell
	72	function
	73	reads the next
	74	line (opening the file if necessary);
	75	.Fn setusershell
	76	rewinds the file;
	77	.Fn endusershell
	78	closes it.
	79	.Sh FILES
	80	.Bl -tag -width /etc/shells -compact
	81	.It Pa /etc/shells
	82	.El
	83	.Sh DIAGNOSTICS
	84	The routine
	85	.Fn getusershell
	86	returns a null pointer (0) on
	87	.Dv EOF .
e9ce8d39	88	.Sh SEE ALSO
5b2abdfb	89	.Xr shells 5
e9ce8d39 A	90	.Sh HISTORY
e9ce8d39 A	91	The
5b2abdfb A	92	.Fn getusershell
	93	function appeared in
	94	.Bx 4.3 .
	95	.Sh BUGS
	96	The
	97	.Fn getusershell
	98	function leaves its result in an internal static object and returns
	99	a pointer to that object.
	100	Subsequent calls to
	101	.Fn getusershell
	102	will modify the same object.