getgrent
These routines perform the same functions as their counterparts in the
system library. In list context, the return values from the various get
routines are as follows:
($name,$passwd,$uid,$gid,
$quota,$comment,$gcos,$dir,$shell,$expire) = getpw*
($name,$passwd,$gid,$members) = getgr*
($name,$aliases,$addrtype,$length,@addrs) = gethost*
($name,$aliases,$addrtype,$net) = getnet*
($name,$aliases,$proto) = getproto*
($name,$aliases,$port,$proto) = getserv*
(If the entry doesn't exist you get a null list.)
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, because
of 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:
$uid = getpwnam($name);
$name = getpwuid($num);
$name = getpwent();
$gid = getgrnam($name);
$name = getgrgid($num);
$name = getgrent();
#etc.
In getpw*() the fields $quota, $comment, and $expire are special
cases in the sense that in many systems they are unsupported. 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 your getpwnam(3) documentation and your 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 only
supported 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 shadow(3) functions as found in
System V ( this includes Solaris and Linux.) Those systems which implement a
proprietary shadow password facility are unlikely to be supported.
The $members value returned by getgr*() is a space separated list of
the login names of the members of the group.
For the gethost*() functions, if the h_errno
variable is supported in C, it will be returned to
you via $?
if the function call
fails. The @addrs
value
returned by a successful call is a list of the raw addresses returned by the
corresponding system library call. In the Internet domain, each address is
four bytes long and you can unpack it by saying something like:
($a,$b,$c,$d) = unpack('C4',$addr[0]);
The Socket library makes this slightly easier:
use Socket;
$iaddr = inet_aton("127.1"); # or whatever address
$name = gethostbyaddr($iaddr, AF_INET);
# or going the other way
$straddr = inet_ntoa($iaddr);
If you get tired of remembering which element of the return list contains
which return value, by-name interfaces are provided in standard modules: File::stat
, Net::hostent
, Net::netent
, Net::protoent
,
Net::servent
, Time::gmtime
, Time::localtime
,
and User::grent
. These
override the normal built-ins, supplying versions that return objects with the
appropriate names for each field. For example:
use File::stat;
use User::pwent;
$is_his = (stat($filename)->uid == pwent($whoever)->uid);
Even though it looks like they're the same method calls (uid), they aren't,
because a File::stat
object is
different from a User::pwent
object.