getgrnam_r()

Arguments:

name

The name of the group you want to get information about.

grp

A pointer to a group structure where the function can store information about the group.

buffer

A buffer from which to allocate any memory required.

bufsize

The size of the buffer.

result

The address of a pointer that getgrgid_r() sets to the same pointer as grp on success, or to NULL if the function can't find the group.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The getgrnam_r() function updates the group structure pointed to by grp and stores a pointer to that structure at the location pointed to by result. The structure contains an entry that is from the group database and has a matching name.

This function allocates storage referenced by the group structure from the memory provided with the buffer parameter, which is bufsize characters in size. A call to sysconf(_SC_GETGR_R_SIZE_MAX) returns either -1 without changing errno or an initial value suggested for the size of this buffer. For most cases, this initial suggestion is sufficient; however, the _SC_GETGR_R_SIZE_MAX value is not guaranteed to be enough to hold all the groups returned. To be certain that you pass a large enough buffer for this case (and thus, don't miss any information), see the code sample below.

The getgrnam_r() function stores a NULL pointer at the location pointed by result on error or if the requested entry isn't found.

Returns:

Zero for success, or an error number if an error occurred.

Errors:

ERANGE

Insufficient storage was supplied via buffer and bufsize to contain the group structure.

The getgrnam_r() function uses the following functions, and as a result, errno can be set to an error for any of these calls:

• fclose()
• fgets()
• fopen()
• fseek()
• rewind()

Examples:

The sysconf(_SC_GETGR_R_SIZE_MAX) call may return -1 if there is no hard limit on the size of the buffer needed to store all the groups returned. This example shows how an application can allocate a buffer of sufficient size to work with getgrnam_r().

long int initlen = sysconf( _SC_GETGR_R_SIZE_MAX );
size_t len;
if ( initlen == -1 ) {
  /* Default initial length */
  len = 1024;
}
else {
  len = (size_t) initlen;
}

struct group result;
struct group *resultp;
char *buffer = malloc( len );
if ( buffer == NULL ) {
  /* Handle error */
}

int err;
while ( ( err = getgrnam_r("somegroup", &result, buffer, len, &resultp ) )
                 == ERANGE) {
  size_t newlen = 2 * len;
  if ( newlen < len ) {
    /* Handle error */
  }
  len = newlen;
  char *newbuffer = realloc( buffer, len );
  if ( newbuffer == NULL ) {
    /* Handle error */
  }
  buffer = newbuffer;
}

if ( err != 0 ) {
  /* Handle error */
}

free ( buffer );

Classification:

POSIX 1003.1