getpwnam(3) - perldoc - phpman

    getpwnam NAME
    getgrnam NAME
    gethostbyname NAME
    getnetbyname NAME
    getprotobyname NAME
    getpwuid UID
    getgrgid GID
    getservbyname NAME,PROTO
    gethostbyaddr ADDR,ADDRTYPE
    getnetbyaddr ADDR,ADDRTYPE
    getprotobynumber NUMBER
    getservbyport PORT,PROTO
    getpwent
    getgrent
    gethostent
    getnetent
    getprotoent
    getservent
    setpwent
    setgrent
    sethostent STAYOPEN
    setnetent STAYOPEN
    setprotoent STAYOPEN
    setservent STAYOPEN
    endpwent
    endgrent
    endhostent
    endnetent
    endprotoent
    endservent
            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 shadow(3) functions as found in
            System V (this includes Solaris and Linux). Those systems that
            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 raw addresses returned by the corresponding
            library call. In the Internet domain, each address is four bytes
            long; you can unpack it by saying something like:

                my ($w,$x,$y,$z) = unpack('W4',$addr[0]);

            The Socket library makes this slightly easier:

                use Socket;
                my $iaddr = inet_aton("127.1"); # or whatever address
                my $name  = gethostbyaddr($iaddr, AF_INET);

                # or going the other way
                my $straddr = inet_ntoa($iaddr);

            In the opposite way, to resolve a hostname to the IP address you
            can write this:

                use Socket;
                my $packed_ip = gethostbyname("www.perl.org");
                my $ip_address;
                if (defined $packed_ip) {
                    $ip_address = inet_ntoa($packed_ip);
                }

            Make sure "gethostbyname" is called in SCALAR context and that
            its return value is checked for definedness.

            The "getprotobynumber" function, even though it only takes one
            argument, has the precedence of a list operator, so beware:

                getprotobynumber $number eq 'icmp'   # WRONG
                getprotobynumber($number eq 'icmp')  # actually means this
                getprotobynumber($number) eq 'icmp'  # better this way

            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;
               my $is_his = (stat($filename)->uid == pwent($whoever)->uid);

            Even though it looks as though they're the same method calls
            (uid), they aren't, because a "File::stat" object is different
            from a "User::pwent" object.

            Many of these functions are not safe in a multi-threaded
            environment where more than one thread can be using them. In
            particular, functions like "getpwent()" iterate per-process and
            not per-thread, so if two threads are simultaneously iterating,
            neither will get all the records.

            Some systems have thread-safe versions of some of the functions,
            such as "getpwnam_r()" instead of "getpwnam()". There, Perl
            automatically and invisibly substitutes the thread-safe version,
            without notice. This means that code that safely runs on some
            systems can fail on others that lack the thread-safe versions.

            Portability issues: "getpwnam" in perlport to "endservent" in
            perlport.