=over

=item getpwnam NAME

=item getgrnam NAME

=item gethostbyname NAME

=item getnetbyname NAME

=item getprotobyname NAME

=item getpwuid UID

=item getgrgid GID

=item getservbyname NAME,PROTO

=item gethostbyaddr ADDR,ADDRTYPE

=item getnetbyaddr ADDR,ADDRTYPE

=item getprotobynumber NUMBER

=item getservbyport PORT,PROTO

=item getpwent

=item getgrent

=item gethostent

=item getnetent

=item getprotoent

=item getservent

=item setpwent

=item setgrent

=item sethostent STAYOPEN

=item setnetent STAYOPEN

=item setprotoent STAYOPEN

=item setservent STAYOPEN

=item endpwent

=item endgrent

=item endhostent

=item endnetent

=item endprotoent

=item endservent

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.)

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 I<getpw*()> the fields C<$quota>, C<$comment>, and C<$expire> are
special cases in the sense that in many systems they are unsupported.
If the C<$quota> is unsupported, it is an empty scalar.  If it is
supported, it usually encodes the disk quota.  If the C<$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 C<$change> or C<$age>, fields that have
to do with password aging.  In some systems the C<$comment> field may
be C<$class>.  The C<$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 F<pwd.h> file.  You can also find
out from within Perl what your C<$quota> and C<$comment> fields mean
and whether you have the C<$expire> field by using the C<Config> module
and the values C<d_pwquota>, C<d_pwage>, C<d_pwchange>, C<d_pwcomment>,
and C<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.  Those that incorrectly implement a separate library
call are not supported.

The C<$members> value returned by I<getgr*()> is a space separated list of
the login names of the members of the group.

For the I<gethost*()> functions, if the C<h_errno> variable is supported in
C, it will be returned to you via C<$?> if the function call fails.  The
C<@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 also provided in modules:
C<File::stat>, C<Net::hostent>, C<Net::netent>, C<Net::protoent>, C<Net::servent>,
C<Time::gmtime>, C<Time::localtime>, and C<User::grent>.  These override the
normal built-in, replacing them with 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 C<File::stat> object is different from a C<User::pwent> object.

=back