NAME

getusershell, getusershell_r, setusershell, setusershell_r, endusershell, endusershell_r − Get the names of legal user shells

LIBRARY

Standard C Library (libc.a)

SYNOPSIS

char ∗getusershell(void);

int getusershell_r(
char ∗shell,
int len
unsigned int ∗state);

int setusershell(void);

int setusershell_r(
unsigned int ∗state);

int endusershell(void);

int endusershell_r(
unsigned int ∗state);

PARAMETERS

shellPoints to a buffer for the shell name. 

lenSpecifies the length of the shell parameter. 

statePoints to a variable which stores information about the contents of the /etc/shells file. 

DESCRIPTION

The getusershell() function returns a pointer to a string that contains the name of a legal user shell as defined by the system manager in the /etc/shells file. If the /etc/shells file does not exist, the standard system shells are returned. 

On subsequent calls, the getusershell() function returns the next shell.  The endusershell() function resets the list so that subsequent calls of getusershell() reread the list from /etc/shells.  The setusershell() function rereads the list from /etc/shells and subsequent calls of getusershell() start from the beginning. 

The getusershell_r(), setusershell_r(), and endusershell_r() functions are the reentrant versions of the getusershell(), setusershell(), and endusershell() functions.  Note that you must initialize the state parameter to 0 (zero) before using it (pass by reference) for the first time.  Upon successful completion of the getusershell_r() function, the name is stored in shell. 

NOTES

For the getusershell() function, the returned information is in a static area.  It must be copied if it is to be saved. 

RETURN VALUES

Upon successful completion, the getusershell() functions returns a pointer to a character string. Upon error or end of file, it returns a null pointer. 

Upon successful completion, the getusershell_r() and setusershell_r() functions always return a value of 0 (zero).  Otherwise, they return a value of -1 and set errno. 

The endusershell_r() function always returns 0 (zero). 

ERRORS

If any of the following conditions occurs, the getusershell_r() function sets errno to the corresponding value:

[EINVAL]Either the shell parameter is invalid, the len parameter is too small, or the state parameter is a null pointer. 

[ESRCH]The end of the shell list has been reached (EOF). 

If the following condition occurs, the setusershell_r() function sets errno to the corresponding value:

[ENOMEM]Unable to allocate memory for the reread list of shells. 

FILES

/etc/shellsContains the names of legal user shells. 

RELATED INFORMATION

Files: shells(4).