These routines are the same as their counterparts in the system C library. In list context, the return values from the various get routines are as follows:

#    0        1          2           3         4
my ( $name,   $passwd,   $gid,       $members  ) = getgr*
my ( $name,   $aliases,  $addrtype,  $net      ) = getnet*
my ( $name,   $aliases,  $port,      $proto    ) = getserv*
my ( $name,   $aliases,  $proto                ) = getproto*
my ( $name,   $aliases,  $addrtype,  $length,  @addrs ) = gethost*
my ( $name,   $passwd,   $uid,       $gid,     $quota,
   $comment,  $gcos,     $dir,       $shell,   $expire ) = getpw*
#    5        6          7           8         9

(If the entry doesn't exist, the return value is a single meaningless true value.)

The exact meaning of the $gcos field varies but it usually contains the real name of the user (as opposed to the login name) and other information pertaining to the user. Beware, however, that in many system users are able to change this information and therefore it cannot be trusted and therefore the $gcos is tainted (see perlsec). The $passwd and $shell, user's encrypted password and login shell, are also tainted, for the same reason.

In scalar context, you get the name, unless the function was a lookup by name, in which case you get the other thing, whatever it is. (If the entry doesn't exist you get the undefined value.) For example:

my $uid   = getpwnam($name);
my $name  = getpwuid($num);
my $name  = getpwent();
my $gid   = getgrnam($name);
my $name  = getgrgid($num);
my $name  = getgrent();
# etc.

In getpw*() the fields $quota, $comment, and $expire are special in that they are unsupported on many systems. If the $quota is unsupported, it is an empty scalar. If it is supported, it usually encodes the disk quota. If the $comment field is unsupported, it is an empty scalar. If it is supported it usually encodes some administrative comment about the user. In some systems the $quota field may be $change or $age, fields that have to do with password aging. In some systems the $comment field may be $class. The $expire field, if present, encodes the expiration period of the account or the password. For the availability and the exact meaning of these fields in your system, please consult getpwnam(3) and your system's pwd.h file. You can also find out from within Perl what your $quota and $comment fields mean and whether you have the $expire field by using the Config module and the values d_pwquota, d_pwage, d_pwchange, d_pwcomment, and d_pwexpire. Shadow password files are supported only if your vendor has implemented them in the intuitive fashion that calling the regular C library routines gets the shadow versions if you're running under privilege or if there exists the