getusershell(3) 					     Library Functions Manual						   getusershell(3)

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 setusershell(void);

       int endusershell(void);

       The  following obsolete functions are supported in order to maintain backward compatibility with previous versions of the operating system.
       You should not use them in new designs.	int getusershell_r(	 char *shell,	   int len	unsigned int *state);

       int setusershell_r(	unsigned int *state);

       int endusershell_r(	unsigned int *state);

PARAMETERS

       Points to a buffer for the shell name.  Specifies the length of the shell parameter.  Points 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.

NOTES

       The getusershell() function returns a pointer to thread-specific data.  Subsequent calls to the function from  the  same  thread  overwrite
       this data.

       The  getusershell_r(),  setusershell_r(),  and  endusershell_r()  functions are obsolete reentrant versions of the getusershell(), setuser-
       shell(), and endusershell() functions.  They are supported in order to maintain backward compatibility with previous versions of the  oper-
       ating  system and should not be used in new designs.  Note that you must initialize the state parameter to 0 (zero) before its first access
       by any of these functions.

RETURN VALUES

       Upon successful completion, the getusershell() function returns a pointer to a character string.  If it fails or reaches  the  end  of  the
       shell file, it returns a null pointer.

       Upon  successful  completion,  the  getusershell_r()  function stores a pointer to the shell name in shell and returns a value of 0 (zero).
       Upon failure, it returns a value of -1 and places an appropriate value in the errno variable.

       Upon successful completion, the setusershell_r() function returns a value of 0 (zero).  Upon failure, it returns a value of -1  and  places
       an appropriate value in the errno variable.

       The endusershell_r() function always returns a value of 0 (zero).

ERRORS

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

       Either the shell parameter is invalid, the len parameter is too small, or the state parameter is a null pointer.  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: Unable to allocate memory  for  the
       reread list of shells.

FILES

       Contains the names of legal user shells.

RELATED INFORMATION

       Files: shells(4).

       delim off

																   getusershell(3)