<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> <meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation"> <title>getgrnam_r()--Get Group Information Using Group Name</title> <!-- Begin Header Records ========================================== --> <!-- All rights reserved. Licensed Materials Property of IBM --> <!-- US Government Users Restricted Rights --> <!-- Use, duplication or disclosure restricted by --> <!-- GSA ADP Schedule Contract with IBM Corp. --> <!-- Change History: --> <!-- file cleaned --> <!-- Unix2 SCRIPT J converted by B2H R4.1 (346) (CMS) by V2KEA304 --> <!-- at RCHVMW2 on 17 Feb 1999 at 11:05:09 --> <!-- This file has undergone html cleanup on 05/14/02 by JET --> <link rel="stylesheet" type="text/css" href="../rzahg/ic.css"> </head> <body> <!--End Header Records --><!-- Java sync-link --> <script language="Javascript" src="../rzahg/synch.js" type="text/javascript"> </script> <a name="Top_Of_Page"></a> <h2>getgrnam_r()--Get Group Information Using Group Name</h2> <div class="box" style="width: 80%;"> <br> Syntax<br> <pre> #include <sys/types.h> #include <grp.h> int getgrnam_r(const char <em>*name</em>, struct group <em>*grp</em>, char <em>*buffer</em>, size_t <em>bufsize</em>, struct group <em>**result</em>); </pre> Service Program Name: QSYPAPI<br> <!-- iddvc RMBR --> <br> Default Public Authority: *USE<br> <!-- iddvc RMBR --> <br> Threadsafe: Yes<br> <!-- iddvc RMBR --> <br> </div> <p>The <strong>getgrnam_r()</strong> function updates the group structure pointed to by <em>grp</em> and stores a pointer to that structure in the location pointed to by <em>result</em>. The structure contains an entry from the user database with matching <em>name</em>.</p> <br> <h3>Parameters</h3> <dl> <dt><strong><em>name</em></strong></dt> <dd>(Input) A pointer to a group profile name.<br> </dd> <dt><strong><em>grp</em></strong></dt> <dd>(Input) A pointer to a group structure.<br> </dd> <dt><strong><em>buffer</em></strong></dt> <dd>(Input) A pointer to a buffer from which memory is allocated to hold storage areas referenced by the group structure <em>grp</em>.<br> </dd> <dt><strong><em>bufsize</em></strong></dt> <dd>(Input) The size of <em>buffer</em> in bytes.<br> </dd> <dt><strong><em>result</em></strong></dt> <dd>(Input) A pointer to a location in which a pointer to the updated group structure is stored. If an error occurs or the requested entry cannot be found, a NULL pointer is stored in this location.</dd> </dl> <p>The <samp>struct group</samp>, which is defined in the <strong> grp.h</strong> header file, has the following elements:<br> </p> <table border cellpadding="5"> <tr> <td align="left" valign="top" width="10%">char *</td> <td align="left" valign="top" width="10%">gr_name</td> <td align="left" valign="top" width="80%">Name of the group</td> </tr> <tr> <td align="left" valign="top" width="10%">gid_t</td> <td align="left" valign="top" width="10%">gr_gid</td> <td align="left" valign="top" width="80%">Group ID</td> </tr> <tr> <td align="left" valign="top" width="10%">char **</td> <td align="left" valign="top" width="10%">gr_mem</td> <td align="left" valign="top" width="80%">A null-terminated list of pointers to the individual member profile names. If the group profile does not have any members or if the caller does not have *READ authority to the group profile, the list will be empty.</td> </tr> </table> <br> <h3>Authorities</h3> <p>*READ authority is required to the user profile associated with the <em> name</em>. If the user does not have *READ authority, only the name of the group and the group ID values are returned.</p> <br> <h3>Return Value</h3> <dl compact> <dt><em>0</em></dt> <dd><strong>getgrnam_r</strong> was successful.</dd> <dt><em>Any other value</em></dt> <dd>Failure: The return value contains an error number indicating the error.</dd> </dl> <br> <h3>Error Conditions</h3> <p>If <strong>getgrnam_r()</strong> is not successful, the return value usually indicates one of the following errors. Under some conditions, the value could indicate an error other than those listed here.</p> <table cellpadding="5"> <!-- cols="25 75" --> <tr> <th align="left" valign="bottom">Error condition</th> <th align="left" valign="bottom">Additional information</th> </tr> <tr> <td align="left" valign="top"> <em>[<a href="unix14.htm#EAGAIN">EAGAIN</a>]</em></td> <td align="left" valign="top"> <p>The user profile associated with the <em>name</em> is currently locked by another process.</p> </td> </tr> <tr> <td align="left" valign="top"> <em>[<a href="unix14.htm#EC2">EC2</a>]</em></td> <td align="left" valign="top"> <p>Detected pointer that is not valid.</p> </td> </tr> <tr> <td align="left" valign="top"> <em>[<a href="unix14.htm#EDAMAGE">EDAMAGE</a>]</em></td> <td align="left" valign="top"> <p>The user profile associated with the group name or an internal system object is damaged.</p> </td> </tr> <tr> <td align="left" valign="top"> <em>[<a href="unix14.htm#EINVAL">EINVAL</a>]</em></td> <td align="left" valign="top"> <p>Value is not valid. Check the job log for messages.</p> </td> </tr> <tr> <td align="left" valign="top"> <em>[<a href="unix14.htm#ENOENT">ENOENT</a>]</em></td> <td align="left" valign="top"> <p>The user profile associated with the <em>name</em> was not found or the profile name specified is not a group profile.</p> </td> </tr> <tr> <td align="left" valign="top"> <em>[<a href="unix14.htm#ERANGE">ERANGE</a>]</em></td> <td align="left" valign="top"> <p>Insufficient storage was supplied by <em>buffer</em> and <em>bufsize</em> to contain the data to be referenced by the resulting group structure.</p> </td> </tr> <tr> <td align="left" valign="top"> <em>[<a href="unix14.htm#EUNKNOWN">EUNKNOWN</a>]</em></td> <td align="left" valign="top"> <p>Unknown system state. Check the job log for a CPF9872 message.</p> </td> </tr> </table> <br> <h3>Related Information</h3> <ul> <li>The <<strong>grp.h</strong>> file (see )<br> </li> <li><a href="gtgrnamr.htm">getgrnam()</a>--Get Group Information Using Group Name</li> </ul> <br> <h3>Example</h3> <p>See <a href="../apiref/aboutapis.htm#codedisclaimer">Code disclaimer information</a> for information pertaining to code examples.</p> <p>The following example gets the group information for the group GROUP1. The gid is 91. There are two group members, CLIFF and PATRICK.</p> <pre> #include <sys/types.h> #include <grp.h> #include <stdio.h> #include <errno.h> main() { short int lp; struct group grp; struct group * grpptr=&grp; struct group * tempGrpPtr; char grpbuffer[200]; int grplinelen = sizeof(grpbuffer); if ((getgrnam_r("GROUP1",grpptr,grpbuffer,grplinelen,&tempGrpPtr))!=0) perror("getgrnam_r() error."); else { printf("\nThe group name is: %s\n", grp.gr_name); printf("The gid is: %u\n", grp.gr_gid); for (lp = 1; NULL != *(grp.gr_mem); lp++, (grp.gr_mem)++) printf("Group Member %d is: %s\n", lp, *(grp.gr_mem)); } } </pre> <p><strong>Output:</strong></p> <pre> The group name is: GROUP1 The gid is: 91 Group member 1 is: CLIFF Group member 2 is: PATRICK </pre> <hr> API introduced: V4R4 <hr> <center> <table cellpadding="2" cellspacing="2"> <tr align="center"> <td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href= "unix.htm">UNIX-Type APIs</a> | <a href="aplist.htm">APIs by category</a></td> </tr> </table> </center> </body> </html>