.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Socket 3perl"
.TH Socket 3perl "2011-09-26" "perl v5.14.2" "Perl Programmers Reference Guide"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Socket, sockaddr_in, sockaddr_un, inet_aton, inet_ntoa, inet_pton, inet_ntop \- load the C socket.h defines and structure manipulators
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Socket;
\&
\&    $proto = getprotobyname(\*(Aqudp\*(Aq);
\&    socket(Socket_Handle, PF_INET, SOCK_DGRAM, $proto);
\&    $iaddr = gethostbyname(\*(Aqhishost.com\*(Aq);
\&    $port = getservbyname(\*(Aqtime\*(Aq, \*(Aqudp\*(Aq);
\&    $sin = sockaddr_in($port, $iaddr);
\&    send(Socket_Handle, 0, 0, $sin);
\&
\&    $proto = getprotobyname(\*(Aqtcp\*(Aq);
\&    socket(Socket_Handle, PF_INET, SOCK_STREAM, $proto);
\&    $port = getservbyname(\*(Aqsmtp\*(Aq, \*(Aqtcp\*(Aq);
\&    $sin = sockaddr_in($port,inet_aton("127.1"));
\&    $sin = sockaddr_in(7,inet_aton("localhost"));
\&    $sin = sockaddr_in(7,INADDR_LOOPBACK);
\&    connect(Socket_Handle,$sin);
\&
\&    ($port, $iaddr) = sockaddr_in(getpeername(Socket_Handle));
\&    $peer_host = gethostbyaddr($iaddr, AF_INET);
\&    $peer_addr = inet_ntoa($iaddr);
\&
\&    $proto = getprotobyname(\*(Aqtcp\*(Aq);
\&    socket(Socket_Handle, PF_UNIX, SOCK_STREAM, $proto);
\&    unlink(\*(Aq/var/run/usock\*(Aq);
\&    $sun = sockaddr_un(\*(Aq/var/run/usock\*(Aq);
\&    connect(Socket_Handle,$sun);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module is just a translation of the C \fIsocket.h\fR file.
Unlike the old mechanism of requiring a translated \fIsocket.ph\fR
file, this uses the \fBh2xs\fR program (see the Perl source distribution)
and your native C compiler.  This means that it has a 
far more likely chance of getting the numbers right.  This includes
all of the commonly used pound-defines like \s-1AF_INET\s0, \s-1SOCK_STREAM\s0, etc.
.PP
Also, some common socket \*(L"newline\*(R" constants are provided: the
constants \f(CW\*(C`CR\*(C'\fR, \f(CW\*(C`LF\*(C'\fR, and \f(CW\*(C`CRLF\*(C'\fR, as well as \f(CW$CR\fR, \f(CW$LF\fR, and
\&\f(CW$CRLF\fR, which map to \f(CW\*(C`\e015\*(C'\fR, \f(CW\*(C`\e012\*(C'\fR, and \f(CW\*(C`\e015\e012\*(C'\fR.  If you do
not want to use the literal characters in your programs, then use
the constants provided here.  They are not exported by default, but can
be imported individually, and with the \f(CW\*(C`:crlf\*(C'\fR export tag:
.PP
.Vb 1
\&    use Socket qw(:DEFAULT :crlf);
.Ve
.PP
In addition, some structure manipulation functions are available:
.IP "inet_aton \s-1HOSTNAME\s0" 4
.IX Item "inet_aton HOSTNAME"
Takes a string giving the name of a host, and translates that to an
opaque string (if programming in C, struct in_addr). Takes arguments
of both the 'rtfm.mit.edu' type and '18.181.0.24'. If the host name
cannot be resolved, returns undef.  For multi-homed hosts (hosts with
more than one address), the first address found is returned.
.Sp
For portability do not assume that the result of \fIinet_aton()\fR is 32
bits wide, in other words, that it would contain only the IPv4 address
in network order.
.IP "inet_ntoa \s-1IP_ADDRESS\s0" 4
.IX Item "inet_ntoa IP_ADDRESS"
Takes a string (an opaque string as returned by \fIinet_aton()\fR,
or a v\-string representing the four octets of the IPv4 address in
network order) and translates it into a string of the form 'd.d.d.d'
where the 'd's are numbers less than 256 (the normal human-readable
four dotted number notation for Internet addresses).
.IP "\s-1INADDR_ANY\s0" 4
.IX Item "INADDR_ANY"
Note: does not return a number, but a packed string.
.Sp
Returns the 4\-byte wildcard ip address which specifies any
of the hosts ip addresses.  (A particular machine can have
more than one ip address, each address corresponding to
a particular network interface. This wildcard address
allows you to bind to all of them simultaneously.)
Normally equivalent to inet_aton('0.0.0.0').
.IP "\s-1INADDR_BROADCAST\s0" 4
.IX Item "INADDR_BROADCAST"
Note: does not return a number, but a packed string.
.Sp
Returns the 4\-byte 'this\-lan' ip broadcast address.
This can be useful for some protocols to solicit information
from all servers on the same \s-1LAN\s0 cable.
Normally equivalent to inet_aton('255.255.255.255').
.IP "\s-1INADDR_LOOPBACK\s0" 4
.IX Item "INADDR_LOOPBACK"
Note \- does not return a number.
.Sp
Returns the 4\-byte loopback address.  Normally equivalent
to inet_aton('localhost').
.IP "\s-1INADDR_NONE\s0" 4
.IX Item "INADDR_NONE"
Note \- does not return a number.
.Sp
Returns the 4\-byte 'invalid' ip address.  Normally equivalent
to inet_aton('255.255.255.255').
.IP "\s-1IN6ADDR_ANY\s0" 4
.IX Item "IN6ADDR_ANY"
Returns the 16\-byte wildcard IPv6 address. Normally equivalent
to inet_pton(\s-1AF_INET6\s0, \*(L"::\*(R")
.IP "\s-1IN6ADDR_LOOPBACK\s0" 4
.IX Item "IN6ADDR_LOOPBACK"
Returns the 16\-byte loopback IPv6 address. Normally equivalent
to inet_pton(\s-1AF_INET6\s0, \*(L"::1\*(R")
.IP "sockaddr_family \s-1SOCKADDR\s0" 4
.IX Item "sockaddr_family SOCKADDR"
Takes a sockaddr structure (as returned by \fIpack_sockaddr_in()\fR,
\&\fIpack_sockaddr_un()\fR or the perl builtin functions \fIgetsockname()\fR and
\&\fIgetpeername()\fR) and returns the address family tag.  It will match the
constant \s-1AF_INET\s0 for a sockaddr_in and \s-1AF_UNIX\s0 for a sockaddr_un.  It
can be used to figure out what unpacker to use for a sockaddr of
unknown type.
.IP "sockaddr_in \s-1PORT\s0, \s-1ADDRESS\s0" 4
.IX Item "sockaddr_in PORT, ADDRESS"
.PD 0
.IP "sockaddr_in \s-1SOCKADDR_IN\s0" 4
.IX Item "sockaddr_in SOCKADDR_IN"
.PD
In a list context, unpacks its \s-1SOCKADDR_IN\s0 argument and returns an array
consisting of (\s-1PORT\s0, \s-1ADDRESS\s0).  In a scalar context, packs its (\s-1PORT\s0,
\&\s-1ADDRESS\s0) arguments as a \s-1SOCKADDR_IN\s0 and returns it.  If this is confusing,
use \fIpack_sockaddr_in()\fR and \fIunpack_sockaddr_in()\fR explicitly.
.IP "pack_sockaddr_in \s-1PORT\s0, \s-1IP_ADDRESS\s0" 4
.IX Item "pack_sockaddr_in PORT, IP_ADDRESS"
Takes two arguments, a port number and an opaque string, \s-1IP_ADDRESS\s0
(as returned by \fIinet_aton()\fR, or a v\-string).  Returns the sockaddr_in
structure with those arguments packed in with \s-1AF_INET\s0 filled in.  For
Internet domain sockets, this structure is normally what you need for
the arguments in \fIbind()\fR, \fIconnect()\fR, and \fIsend()\fR, and is also returned
by \fIgetpeername()\fR, \fIgetsockname()\fR and \fIrecv()\fR.
.IP "unpack_sockaddr_in \s-1SOCKADDR_IN\s0" 4
.IX Item "unpack_sockaddr_in SOCKADDR_IN"
Takes a sockaddr_in structure (as returned by \fIpack_sockaddr_in()\fR) and
returns an array of two elements: the port and an opaque string
representing the \s-1IP\s0 address (you can use \fIinet_ntoa()\fR to convert the
address to the four-dotted numeric format).  Will croak if the
structure does not have \s-1AF_INET\s0 in the right place.
.IP "sockaddr_in6 \s-1PORT\s0, \s-1IP6_ADDRESS\s0, [ \s-1SCOPE_ID\s0, [ \s-1FLOWINFO\s0 ] ]" 4
.IX Item "sockaddr_in6 PORT, IP6_ADDRESS, [ SCOPE_ID, [ FLOWINFO ] ]"
.PD 0
.IP "sockaddr_in6 \s-1SOCKADDR_IN6\s0" 4
.IX Item "sockaddr_in6 SOCKADDR_IN6"
.PD
In list context, unpacks its \s-1SOCKADDR_IN6\s0 argument according to
\&\fIunpack_sockaddr_in6()\fR. In scalar context, packs its arguments according to
\&\fIpack_sockaddr_in6()\fR.
.IP "pack_sockaddr_in6 \s-1PORT\s0, \s-1IP6_ADDRESS\s0, [ \s-1SCOPE_ID\s0, [ \s-1FLOWINFO\s0 ] ]" 4
.IX Item "pack_sockaddr_in6 PORT, IP6_ADDRESS, [ SCOPE_ID, [ FLOWINFO ] ]"
Takes two to four arguments, a port number, an opaque string (as returned by
\&\fIinet_pton()\fR), optionally a scope \s-1ID\s0 number, and optionally a flow label
number. Returns the sockaddr_in6 structure with those arguments packed in
with \s-1AF_INET6\s0 filled in. IPv6 equivalent of \fIpack_sockaddr_in()\fR.
.IP "unpack_sockaddr_in6 \s-1SOCKADDR_IN6\s0" 4
.IX Item "unpack_sockaddr_in6 SOCKADDR_IN6"
Takes a sockaddr_in6 structure (as returned by \fIpack_sockaddr_in6()\fR) and
returns an array of four elements: the port number, an opaque string
representing the IPv6 address, the scope \s-1ID\s0, and the flow label. (You can
use \fIinet_ntop()\fR to convert the address to the usual string format). Will
croak if the structure does not have \s-1AF_INET6\s0 in the right place.
.IP "sockaddr_un \s-1PATHNAME\s0" 4
.IX Item "sockaddr_un PATHNAME"
.PD 0
.IP "sockaddr_un \s-1SOCKADDR_UN\s0" 4
.IX Item "sockaddr_un SOCKADDR_UN"
.PD
In a list context, unpacks its \s-1SOCKADDR_UN\s0 argument and returns an array
consisting of (\s-1PATHNAME\s0).  In a scalar context, packs its \s-1PATHNAME\s0
arguments as a \s-1SOCKADDR_UN\s0 and returns it.  If this is confusing, use
\&\fIpack_sockaddr_un()\fR and \fIunpack_sockaddr_un()\fR explicitly.
These are only supported if your system has <\fIsys/un.h\fR>.
.IP "pack_sockaddr_un \s-1PATH\s0" 4
.IX Item "pack_sockaddr_un PATH"
Takes one argument, a pathname. Returns the sockaddr_un structure with
that path packed in with \s-1AF_UNIX\s0 filled in. For unix domain sockets, this
structure is normally what you need for the arguments in \fIbind()\fR,
\&\fIconnect()\fR, and \fIsend()\fR, and is also returned by \fIgetpeername()\fR,
\&\fIgetsockname()\fR and \fIrecv()\fR.
.IP "unpack_sockaddr_un \s-1SOCKADDR_UN\s0" 4
.IX Item "unpack_sockaddr_un SOCKADDR_UN"
Takes a sockaddr_un structure (as returned by \fIpack_sockaddr_un()\fR)
and returns the pathname.  Will croak if the structure does not
have \s-1AF_UNIX\s0 in the right place.
.IP "inet_pton \s-1ADDRESS_FAMILY\s0, \s-1HOSTNAME\s0" 4
.IX Item "inet_pton ADDRESS_FAMILY, HOSTNAME"
Takes an address family, either \s-1AF_INET\s0 or \s-1AF_INET6\s0, and a string giving
the name of a host, and translates that to an opaque string
(if programming in C, struct in_addr or struct in6_addr depending on the 
address family passed in).  The host string may be a string hostname, such
as 'www.perl.org', or an \s-1IP\s0 address.  If using an \s-1IP\s0 address, the type of
\&\s-1IP\s0 address must be consistent with the address family passed into the function.
.Sp
This function is not exported by default.
.IP "inet_ntop \s-1ADDRESS_FAMILY\s0, \s-1IP_ADDRESS\s0" 4
.IX Item "inet_ntop ADDRESS_FAMILY, IP_ADDRESS"
Takes an address family, either \s-1AF_INET\s0 or \s-1AF_INET6\s0, and a string 
(an opaque string as returned by \fIinet_aton()\fR or \fIinet_pton()\fR) and
translates it to an IPv4 or IPv6 address string.
.Sp
This function is not exported by default.
.IP "getaddrinfo \s-1HOST\s0, \s-1SERVICE\s0, [ \s-1HINTS\s0 ]" 4
.IX Item "getaddrinfo HOST, SERVICE, [ HINTS ]"
Given at least one of a hostname and a service name, returns a list of address
structures to listen on or connect to. \s-1HOST\s0 and \s-1SERVICE\s0 should be plain
strings (or a numerical port number for \s-1SERVICE\s0). If present, \s-1HINTS\s0 should be
a reference to a \s-1HASH\s0, where the following keys are recognised:
.RS 4
.IP "flags => \s-1INT\s0" 8
.IX Item "flags => INT"
A bitfield containing \f(CW\*(C`AI_*\*(C'\fR constants
.IP "family => \s-1INT\s0" 8
.IX Item "family => INT"
Restrict to only generating addresses in this address family
.IP "socktype => \s-1INT\s0" 8
.IX Item "socktype => INT"
Restrict to only generating addresses of this socket type
.IP "protocol => \s-1INT\s0" 8
.IX Item "protocol => INT"
Restrict to only generating addresses for this protocol
.RE
.RS 4
.Sp
The return value will be a list; the first value being an error indication,
followed by a list of address structures (if no error occured).
.Sp
.Vb 1
\& my ( $err, @results ) = getaddrinfo( ... );
.Ve
.Sp
The error value will be a dualvar; comparable to the \f(CW\*(C`EI_*\*(C'\fR error constants,
or printable as a human-readable error message string. Each value in the
results list will be a \s-1HASH\s0 reference containing the following fields:
.IP "family => \s-1INT\s0" 8
.IX Item "family => INT"
The address family (e.g. \s-1AF_INET\s0)
.IP "socktype => \s-1INT\s0" 8
.IX Item "socktype => INT"
The socket type (e.g. \s-1SOCK_STREAM\s0)
.IP "protocol => \s-1INT\s0" 8
.IX Item "protocol => INT"
The protocol (e.g. \s-1IPPROTO_TCP\s0)
.IP "addr => \s-1STRING\s0" 8
.IX Item "addr => STRING"
The address in a packed string (such as would be returned by pack_sockaddr_in)
.IP "canonname => \s-1STRING\s0" 8
.IX Item "canonname => STRING"
The canonical name for the host if the \f(CW\*(C`AI_CANONNAME\*(C'\fR flag was provided, or
\&\f(CW\*(C`undef\*(C'\fR otherwise. This field will only be present on the first returned
address.
.RE
.RS 4
.RE
.IP "getnameinfo \s-1ADDR\s0, \s-1FLAGS\s0" 4
.IX Item "getnameinfo ADDR, FLAGS"
Given a packed socket address (such as from \f(CW\*(C`getsockname\*(C'\fR, \f(CW\*(C`getpeername\*(C'\fR, or
returned by \f(CW\*(C`getaddrinfo\*(C'\fR in a \f(CW\*(C`addr\*(C'\fR field), returns the hostname and
symbolic service name it represents. \s-1FLAGS\s0 may be a bitmask of \f(CW\*(C`NI_*\*(C'\fR
constants, or defaults to 0 if unspecified.
.Sp
The return value will be a list; the first value being an error condition,
followed by the hostname and service name.
.Sp
.Vb 1
\& my ( $err, $host, $service ) = getnameinfo( ... );
.Ve
.Sp
The error value will be a dualvar; comparable to the \f(CW\*(C`EI_*\*(C'\fR error constants,
or printable as a human-readable error message string. The host and service
names will be plain strings.