Index for Section 3

Alphabetical listing for G

Bottom of page

getgrent(3)
NAME
  endgrent, fgetgrent, getgrent, getgrgid, getgrnam, setgrent, endgrent_r,
  fgetgrent_r, getgrent_r, getgrgid_r, getgrnam_r, setgrent_r - Access group
  information in the user database

SYNOPSIS
  #include <grp.h>

  void endgrent(
	  void );

  struct group *fgetgrent(
	  FILE *f );

  struct group *getgrent(
	  void );

  struct group *getgrgid(
	  gid_t *gid );

  struct group *getgrnam(
	  const char *name );

  void setgrent(
	  void );

  void endgrent(
	  FILE **gr_fp );

  void fgetgrent_r(
	  FILE *f,
	  stuct group *grp,
	  char *buffer,
	  int len );

  void getgrent_r(
	  stuct group *grp,
	  char *buffer,
	  int len,
	  FILE **gr_fp );

  int getgrgid_r(
	  gid_t *gid,
	  struct group *grp,
	  char *buffer,
	  siz_t len,
	  struct group **result );

  int getgrname(
	  const char *name,
	  struct group *grp,
	  char *buffer,
	  size_t len,
	  struct group **result );

  int setgrent_r(
	  FILE **gr_fp );

  The following obsolete functions do not conform to industry standards and
  are supported only for backward compatibility. You should not use them in
  new designs.

  int getgrgid_r(
	  gid_t gid,
	  struct group *grp,
	  char *buffer,
	  int len );

  int getgrnam_r(
	  const char *name,
	  struct group *grp,
	  char *buffer,
	  int len );

  int setgrent(
	  void );

LIBRARY
  Standard C Library (libc)

STANDARDS
  Interfaces documented on this reference page conform to industry standards
  as follows:

  endgrent(), getgrent(), getgrgid(), getgrgid_r(), getgrnam(), getgrnam_r(),
  setgrent(): XSH5.0

  Refer to the standards(5) reference page for more information about
  industry standards and associated tags.

PARAMETERS
  name
      Specifies the name of the group for which the group file entry is to be
      retrieved.

  gid Specifies the group ID of the group for which the group file entry is
      to be retrieved.

  grp Provides storage to hold the retrieved group structure.

  buffer
      Specifies the working buffer that is able to hold the longest group
      entry in the database (/etc/group).

  len Specifies the length of buffer. This length should be sufficient for
      buf to hold the longest /etc/group line.

  result
      Upon successful return, points to the retrieved group structure. Upon
      unsuccessful return, the result is set to NULL.

  gr_fp
      Specifies a file that contains the next group structure (initialized by
      the user).

  f   Specifies a file that contains the next group structure (initialized by
      the user). This file should have the same format as /etc/group. The
      minimum buffer size is 1024 bytes as defined for SIABUFSIZ in
      /usr/include/sia.h.

  len Specifies the length of buffer. The minimum buffer size is 1024 bytes
      as defined for SIABUFSIZ in /usr/include/sia.h.

DESCRIPTION
  The getgrent(), getgrgid(), getgrnam(), setgrent(), endgrent(), and
  fgetgrent() functions may be used to access the basic group attributes.

  The setgrent() function opens the user database (if not already open) and
  rewinds to the first group entry in the database.

  The getgrent(), getgrnam(), and getgrgid() functions return information
  about the requested group.  The getgrent() function returns the next group
  in the sequential search. The getgrnam() function returns the first group
  in the database with the gr_name field that matches the name parameter. The
  getgrgid() function returns the first group in the database with a gr_gid
  field that matches the gid parameter. The endgrent() function closes the
  user database.

  The group structure, which is returned by the getgrent(), getgrgid(), and
  getgrnam() functions, is defined in the grp.h header file, and contains the
  following members:

  gr_name
      The name of the group.

  gr_passwd
      The password of the group. (Note that this field is not used by the
      system, so its value is meaningless.)

  gr_gid
      The ID of the group.

  gr_mem
      The members of the group.

  The fgetgrent() function gets a group file entry from the file specified by
  the f parameter, rather than assuming that it comes from the /etc/group
  file.	 This file must have the format of the /etc/group file.

  The endgrent_r(), fgetgrent_r(), getgrent_r(), getgrgid_r(), getgrnam_r(),
  and setgrent_r(), functions are the reentrant versions of endgrent(),
  fgetgrent(), getgrent(), getgrgid(), getgrnam(), and setgrent(),
  respectively.

  The endgrent_r(), fgetgrent_r(), getgrent_r(), and setgrent_r(), functions
  use the f and gr_fp parameters to keep track of the calls to the getgrent_r
  function, so that subsequent calls will return subsequent entries from the
  /etc/group file.

  Upon successful completion, the fgetgrent_r(), getgrent_r(), getgrgid_r(),
  and getgrnam_r() functions store their results in the buffer pointed to by
  the grp parameter, with references to the working buffer. The pointer to
  the grp is also stored in result.

NOTES
  The data that is returned by the fgetgrent(), getgrent(), getgrgid(), and
  getgrnam() functions is stored in a static area and will be overwritten on
  subsequent calls to these routines.

  The fgetgrent(), getgrent(), getgrnam(), and getgrgid() functions are not
  supported for multithreaded applications. Instead, their reentrant
  equivalents, fgetgrent_r(), getgrent_r(), getgrnam_r(), and getgrgid_r,()
  should be used with multiple threads.

  Note that the caller is expected to initialize *gr_fp to NULL before using
  it for the first time.

  Note also that entries which are excessively long will be ignored by both
  the reentrant and non-reentrant functions.

RETURN VALUES
  Upon successful completion, the fgetgrent(), getgrent(), getgrgid(), and
  getgrnam() functions return a pointer to a valid group structure containing
  a matching entry. Upon failure, these functions return NULL.

  The getgrgid_r() and getgrnam_r() functions return a value of 0 (zero) on
  success. If the user or group is not found in the password or group
  database, these routines return 0 for the status and a NULL in the returned
  "result" pointer.

  The fgetgrent_r() and getgrent_r() functions, as well as the obsolete
  versions of the getgrgid_r and getgrnam_r functions, return a value of 0
  (zero) for success and a value of -1 for failure.

  The backward-compatible version of the setgrent() function returns a value
  of 1 for success and a value of 0 (zero) for failure.

  The setgrent_r() function returns a value of 0 (zero) for success and a
  value of -1 for failure.

ERRORS
  If any of the following conditions occurs, the getgrgid_r() and
  getgrnam_r() functions set errno to the corresponding value:

  [ERANGE]
      The amount of storage specified by buffer and len is too small to
      contain the data to be referenced by the resulting struct group
      structure.

SEE ALSO
  Functions: getpwent(3)

  Standards: standards(5)

Index for Section 3

Alphabetical listing for G

Top of page