'\" te
.\" Copyright (c) 2007, Sun Microsystems, Inc.  All Rights Reserved.
.\" Copyright (c) 1985 Regents of the University of California.  All rights reserved.  The Berkeley software License Agreement specifies the terms and conditions for redistribution.
.\" Portions Copyright (c) 1982-2007 AT&T Knowledge Ventures
.TH GETUSERSHELL 3C "Nov 1, 2007"
.SH NAME
getusershell, setusershell, endusershell \- get legal user shells
.SH SYNOPSIS
.LP
.nf
#include <unistd.h>

\fBchar *\fR\fBgetusershell\fR(\fBvoid\fR);
.fi

.LP
.nf
\fBvoid\fR \fBsetusershell\fR(\fBvoid\fR);
.fi

.LP
.nf
\fBvoid\fR \fBendusershell\fR(\fBvoid\fR);
.fi

.SH DESCRIPTION
.sp
.LP
The \fBgetusershell()\fR function returns a pointer to a legal user shell as
defined by the system manager in the file \fB/etc/shells\fR. If
\fB/etc/shells\fR does not exist, the following locations of the standard
system shells are used in its place:
.sp
.in +2
.nf
\fB/bin/bash\fR                  \fB/bin/csh\fR
\fB/bin/jsh\fR                   \fB/bin/ksh\fR
\fB/bin/ksh93\fR                 \fB/bin/pfcsh\fR
\fB/bin/pfksh\fR                 \fB/bin/pfsh\fR
\fB/bin/sh\fR                    \fB/bin/tcsh\fR
\fB/bin/zsh\fR                   \fB/sbin/jsh\fR
\fB/sbin/pfsh\fR                 \fB/sbin/sh\fR
\fB/usr/bin/bash\fR              \fB/usr/bin/csh\fR
\fB/usr/bin/jsh\fR               \fB/usr/bin/ksh\fR
\fB/usr/bin/ksh93\fR             \fB/usr/bin/pfcsh\fR
\fB/usr/bin/pfksh\fR             \fB/usr/bin/pfsh\fR
\fB/usr/bin/sh\fR                \fB/usr/bin/tcsh\fR
\fB/usr/bin/zsh\fR               \fB/usr/sfw/bin/zsh\fR
\fB/usr/xpg4/bin/sh\fR
.fi
.in -2

.sp
.LP
The \fBgetusershell()\fR function opens the file \fB/etc/shells\fR, if it
exists, and returns the next entry in the list of shells.
.sp
.LP
The \fBsetusershell()\fR function rewinds the file or the list.
.sp
.LP
The \fBendusershell()\fR function closes the file, frees any memory used by
\fBgetusershell()\fR and \fBsetusershell()\fR, and rewinds the file
\fB/etc/shells\fR.
.SH RETURN VALUES
.sp
.LP
The \fBgetusershell()\fR function returns a null pointer on EOF.
.SH BUGS
.sp
.LP
All information is contained in memory that may be freed with a call to
\fBendusershell()\fR, so it must be copied if it is to be saved.
.SH NOTES
.sp
.LP
Restricted shells should not be listed in \fB/etc/shells\fR.