*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->Tru64 Unix man pages -> fgetgrent (3)              
Title
Content
Arch
Section
 

getgrent(3)

Contents


NAME    [Toc]    [Back]

       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    [Toc]    [Back]

       #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    [Toc]    [Back]

       Standard C Library (libc)

STANDARDS    [Toc]    [Back]

       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    [Toc]    [Back]

       Specifies  the  name of the group for which the group file
       entry is to be retrieved.  Specifies the group ID  of  the
       group  for  which the group file entry is to be retrieved.
       Provides storage to hold the  retrieved  group  structure.
       Specifies  the  working  buffer  that  is able to hold the
       longest group entry in the database (/etc/group).   Specifies
  the  length  of buffer. This length should be sufficient
 for buf to hold the longest /etc/group  line.   Upon
       successful  return,  points  to the retrieved group structure.
 Upon unsuccessful return, the result is set to NULL.
       Specifies  a  file  that contains the next group structure
       (initialized by the user).  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.  Specifies the length of  buffer.  The
       minimum buffer size is 1024 bytes as defined for SIABUFSIZ
       in /usr/include/sia.h.

DESCRIPTION    [Toc]    [Back]

       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: The
       name  of the group.  The password of the group. (Note that
       this field is not used by the  system,  so  its  value  is
       meaningless.)   The  ID  of the group.  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    [Toc]    [Back]

       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    [Toc]    [Back]

       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    [Toc]    [Back]

       If any  of  the  following  conditions  occurs,  the  getgrgid_r()
 and getgrnam_r() functions set errno to the corresponding
 value:  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    [Toc]    [Back]

      
      
       Functions: getpwent(3)

       Standards: standards(5)



                                                      getgrent(3)
[ Back ]
 Similar pages
Name OS Title
endpwent_r Tru64 Access user attribute information in the user database
putpwent Tru64 Access user attribute information in the user database
getpwuid_r Tru64 Access user attribute information in the user database
getpwnam_r Tru64 Access user attribute information in the user database
setpwent Tru64 Access user attribute information in the user database
setpwent_r Tru64 Access user attribute information in the user database
setpwfile Tru64 Access user attribute information in the user database
getpwuid Tru64 Access user attribute information in the user database
fgetpwent Tru64 Access user attribute information in the user database
fgetpwent_r Tru64 Access user attribute information in the user database
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service