diff options
Diffstat (limited to 'upstream/mageia-cauldron/man3pm/Socket.3pm')
| -rw-r--r-- | upstream/mageia-cauldron/man3pm/Socket.3pm | 674 |
1 files changed, 674 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man3pm/Socket.3pm b/upstream/mageia-cauldron/man3pm/Socket.3pm new file mode 100644 index 00000000..190da75d --- /dev/null +++ b/upstream/mageia-cauldron/man3pm/Socket.3pm @@ -0,0 +1,674 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" 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 +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'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 >0, 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. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "Socket 3pm" +.TH Socket 3pm 2023-11-28 "perl v5.38.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" \- networking constants and support functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +\&\f(CW\*(C`Socket\*(C'\fR a low-level module used by, among other things, the IO::Socket +family of modules. The following examples demonstrate some low-level uses but +a practical program would likely use the higher-level API provided by +\&\f(CW\*(C`IO::Socket\*(C'\fR or similar instead. +.PP +.Vb 1 +\& use Socket qw(PF_INET SOCK_STREAM pack_sockaddr_in inet_aton); +\& +\& socket(my $socket, PF_INET, SOCK_STREAM, 0) +\& or die "socket: $!"; +\& +\& my $port = getservbyname "echo", "tcp"; +\& connect($socket, pack_sockaddr_in($port, inet_aton("localhost"))) +\& or die "connect: $!"; +\& +\& print $socket "Hello, world!\en"; +\& print <$socket>; +.Ve +.PP +See also the "EXAMPLES" section. +.SH DESCRIPTION +.IX Header "DESCRIPTION" +This module provides a variety of constants, structure manipulators and other +functions related to socket-based networking. The values and functions +provided are useful when used in conjunction with Perl core functions such as +\&\fBsocket()\fR, \fBsetsockopt()\fR and \fBbind()\fR. It also provides several other support +functions, mostly for dealing with conversions of network addresses between +human-readable and native binary forms, and for hostname resolver operations. +.PP +Some constants and functions are exported by default by this module; but for +backward-compatibility any recently-added symbols are not exported by default +and must be requested explicitly. When an import list is provided to the +\&\f(CW\*(C`use Socket\*(C'\fR line, the default exports are not automatically imported. It is +therefore best practice to always to explicitly list all the symbols required. +.PP +Also, some common socket "newline" 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); +\& +\& $sock\->print("GET / HTTP/1.0$CRLF"); +.Ve +.PP +The entire \fBgetaddrinfo()\fR subsystem can be exported using the tag \f(CW\*(C`:addrinfo\*(C'\fR; +this exports the \fBgetaddrinfo()\fR and \fBgetnameinfo()\fR functions, and all the +\&\f(CW\*(C`AI_*\*(C'\fR, \f(CW\*(C`NI_*\*(C'\fR, \f(CW\*(C`NIx_*\*(C'\fR and \f(CW\*(C`EAI_*\*(C'\fR constants. +.SH CONSTANTS +.IX Header "CONSTANTS" +In each of the following groups, there may be many more constants provided +than just the ones given as examples in the section heading. If the heading +ends \f(CW\*(C`...\*(C'\fR then this means there are likely more; the exact constants +provided will depend on the OS and headers found at compile-time. +.SS "PF_INET, PF_INET6, PF_UNIX, ..." +.IX Subsection "PF_INET, PF_INET6, PF_UNIX, ..." +Protocol family constants to use as the first argument to \fBsocket()\fR or the +value of the \f(CW\*(C`SO_DOMAIN\*(C'\fR or \f(CW\*(C`SO_FAMILY\*(C'\fR socket option. +.SS "AF_INET, AF_INET6, AF_UNIX, ..." +.IX Subsection "AF_INET, AF_INET6, AF_UNIX, ..." +Address family constants used by the socket address structures, to pass to +such functions as \fBinet_pton()\fR or \fBgetaddrinfo()\fR, or are returned by such +functions as \fBsockaddr_family()\fR. +.SS "SOCK_STREAM, SOCK_DGRAM, SOCK_RAW, ..." +.IX Subsection "SOCK_STREAM, SOCK_DGRAM, SOCK_RAW, ..." +Socket type constants to use as the second argument to \fBsocket()\fR, or the value +of the \f(CW\*(C`SO_TYPE\*(C'\fR socket option. +.SS "SOCK_NONBLOCK. SOCK_CLOEXEC" +.IX Subsection "SOCK_NONBLOCK. SOCK_CLOEXEC" +Linux-specific shortcuts to specify the \f(CW\*(C`O_NONBLOCK\*(C'\fR and \f(CW\*(C`FD_CLOEXEC\*(C'\fR flags +during a \f(CWsocket(2)\fR call. +.PP +.Vb 1 +\& socket( my $sockh, PF_INET, SOCK_DGRAM|SOCK_NONBLOCK, 0 ) +.Ve +.SS SOL_SOCKET +.IX Subsection "SOL_SOCKET" +Socket option level constant for \fBsetsockopt()\fR and \fBgetsockopt()\fR. +.SS "SO_ACCEPTCONN, SO_BROADCAST, SO_ERROR, ..." +.IX Subsection "SO_ACCEPTCONN, SO_BROADCAST, SO_ERROR, ..." +Socket option name constants for \fBsetsockopt()\fR and \fBgetsockopt()\fR at the +\&\f(CW\*(C`SOL_SOCKET\*(C'\fR level. +.SS "IP_OPTIONS, IP_TOS, IP_TTL, ..." +.IX Subsection "IP_OPTIONS, IP_TOS, IP_TTL, ..." +Socket option name constants for IPv4 socket options at the \f(CW\*(C`IPPROTO_IP\*(C'\fR +level. +.SS "IP_PMTUDISC_WANT, IP_PMTUDISC_DONT, ..." +.IX Subsection "IP_PMTUDISC_WANT, IP_PMTUDISC_DONT, ..." +Socket option value constants for \f(CW\*(C`IP_MTU_DISCOVER\*(C'\fR socket option. +.SS "IPTOS_LOWDELAY, IPTOS_THROUGHPUT, IPTOS_RELIABILITY, ..." +.IX Subsection "IPTOS_LOWDELAY, IPTOS_THROUGHPUT, IPTOS_RELIABILITY, ..." +Socket option value constants for \f(CW\*(C`IP_TOS\*(C'\fR socket option. +.SS "MSG_BCAST, MSG_OOB, MSG_TRUNC, ..." +.IX Subsection "MSG_BCAST, MSG_OOB, MSG_TRUNC, ..." +Message flag constants for \fBsend()\fR and \fBrecv()\fR. +.SS "SHUT_RD, SHUT_RDWR, SHUT_WR" +.IX Subsection "SHUT_RD, SHUT_RDWR, SHUT_WR" +Direction constants for \fBshutdown()\fR. +.SS "INADDR_ANY, INADDR_BROADCAST, INADDR_LOOPBACK, INADDR_NONE" +.IX Subsection "INADDR_ANY, INADDR_BROADCAST, INADDR_LOOPBACK, INADDR_NONE" +Constants giving the special \f(CW\*(C`AF_INET\*(C'\fR addresses for wildcard, broadcast, +local loopback, and invalid addresses. +.PP +Normally equivalent to inet_aton('0.0.0.0'), inet_aton('255.255.255.255'), +inet_aton('localhost') and inet_aton('255.255.255.255') respectively. +.SS "IPPROTO_IP, IPPROTO_IPV6, IPPROTO_TCP, ..." +.IX Subsection "IPPROTO_IP, IPPROTO_IPV6, IPPROTO_TCP, ..." +IP protocol constants to use as the third argument to \fBsocket()\fR, the level +argument to \fBgetsockopt()\fR or \fBsetsockopt()\fR, or the value of the \f(CW\*(C`SO_PROTOCOL\*(C'\fR +socket option. +.SS "TCP_CORK, TCP_KEEPALIVE, TCP_NODELAY, ..." +.IX Subsection "TCP_CORK, TCP_KEEPALIVE, TCP_NODELAY, ..." +Socket option name constants for TCP socket options at the \f(CW\*(C`IPPROTO_TCP\*(C'\fR +level. +.SS "IN6ADDR_ANY, IN6ADDR_LOOPBACK" +.IX Subsection "IN6ADDR_ANY, IN6ADDR_LOOPBACK" +Constants giving the special \f(CW\*(C`AF_INET6\*(C'\fR addresses for wildcard and local +loopback. +.PP +Normally equivalent to inet_pton(AF_INET6, "::") and +inet_pton(AF_INET6, "::1") respectively. +.SS "IPV6_ADD_MEMBERSHIP, IPV6_MTU, IPV6_V6ONLY, ..." +.IX Subsection "IPV6_ADD_MEMBERSHIP, IPV6_MTU, IPV6_V6ONLY, ..." +Socket option name constants for IPv6 socket options at the \f(CW\*(C`IPPROTO_IPV6\*(C'\fR +level. +.SH "STRUCTURE MANIPULATORS" +.IX Header "STRUCTURE MANIPULATORS" +The following functions convert between lists of Perl values and packed binary +strings representing structures. +.ie n .SS "$family = sockaddr_family $sockaddr" +.el .SS "\f(CW$family\fP = sockaddr_family \f(CW$sockaddr\fP" +.IX Subsection "$family = sockaddr_family $sockaddr" +Takes a packed socket address (as returned by \fBpack_sockaddr_in()\fR, +\&\fBpack_sockaddr_un()\fR or the perl builtin functions \fBgetsockname()\fR and +\&\fBgetpeername()\fR). Returns the address family tag. This will be one of the +\&\f(CW\*(C`AF_*\*(C'\fR constants, such as \f(CW\*(C`AF_INET\*(C'\fR for a \f(CW\*(C`sockaddr_in\*(C'\fR addresses or +\&\f(CW\*(C`AF_UNIX\*(C'\fR for a \f(CW\*(C`sockaddr_un\*(C'\fR. It can be used to figure out what unpack to +use for a sockaddr of unknown type. +.ie n .SS "$sockaddr = pack_sockaddr_in $port, $ip_address" +.el .SS "\f(CW$sockaddr\fP = pack_sockaddr_in \f(CW$port\fP, \f(CW$ip_address\fP" +.IX Subsection "$sockaddr = pack_sockaddr_in $port, $ip_address" +Takes two arguments, a port number and an opaque string (as returned by +\&\fBinet_aton()\fR, or a v\-string). Returns the \f(CW\*(C`sockaddr_in\*(C'\fR structure with those +arguments packed in and \f(CW\*(C`AF_INET\*(C'\fR filled in. For Internet domain sockets, +this structure is normally what you need for the arguments in \fBbind()\fR, +\&\fBconnect()\fR, and \fBsend()\fR. +.PP +An undefined \f(CW$port\fR argument is taken as zero; an undefined \f(CW$ip_address\fR is +considered a fatal error. +.ie n .SS "($port, $ip_address) = unpack_sockaddr_in $sockaddr" +.el .SS "($port, \f(CW$ip_address\fP) = unpack_sockaddr_in \f(CW$sockaddr\fP" +.IX Subsection "($port, $ip_address) = unpack_sockaddr_in $sockaddr" +Takes a \f(CW\*(C`sockaddr_in\*(C'\fR structure (as returned by \fBpack_sockaddr_in()\fR, +\&\fBgetpeername()\fR or \fBrecv()\fR). Returns a list of two elements: the port and an +opaque string representing the IP address (you can use \fBinet_ntoa()\fR to convert +the address to the four-dotted numeric format). Will croak if the structure +does not represent an \f(CW\*(C`AF_INET\*(C'\fR address. +.PP +In scalar context will return just the IP address. +.ie n .SS "$sockaddr = sockaddr_in $port, $ip_address" +.el .SS "\f(CW$sockaddr\fP = sockaddr_in \f(CW$port\fP, \f(CW$ip_address\fP" +.IX Subsection "$sockaddr = sockaddr_in $port, $ip_address" +.ie n .SS "($port, $ip_address) = sockaddr_in $sockaddr" +.el .SS "($port, \f(CW$ip_address\fP) = sockaddr_in \f(CW$sockaddr\fP" +.IX Subsection "($port, $ip_address) = sockaddr_in $sockaddr" +A wrapper of \fBpack_sockaddr_in()\fR or \fBunpack_sockaddr_in()\fR. In list context, +unpacks its argument and returns a list consisting of the port and IP address. +In scalar context, packs its port and IP address arguments as a \f(CW\*(C`sockaddr_in\*(C'\fR +and returns it. +.PP +Provided largely for legacy compatibility; it is better to use +\&\fBpack_sockaddr_in()\fR or \fBunpack_sockaddr_in()\fR explicitly. +.ie n .SS "$sockaddr = pack_sockaddr_in6 $port, $ip6_address, [$scope_id, [$flowinfo]]" +.el .SS "\f(CW$sockaddr\fP = pack_sockaddr_in6 \f(CW$port\fP, \f(CW$ip6_address\fP, [$scope_id, [$flowinfo]]" +.IX Subsection "$sockaddr = pack_sockaddr_in6 $port, $ip6_address, [$scope_id, [$flowinfo]]" +Takes two to four arguments, a port number, an opaque string (as returned by +\&\fBinet_pton()\fR), optionally a scope ID number, and optionally a flow label +number. Returns the \f(CW\*(C`sockaddr_in6\*(C'\fR structure with those arguments packed in +and \f(CW\*(C`AF_INET6\*(C'\fR filled in. IPv6 equivalent of \fBpack_sockaddr_in()\fR. +.PP +An undefined \f(CW$port\fR argument is taken as zero; an undefined \f(CW$ip6_address\fR is +considered a fatal error. +.ie n .SS "($port, $ip6_address, $scope_id, $flowinfo) = unpack_sockaddr_in6 $sockaddr" +.el .SS "($port, \f(CW$ip6_address\fP, \f(CW$scope_id\fP, \f(CW$flowinfo\fP) = unpack_sockaddr_in6 \f(CW$sockaddr\fP" +.IX Subsection "($port, $ip6_address, $scope_id, $flowinfo) = unpack_sockaddr_in6 $sockaddr" +Takes a \f(CW\*(C`sockaddr_in6\*(C'\fR structure. Returns a list of four elements: the port +number, an opaque string representing the IPv6 address, the scope ID, and the +flow label. (You can use \fBinet_ntop()\fR to convert the address to the usual +string format). Will croak if the structure does not represent an \f(CW\*(C`AF_INET6\*(C'\fR +address. +.PP +In scalar context will return just the IP address. +.ie n .SS "$sockaddr = sockaddr_in6 $port, $ip6_address, [$scope_id, [$flowinfo]]" +.el .SS "\f(CW$sockaddr\fP = sockaddr_in6 \f(CW$port\fP, \f(CW$ip6_address\fP, [$scope_id, [$flowinfo]]" +.IX Subsection "$sockaddr = sockaddr_in6 $port, $ip6_address, [$scope_id, [$flowinfo]]" +.ie n .SS "($port, $ip6_address, $scope_id, $flowinfo) = sockaddr_in6 $sockaddr" +.el .SS "($port, \f(CW$ip6_address\fP, \f(CW$scope_id\fP, \f(CW$flowinfo\fP) = sockaddr_in6 \f(CW$sockaddr\fP" +.IX Subsection "($port, $ip6_address, $scope_id, $flowinfo) = sockaddr_in6 $sockaddr" +A wrapper of \fBpack_sockaddr_in6()\fR or \fBunpack_sockaddr_in6()\fR. In list context, +unpacks its argument according to \fBunpack_sockaddr_in6()\fR. In scalar context, +packs its arguments according to \fBpack_sockaddr_in6()\fR. +.PP +Provided largely for legacy compatibility; it is better to use +\&\fBpack_sockaddr_in6()\fR or \fBunpack_sockaddr_in6()\fR explicitly. +.ie n .SS "$sockaddr = pack_sockaddr_un $path" +.el .SS "\f(CW$sockaddr\fP = pack_sockaddr_un \f(CW$path\fP" +.IX Subsection "$sockaddr = pack_sockaddr_un $path" +Takes one argument, a pathname. Returns the \f(CW\*(C`sockaddr_un\*(C'\fR structure with that +path packed in with \f(CW\*(C`AF_UNIX\*(C'\fR filled in. For \f(CW\*(C`PF_UNIX\*(C'\fR sockets, this +structure is normally what you need for the arguments in \fBbind()\fR, \fBconnect()\fR, +and \fBsend()\fR. +.ie n .SS "($path) = unpack_sockaddr_un $sockaddr" +.el .SS "($path) = unpack_sockaddr_un \f(CW$sockaddr\fP" +.IX Subsection "($path) = unpack_sockaddr_un $sockaddr" +Takes a \f(CW\*(C`sockaddr_un\*(C'\fR structure (as returned by \fBpack_sockaddr_un()\fR, +\&\fBgetpeername()\fR or \fBrecv()\fR). Returns a list of one element: the pathname. Will +croak if the structure does not represent an \f(CW\*(C`AF_UNIX\*(C'\fR address. +.ie n .SS "$sockaddr = sockaddr_un $path" +.el .SS "\f(CW$sockaddr\fP = sockaddr_un \f(CW$path\fP" +.IX Subsection "$sockaddr = sockaddr_un $path" +.ie n .SS "($path) = sockaddr_un $sockaddr" +.el .SS "($path) = sockaddr_un \f(CW$sockaddr\fP" +.IX Subsection "($path) = sockaddr_un $sockaddr" +A wrapper of \fBpack_sockaddr_un()\fR or \fBunpack_sockaddr_un()\fR. In a list context, +unpacks its argument and returns a list consisting of the pathname. In a +scalar context, packs its pathname as a \f(CW\*(C`sockaddr_un\*(C'\fR and returns it. +.PP +Provided largely for legacy compatibility; it is better to use +\&\fBpack_sockaddr_un()\fR or \fBunpack_sockaddr_un()\fR explicitly. +.PP +These are only supported if your system has <\fIsys/un.h\fR>. +.ie n .SS "$ip_mreq = pack_ip_mreq $multiaddr, $interface" +.el .SS "\f(CW$ip_mreq\fP = pack_ip_mreq \f(CW$multiaddr\fP, \f(CW$interface\fP" +.IX Subsection "$ip_mreq = pack_ip_mreq $multiaddr, $interface" +Takes an IPv4 multicast address and optionally an interface address (or +\&\f(CW\*(C`INADDR_ANY\*(C'\fR). Returns the \f(CW\*(C`ip_mreq\*(C'\fR structure with those arguments packed +in. Suitable for use with the \f(CW\*(C`IP_ADD_MEMBERSHIP\*(C'\fR and \f(CW\*(C`IP_DROP_MEMBERSHIP\*(C'\fR +sockopts. +.ie n .SS "($multiaddr, $interface) = unpack_ip_mreq $ip_mreq" +.el .SS "($multiaddr, \f(CW$interface\fP) = unpack_ip_mreq \f(CW$ip_mreq\fP" +.IX Subsection "($multiaddr, $interface) = unpack_ip_mreq $ip_mreq" +Takes an \f(CW\*(C`ip_mreq\*(C'\fR structure. Returns a list of two elements; the IPv4 +multicast address and interface address. +.ie n .SS "$ip_mreq_source = pack_ip_mreq_source $multiaddr, $source, $interface" +.el .SS "\f(CW$ip_mreq_source\fP = pack_ip_mreq_source \f(CW$multiaddr\fP, \f(CW$source\fP, \f(CW$interface\fP" +.IX Subsection "$ip_mreq_source = pack_ip_mreq_source $multiaddr, $source, $interface" +Takes an IPv4 multicast address, source address, and optionally an interface +address (or \f(CW\*(C`INADDR_ANY\*(C'\fR). Returns the \f(CW\*(C`ip_mreq_source\*(C'\fR structure with those +arguments packed in. Suitable for use with the \f(CW\*(C`IP_ADD_SOURCE_MEMBERSHIP\*(C'\fR +and \f(CW\*(C`IP_DROP_SOURCE_MEMBERSHIP\*(C'\fR sockopts. +.ie n .SS "($multiaddr, $source, $interface) = unpack_ip_mreq_source $ip_mreq" +.el .SS "($multiaddr, \f(CW$source\fP, \f(CW$interface\fP) = unpack_ip_mreq_source \f(CW$ip_mreq\fP" +.IX Subsection "($multiaddr, $source, $interface) = unpack_ip_mreq_source $ip_mreq" +Takes an \f(CW\*(C`ip_mreq_source\*(C'\fR structure. Returns a list of three elements; the +IPv4 multicast address, source address and interface address. +.ie n .SS "$ipv6_mreq = pack_ipv6_mreq $multiaddr6, $ifindex" +.el .SS "\f(CW$ipv6_mreq\fP = pack_ipv6_mreq \f(CW$multiaddr6\fP, \f(CW$ifindex\fP" +.IX Subsection "$ipv6_mreq = pack_ipv6_mreq $multiaddr6, $ifindex" +Takes an IPv6 multicast address and an interface number. Returns the +\&\f(CW\*(C`ipv6_mreq\*(C'\fR structure with those arguments packed in. Suitable for use with +the \f(CW\*(C`IPV6_ADD_MEMBERSHIP\*(C'\fR and \f(CW\*(C`IPV6_DROP_MEMBERSHIP\*(C'\fR sockopts. +.ie n .SS "($multiaddr6, $ifindex) = unpack_ipv6_mreq $ipv6_mreq" +.el .SS "($multiaddr6, \f(CW$ifindex\fP) = unpack_ipv6_mreq \f(CW$ipv6_mreq\fP" +.IX Subsection "($multiaddr6, $ifindex) = unpack_ipv6_mreq $ipv6_mreq" +Takes an \f(CW\*(C`ipv6_mreq\*(C'\fR structure. Returns a list of two elements; the IPv6 +address and an interface number. +.SH FUNCTIONS +.IX Header "FUNCTIONS" +.ie n .SS "$ip_address = inet_aton $string" +.el .SS "\f(CW$ip_address\fP = inet_aton \f(CW$string\fP" +.IX Subsection "$ip_address = inet_aton $string" +Takes a string giving the name of a host, or a textual representation of an IP +address and translates that to an packed binary address structure suitable to +pass to \fBpack_sockaddr_in()\fR. If passed a hostname that cannot be resolved, +returns \f(CW\*(C`undef\*(C'\fR. For multi-homed hosts (hosts with more than one address), +the first address found is returned. +.PP +For portability do not assume that the result of \fBinet_aton()\fR is 32 bits wide, +in other words, that it would contain only the IPv4 address in network order. +.PP +This IPv4\-only function is provided largely for legacy reasons. Newly-written +code should use \fBgetaddrinfo()\fR or \fBinet_pton()\fR instead for IPv6 support. +.ie n .SS "$string = inet_ntoa $ip_address" +.el .SS "\f(CW$string\fP = inet_ntoa \f(CW$ip_address\fP" +.IX Subsection "$string = inet_ntoa $ip_address" +Takes a packed binary address structure such as returned by +\&\fBunpack_sockaddr_in()\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 +\&\f(CW\*(C`d.d.d.d\*(C'\fR where the \f(CW\*(C`d\*(C'\fRs are numbers less than 256 (the normal +human-readable four dotted number notation for Internet addresses). +.PP +This IPv4\-only function is provided largely for legacy reasons. Newly-written +code should use \fBgetnameinfo()\fR or \fBinet_ntop()\fR instead for IPv6 support. +.ie n .SS "$address = inet_pton $family, $string" +.el .SS "\f(CW$address\fP = inet_pton \f(CW$family\fP, \f(CW$string\fP" +.IX Subsection "$address = inet_pton $family, $string" +Takes an address family (such as \f(CW\*(C`AF_INET\*(C'\fR or \f(CW\*(C`AF_INET6\*(C'\fR) and a string +containing a textual representation of an address in that family and +translates that to an packed binary address structure. +.PP +See also \fBgetaddrinfo()\fR for a more powerful and flexible function to look up +socket addresses given hostnames or textual addresses. +.ie n .SS "$string = inet_ntop $family, $address" +.el .SS "\f(CW$string\fP = inet_ntop \f(CW$family\fP, \f(CW$address\fP" +.IX Subsection "$string = inet_ntop $family, $address" +Takes an address family and a packed binary address structure and translates +it into a human-readable textual representation of the address; typically in +\&\f(CW\*(C`d.d.d.d\*(C'\fR form for \f(CW\*(C`AF_INET\*(C'\fR or \f(CW\*(C`hhhh:hhhh::hhhh\*(C'\fR form for \f(CW\*(C`AF_INET6\*(C'\fR. +.PP +See also \fBgetnameinfo()\fR for a more powerful and flexible function to turn +socket addresses into human-readable textual representations. +.ie n .SS "($err, @result) = getaddrinfo $host, $service, [$hints]" +.el .SS "($err, \f(CW@result\fP) = getaddrinfo \f(CW$host\fP, \f(CW$service\fP, [$hints]" +.IX Subsection "($err, @result) = getaddrinfo $host, $service, [$hints]" +Given both a hostname and service name, this function attempts to resolve the +host name into a list of network addresses, and the service name into a +protocol and port number, and then returns a list of address structures +suitable to \fBconnect()\fR to it. +.PP +Given just a host name, this function attempts to resolve it to a list of +network addresses, and then returns a list of address structures giving these +addresses. +.PP +Given just a service name, this function attempts to resolve it to a protocol +and port number, and then returns a list of address structures that represent +it suitable to \fBbind()\fR to. This use should be combined with the \f(CW\*(C`AI_PASSIVE\*(C'\fR +flag; see below. +.PP +Given neither name, it generates an error. +.PP +If present, \f(CW$hints\fR should be a reference to a hash, where the following keys +are recognised: +.IP "flags => INT" 4 +.IX Item "flags => INT" +A bitfield containing \f(CW\*(C`AI_*\*(C'\fR constants; see below. +.IP "family => INT" 4 +.IX Item "family => INT" +Restrict to only generating addresses in this address family +.IP "socktype => INT" 4 +.IX Item "socktype => INT" +Restrict to only generating addresses of this socket type +.IP "protocol => INT" 4 +.IX Item "protocol => INT" +Restrict to only generating addresses for this protocol +.PP +The return value will be a list; the first value being an error indication, +followed by a list of address structures (if no error occurred). +.PP +The error value will be a dualvar; comparable to the \f(CW\*(C`EAI_*\*(C'\fR error constants, +or printable as a human-readable error message string. If no error occurred it +will be zero numerically and an empty string. +.PP +Each value in the results list will be a hash reference containing the following +fields: +.IP "family => INT" 4 +.IX Item "family => INT" +The address family (e.g. \f(CW\*(C`AF_INET\*(C'\fR) +.IP "socktype => INT" 4 +.IX Item "socktype => INT" +The socket type (e.g. \f(CW\*(C`SOCK_STREAM\*(C'\fR) +.IP "protocol => INT" 4 +.IX Item "protocol => INT" +The protocol (e.g. \f(CW\*(C`IPPROTO_TCP\*(C'\fR) +.IP "addr => STRING" 4 +.IX Item "addr => STRING" +The address in a packed string (such as would be returned by +\&\fBpack_sockaddr_in()\fR) +.IP "canonname => STRING" 4 +.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. +.PP +The following flag constants are recognised in the \f(CW$hints\fR hash. Other flag +constants may exist as provided by the OS. +.IP AI_PASSIVE 4 +.IX Item "AI_PASSIVE" +Indicates that this resolution is for a local \fBbind()\fR for a passive (i.e. +listening) socket, rather than an active (i.e. connecting) socket. +.IP AI_CANONNAME 4 +.IX Item "AI_CANONNAME" +Indicates that the caller wishes the canonical hostname (\f(CW\*(C`canonname\*(C'\fR) field +of the result to be filled in. +.IP AI_NUMERICHOST 4 +.IX Item "AI_NUMERICHOST" +Indicates that the caller will pass a numeric address, rather than a hostname, +and that \fBgetaddrinfo()\fR must not perform a resolve operation on this name. This +flag will prevent a possibly-slow network lookup operation, and instead return +an error if a hostname is passed. +.ie n .SS "($err, $hostname, $servicename) = getnameinfo $sockaddr, [$flags, [$xflags]]" +.el .SS "($err, \f(CW$hostname\fP, \f(CW$servicename\fP) = getnameinfo \f(CW$sockaddr\fP, [$flags, [$xflags]]" +.IX Subsection "($err, $hostname, $servicename) = getnameinfo $sockaddr, [$flags, [$xflags]]" +Given a packed socket address (such as from \fBgetsockname()\fR, \fBgetpeername()\fR, or +returned by \fBgetaddrinfo()\fR in a \f(CW\*(C`addr\*(C'\fR field), returns the hostname and +symbolic service name it represents. \f(CW$flags\fR may be a bitmask of \f(CW\*(C`NI_*\*(C'\fR +constants, or defaults to 0 if unspecified. +.PP +The return value will be a list; the first value being an error condition, +followed by the hostname and service name. +.PP +The error value will be a dualvar; comparable to the \f(CW\*(C`EAI_*\*(C'\fR error constants, +or printable as a human-readable error message string. The host and service +names will be plain strings. +.PP +The following flag constants are recognised as \f(CW$flags\fR. Other flag constants may +exist as provided by the OS. +.IP NI_NUMERICHOST 4 +.IX Item "NI_NUMERICHOST" +Requests that a human-readable string representation of the numeric address be +returned directly, rather than performing a name resolve operation that may +convert it into a hostname. This will also avoid potentially-blocking network +IO. +.IP NI_NUMERICSERV 4 +.IX Item "NI_NUMERICSERV" +Requests that the port number be returned directly as a number representation +rather than performing a name resolve operation that may convert it into a +service name. +.IP NI_NAMEREQD 4 +.IX Item "NI_NAMEREQD" +If a name resolve operation fails to provide a name, then this flag will cause +\&\fBgetnameinfo()\fR to indicate an error, rather than returning the numeric +representation as a human-readable string. +.IP NI_DGRAM 4 +.IX Item "NI_DGRAM" +Indicates that the socket address relates to a \f(CW\*(C`SOCK_DGRAM\*(C'\fR socket, for the +services whose name differs between TCP and UDP protocols. +.PP +The following constants may be supplied as \f(CW$xflags\fR. +.IP NIx_NOHOST 4 +.IX Item "NIx_NOHOST" +Indicates that the caller is not interested in the hostname of the result, so +it does not have to be converted. \f(CW\*(C`undef\*(C'\fR will be returned as the hostname. +.IP NIx_NOSERV 4 +.IX Item "NIx_NOSERV" +Indicates that the caller is not interested in the service name of the result, +so it does not have to be converted. \f(CW\*(C`undef\*(C'\fR will be returned as the service +name. +.SH "\fBgetaddrinfo()\fP / \fBgetnameinfo()\fP ERROR CONSTANTS" +.IX Header "getaddrinfo() / getnameinfo() ERROR CONSTANTS" +The following constants may be returned by \fBgetaddrinfo()\fR or \fBgetnameinfo()\fR. +Others may be provided by the OS. +.IP EAI_AGAIN 4 +.IX Item "EAI_AGAIN" +A temporary failure occurred during name resolution. The operation may be +successful if it is retried later. +.IP EAI_BADFLAGS 4 +.IX Item "EAI_BADFLAGS" +The value of the \f(CW\*(C`flags\*(C'\fR hint to \fBgetaddrinfo()\fR, or the \f(CW$flags\fR parameter to +\&\fBgetnameinfo()\fR contains unrecognised flags. +.IP EAI_FAMILY 4 +.IX Item "EAI_FAMILY" +The \f(CW\*(C`family\*(C'\fR hint to \fBgetaddrinfo()\fR, or the family of the socket address +passed to \fBgetnameinfo()\fR is not supported. +.IP EAI_NODATA 4 +.IX Item "EAI_NODATA" +The host name supplied to \fBgetaddrinfo()\fR did not provide any usable address +data. +.IP EAI_NONAME 4 +.IX Item "EAI_NONAME" +The host name supplied to \fBgetaddrinfo()\fR does not exist, or the address +supplied to \fBgetnameinfo()\fR is not associated with a host name and the +\&\f(CW\*(C`NI_NAMEREQD\*(C'\fR flag was supplied. +.IP EAI_SERVICE 4 +.IX Item "EAI_SERVICE" +The service name supplied to \fBgetaddrinfo()\fR is not available for the socket +type given in the \f(CW$hints\fR. +.SH EXAMPLES +.IX Header "EXAMPLES" +.SS "Lookup for \fBconnect()\fP" +.IX Subsection "Lookup for connect()" +The \fBgetaddrinfo()\fR function converts a hostname and a service name into a list +of structures, each containing a potential way to \fBconnect()\fR to the named +service on the named host. +.PP +.Vb 2 +\& use IO::Socket; +\& use Socket qw(SOCK_STREAM getaddrinfo); +\& +\& my %hints = (socktype => SOCK_STREAM); +\& my ($err, @res) = getaddrinfo("localhost", "echo", \e%hints); +\& die "Cannot getaddrinfo \- $err" if $err; +\& +\& my $sock; +\& +\& foreach my $ai (@res) { +\& my $candidate = IO::Socket\->new(); +\& +\& $candidate\->socket($ai\->{family}, $ai\->{socktype}, $ai\->{protocol}) +\& or next; +\& +\& $candidate\->connect($ai\->{addr}) +\& or next; +\& +\& $sock = $candidate; +\& last; +\& } +\& +\& die "Cannot connect to localhost:echo" unless $sock; +\& +\& $sock\->print("Hello, world!\en"); +\& print <$sock>; +.Ve +.PP +Because a list of potential candidates is returned, the \f(CW\*(C`while\*(C'\fR loop tries +each in turn until it finds one that succeeds both the \fBsocket()\fR and \fBconnect()\fR +calls. +.PP +This function performs the work of the legacy functions \fBgethostbyname()\fR, +\&\fBgetservbyname()\fR, \fBinet_aton()\fR and \fBpack_sockaddr_in()\fR. +.PP +In practice this logic is better performed by IO::Socket::IP. +.SS "Making a human-readable string out of an address" +.IX Subsection "Making a human-readable string out of an address" +The \fBgetnameinfo()\fR function converts a socket address, such as returned by +\&\fBgetsockname()\fR or \fBgetpeername()\fR, into a pair of human-readable strings +representing the address and service name. +.PP +.Vb 2 +\& use IO::Socket::IP; +\& use Socket qw(getnameinfo); +\& +\& my $server = IO::Socket::IP\->new(LocalPort => 12345, Listen => 1) or +\& die "Cannot listen \- $@"; +\& +\& my $socket = $server\->accept or die "accept: $!"; +\& +\& my ($err, $hostname, $servicename) = getnameinfo($socket\->peername); +\& die "Cannot getnameinfo \- $err" if $err; +\& +\& print "The peer is connected from $hostname\en"; +.Ve +.PP +Since in this example only the hostname was used, the redundant conversion of +the port number into a service name may be omitted by passing the +\&\f(CW\*(C`NIx_NOSERV\*(C'\fR flag. +.PP +.Vb 1 +\& use Socket qw(getnameinfo NIx_NOSERV); +\& +\& my ($err, $hostname) = getnameinfo($socket\->peername, 0, NIx_NOSERV); +.Ve +.PP +This function performs the work of the legacy functions \fBunpack_sockaddr_in()\fR, +\&\fBinet_ntoa()\fR, \fBgethostbyaddr()\fR and \fBgetservbyport()\fR. +.PP +In practice this logic is better performed by IO::Socket::IP. +.SS "Resolving hostnames into IP addresses" +.IX Subsection "Resolving hostnames into IP addresses" +To turn a hostname into a human-readable plain IP address use \fBgetaddrinfo()\fR +to turn the hostname into a list of socket structures, then \fBgetnameinfo()\fR on +each one to make it a readable IP address again. +.PP +.Vb 1 +\& use Socket qw(:addrinfo SOCK_RAW); +\& +\& my ($err, @res) = getaddrinfo($hostname, "", {socktype => SOCK_RAW}); +\& die "Cannot getaddrinfo \- $err" if $err; +\& +\& while( my $ai = shift @res ) { +\& my ($err, $ipaddr) = getnameinfo($ai\->{addr}, NI_NUMERICHOST, NIx_NOSERV); +\& die "Cannot getnameinfo \- $err" if $err; +\& +\& print "$ipaddr\en"; +\& } +.Ve +.PP +The \f(CW\*(C`socktype\*(C'\fR hint to \fBgetaddrinfo()\fR filters the results to only include one +socket type and protocol. Without this most OSes return three combinations, +for \f(CW\*(C`SOCK_STREAM\*(C'\fR, \f(CW\*(C`SOCK_DGRAM\*(C'\fR and \f(CW\*(C`SOCK_RAW\*(C'\fR, resulting in triplicate +output of addresses. The \f(CW\*(C`NI_NUMERICHOST\*(C'\fR flag to \fBgetnameinfo()\fR causes it to +return a string-formatted plain IP address, rather than reverse resolving it +back into a hostname. +.PP +This combination performs the work of the legacy functions \fBgethostbyname()\fR +and \fBinet_ntoa()\fR. +.SS "Accessing socket options" +.IX Subsection "Accessing socket options" +The many \f(CW\*(C`SO_*\*(C'\fR and other constants provide the socket option names for +\&\fBgetsockopt()\fR and \fBsetsockopt()\fR. +.PP +.Vb 2 +\& use IO::Socket::INET; +\& use Socket qw(SOL_SOCKET SO_RCVBUF IPPROTO_IP IP_TTL); +\& +\& my $socket = IO::Socket::INET\->new(LocalPort => 0, Proto => \*(Aqudp\*(Aq) +\& or die "Cannot create socket: $@"; +\& +\& $socket\->setsockopt(SOL_SOCKET, SO_RCVBUF, 64*1024) or +\& die "setsockopt: $!"; +\& +\& print "Receive buffer is ", $socket\->getsockopt(SOL_SOCKET, SO_RCVBUF), +\& " bytes\en"; +\& +\& print "IP TTL is ", $socket\->getsockopt(IPPROTO_IP, IP_TTL), "\en"; +.Ve +.PP +As a convenience, IO::Socket's \fBsetsockopt()\fR method will convert a number +into a packed byte buffer, and \fBgetsockopt()\fR will unpack a byte buffer of the +correct size back into a number. +.SH AUTHOR +.IX Header "AUTHOR" +This module was originally maintained in Perl core by the Perl 5 Porters. +.PP +It was extracted to dual-life on CPAN at version 1.95 by +Paul Evans <leonerd@leonerd.org.uk> |