| 1 | GETGRENT(3) BSD Programmer's Manual GETGRENT(3) |
| 2 | |
| 3 | N\bNA\bAM\bME\bE |
| 4 | g\bge\bet\btg\bgr\bre\ben\bnt\bt, g\bge\bet\btg\bgr\brn\bna\bam\bm, g\bge\bet\btg\bgr\brg\bgi\bid\bd, s\bse\bet\btg\bgr\bro\bou\bup\bpe\ben\bnt\bt, s\bse\bet\btg\bgr\bre\ben\bnt\bt, e\ben\bnd\bdg\bgr\bre\ben\bnt\bt - group |
| 5 | database operations |
| 6 | |
| 7 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 8 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<g\bgr\brp\bp.\b.h\bh>\b> |
| 9 | |
| 10 | _\bs_\bt_\br_\bu_\bc_\bt _\bg_\br_\bo_\bu_\bp _\b* |
| 11 | g\bge\bet\btg\bgr\bre\ben\bnt\bt(_\bv_\bo_\bi_\bd); |
| 12 | |
| 13 | _\bs_\bt_\br_\bu_\bc_\bt _\bg_\br_\bo_\bu_\bp _\b* |
| 14 | g\bge\bet\btg\bgr\brn\bna\bam\bm(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bn_\ba_\bm_\be); |
| 15 | |
| 16 | _\bs_\bt_\br_\bu_\bc_\bt _\bg_\br_\bo_\bu_\bp _\b* |
| 17 | g\bge\bet\btg\bgr\brg\bgi\bid\bd(_\bg_\bi_\bd_\b__\bt _\bg_\bi_\bd); |
| 18 | |
| 19 | _\bs_\bt_\br_\bu_\bc_\bt _\bg_\br_\bo_\bu_\bp _\b* |
| 20 | s\bse\bet\btg\bgr\bro\bou\bup\bpe\ben\bnt\bt(_\bi_\bn_\bt _\bs_\bt_\ba_\by_\bo_\bp_\be_\bn); |
| 21 | |
| 22 | _\bi_\bn_\bt |
| 23 | s\bse\bet\btg\bgr\bre\ben\bnt\bt(_\bv_\bo_\bi_\bd); |
| 24 | |
| 25 | _\bv_\bo_\bi_\bd |
| 26 | e\ben\bnd\bdg\bgr\bre\ben\bnt\bt(_\bv_\bo_\bi_\bd); |
| 27 | |
| 28 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 29 | These functions operate on the group database file _\b/_\be_\bt_\bc_\b/_\bg_\br_\bo_\bu_\bp which is |
| 30 | described in group(5). Each line of the database is defined by the |
| 31 | structure _\bg_\br_\bo_\bu_\bp found in the include file <_\bg_\br_\bp_\b._\bh>: |
| 32 | |
| 33 | struct group { |
| 34 | char *gr_name; /* group name */ |
| 35 | char *gr_passwd; /* group password */ |
| 36 | gid_t gr_gid; /* group id */ |
| 37 | char **gr_mem; /* group members */ |
| 38 | }; |
| 39 | |
| 40 | The functions g\bge\bet\btg\bgr\brn\bna\bam\bm() and g\bge\bet\btg\bgr\brg\bgi\bid\bd() search the group database for the |
| 41 | given group name pointed to by _\bn_\ba_\bm_\be or the group id pointed to by _\bg_\bi_\bd, |
| 42 | respectively, returning the first one encountered. Identical group names |
| 43 | or group gids may result in undefined behavior. |
| 44 | |
| 45 | The g\bge\bet\btg\bgr\bre\ben\bnt\bt() function sequentially reads the group database and is in- |
| 46 | tended for programs that wish to step through the complete list of |
| 47 | groups. |
| 48 | |
| 49 | All three routines will open the group file for reading, if necesssary. |
| 50 | |
| 51 | The s\bse\bet\btg\bgr\bro\bou\bup\bpe\ben\bnt\bt() function opens the file, or rewinds it if it is already |
| 52 | open. If _\bs_\bt_\ba_\by_\bo_\bp_\be_\bn is non-zero, file descriptors are left open, signifi- |
| 53 | cantly speeding functions subsequent calls. This functionality is unnec- |
| 54 | essary for g\bge\bet\btg\bgr\bre\ben\bnt\bt() as it doesn't close its file descriptors by de- |
| 55 | fault. It should also be noted that it is dangerous for long-running |
| 56 | programs to use this functionality as the group file may be updated. |
| 57 | |
| 58 | The s\bse\bet\btg\bgr\bre\ben\bnt\bt() function is identical to s\bse\bet\btg\bgr\bro\bou\bup\bpe\ben\bnt\bt() with an argument of |
| 59 | zero. |
| 60 | |
| 61 | The e\ben\bnd\bdg\bgr\bre\ben\bnt\bt() function closes any open files. |
| 62 | |
| 63 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 64 | The functions g\bge\bet\btg\bgr\bre\ben\bnt\bt(), g\bge\bet\btg\bgr\brn\bna\bam\bm(), and g\bge\bet\btg\bgr\brg\bgi\bid\bd(), return a pointer to |
| 65 | the group entry if successful; if end-of-file is reached or an error oc- |
| 66 | curs a null pointer is returned. The functions s\bse\bet\btg\bgr\bro\bou\bup\bpe\ben\bnt\bt() and |
| 67 | s\bse\bet\btg\bgr\bre\ben\bnt\bt() return the value 1 if successful, otherwise the value 0 is re- |
| 68 | turned. The functions e\ben\bnd\bdg\bgr\bre\ben\bnt\bt() and s\bse\bet\btg\bgr\brf\bfi\bil\ble\be() have no return value. |
| 69 | |
| 70 | F\bFI\bIL\bLE\bES\bS |
| 71 | /etc/group group database file |
| 72 | |
| 73 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 74 | g\bge\bet\btp\bpw\bwe\ben\bnt\bt(_\b3), g\bgr\bro\bou\bup\bp(_\b5) |
| 75 | |
| 76 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 77 | The functions e\ben\bnd\bdg\bgr\bre\ben\bnt\bt(), g\bge\bet\btg\bgr\bre\ben\bnt\bt(), g\bge\bet\btg\bgr\brn\bna\bam\bm(), g\bge\bet\btg\bgr\brg\bgi\bid\bd(), and |
| 78 | s\bse\bet\btg\bgr\bre\ben\bnt\bt() appeared in Version 7 AT&T UNIX. The functions s\bse\bet\btg\bgr\brf\bfi\bil\ble\be() |
| 79 | and s\bse\bet\btg\bgr\bro\bou\bup\bpe\ben\bnt\bt() appeared in 4.3BSD-Reno. |
| 80 | |
| 81 | C\bCO\bOM\bMP\bPA\bAT\bTI\bIB\bBI\bIL\bLI\bIT\bTY\bY |
| 82 | The historic function s\bse\bet\btg\bgr\brf\bfi\bil\ble\be(), which allowed the specification of al- |
| 83 | ternate password databases, has been deprecated and is no longer avail- |
| 84 | able. |
| 85 | |
| 86 | B\bBU\bUG\bGS\bS |
| 87 | The functions g\bge\bet\btg\bgr\bre\ben\bnt\bt(), g\bge\bet\btg\bgr\brn\bna\bam\bm(), g\bge\bet\btg\bgr\brg\bgi\bid\bd(), s\bse\bet\btg\bgr\bro\bou\bup\bpe\ben\bnt\bt() and |
| 88 | s\bse\bet\btg\bgr\bre\ben\bnt\bt() leave their results in an internal static object and return a |
| 89 | pointer to that object. Subsequent calls to the same function will modify |
| 90 | the same object. |
| 91 | |
| 92 | The functions g\bge\bet\btg\bgr\bre\ben\bnt\bt(), e\ben\bnd\bdg\bgr\bre\ben\bnt\bt(), s\bse\bet\btg\bgr\bro\bou\bup\bpe\ben\bnt\bt(), and s\bse\bet\btg\bgr\bre\ben\bnt\bt() are |
| 93 | fairly useless in a networked environment and should be avoided, if pos- |
| 94 | sible. |
| 95 | |
| 96 | 4.4BSD June 4, 1993 2 |