Index for Section 3

Alphabetical listing for G

Bottom of page

getusershell(3)
NAME
  getusershell, getusershell_r, setusershell, setusershell_r, endusershell,
  endusershell_r - Get the names of legal user shells

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(
	  unsigned int *state );

LIBRARY
  Standard C Library (libc)

PARAMETERS
  shell
      Points to a buffer for the shell name.

  len Specifies the length of the shell parameter.

  state
      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(), setusershell(), and
  endusershell() functions. They are supported in order to maintain backward
  compatibility with previous versions of the operating 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:

  [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/shells
      Contains the names of legal user shells.

SEE ALSO
  Files: shells(4).

Index for Section 3

Alphabetical listing for G

Top of page