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