perlfunc
gods
<P>
gethostbyname - get host record given name
<P>
<HR>
<P>
gethostbyname
<FONT SIZE=-1>NAME</FONT>
<P>
<HR>
<P>
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:
<P>
<PRE> ($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*
</PRE>
<P>
(If the entry doesn't exist you get a null list.)
<P>
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:
<P>
<PRE> $uid = getpwnam($name);
$name = getpwuid($num);
$name = getpwent();
$gid = getgrnam($name);
$name = getgrgid($num;
$name = getgrent();
#etc.
</PRE>
<P>
In <EM>getpw*()</EM> the fields <CODE>$quota</CODE>, <CODE>$comment</CODE>, and <CODE>$expire</CODE> are special cases in the sense that in many systems they are unsupported.
If the
<CODE>$quota</CODE> is unsupported, it is an empty scalar. If it is supported, it usually
encodes the disk quota. If the <CODE>$comment</CODE> 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
<CODE>$quota</CODE> field may be <CODE>$change</CODE> or <CODE>$age</CODE>, fields that have to do with password aging. In some systems the <CODE>$comment</CODE> field may be <CODE>$class</CODE>. The <CODE>$expire</CODE>
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
<CODE>getpwnam(3)</CODE> documentation and your
<EM>pwd.h</EM> file. You can also find out from within Perl which meaning your <CODE>$quota</CODE> and <CODE>$comment</CODE> fields have and whether you have the <CODE>$expire</CODE>
field by using the <CODE>Config</CODE> module and the values <CODE>d_pwquota</CODE>, <CODE>d_pwage</CODE>,
<CODE>d_pwchange</CODE>, <CODE>d_pwcomment</CODE>, and <CODE>d_pwexpire</CODE>.
<P>
The <CODE>$members</CODE> value returned by <EM>getgr*()</EM> is a space separated list of the login names of the members of the group.
<P>
For the <EM>gethost*()</EM> functions, if the <CODE>h_errno</CODE> variable is supported in
<FONT SIZE=-1>C,</FONT> it will be returned to you via <CODE>$?</CODE> if the function call fails. The
<CODE>@addrs</CODE> 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:
<P>
<PRE> ($a,$b,$c,$d) = unpack('C4',$addr[0]);
</PRE>
<P>
If you get tired of remembering which element of the return list contains
which return value, by-name interfaces are also provided in modules:
<CODE>File::stat</CODE>, <CODE>Net::hostent</CODE>, <CODE>Net::netent</CODE>, <CODE>Net::protoent</CODE>, <CODE>Net::servent</CODE>,
<CODE>Time::gmtime</CODE>, <CODE>Time::localtime</CODE>, and <CODE>User::grent</CODE>. These override the normal built-in, replacing them with versions that
return objects with the appropriate names for each field. For example:
<P>
<PRE> use <U>File::stat</U>;
use User::pwent;
$is_his = (stat($filename)->uid == pwent($whoever)->uid);
</PRE>
<P>
Even though it looks like they're the same method calls (uid), they aren't,
because a <CODE>File::stat</CODE> object is different from a <CODE>User::pwent</CODE> object.
<HR>