'\" te
.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14)
.\"
.\" 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 3"
.TH Socket 3 "2012-11-03" "perl v5.12.5" "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 "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_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 consistant 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.


.\" Oracle has added the ARC stability level to this manual page
.SH ATTRIBUTES
See
.BR attributes (5)
for descriptions of the following attributes:
.sp
.TS
box;
cbp-1 | cbp-1
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE 
=
Availability	runtime/perl-512
=
Stability	Uncommitted
.TE 
.PP

.SH NOTES

.\" Oracle has added source availability information to this manual page
This software was built from source available at https://java.net/projects/solaris-userland.  The original community source was downloaded from  http://www.cpan.org/src/5.0/perl-5.12.5.tar.bz2

Further information about this software can be found on the open source community website at http://www.perl.org/.