Initial commit of OpenSPARC T2 architecture model.

[OpenSPARC-T2-SAM] / sam-t2 / devtools / v8plus / man / man3 / Socket.3

.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.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.  | will give a
.\" real vertical bar.  \*(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-|\(bv\*(Tr
.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\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" 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 "2001-09-21" "perl v5.8.8" "Perl Programmers Reference Guide"
.SH "NAME"
Socket, sockaddr_in, sockaddr_un, inet_aton, inet_ntoa \- load the C socket.h defines and structure manipulators 
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Socket;
.Ve
.PP
.Vb 6
\&    $proto = getprotobyname('udp');
\&    socket(Socket_Handle, PF_INET, SOCK_DGRAM, $proto);
\&    $iaddr = gethostbyname('hishost.com');
\&    $port = getservbyname('time', 'udp');
\&    $sin = sockaddr_in($port, $iaddr);
\&    send(Socket_Handle, 0, 0, $sin);
.Ve
.PP
.Vb 7
\&    $proto = getprotobyname('tcp');
\&    socket(Socket_Handle, PF_INET, SOCK_STREAM, $proto);
\&    $port = getservbyname('smtp', 'tcp');
\&    $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);
.Ve
.PP
.Vb 3
\&    ($port, $iaddr) = sockaddr_in(getpeername(Socket_Handle));
\&    $peer_host = gethostbyaddr($iaddr, AF_INET);
\&    $peer_addr = inet_ntoa($iaddr);
.Ve
.PP
.Vb 5
\&    $proto = getprotobyname('tcp');
\&    socket(Socket_Handle, PF_UNIX, SOCK_STREAM, $proto);
\&    unlink('/var/run/usock');
\&    $sun = sockaddr_un('/var/run/usock');
\&    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.