| |
man : AnyEvent::Socket
AnyEvent::SockeUser)Contributed Perl DocumentAnyEvent::Socket(3p)
NAME
AnyEvent::Socket - useful IPv4 and IPv6 stuff.
SYNOPSIS
use AnyEvent::Socket;
tcp_connect "gameserver.deliantra.net", 13327, sub {
my ($fh) = @_
or die "gameserver.deliantra.net connect failed: $!";
# enjoy your filehandle
};
# a simple tcp server
tcp_server undef, 8888, sub {
my ($fh, $host, $port) = @_;
syswrite $fh, "The internet is full, $host:$port. Go away!\015\012";
};
DESCRIPTION
This module implements various utility functions for handling internet
protocol addresses and sockets, in an as transparent and simple way as
possible.
All functions documented without "AnyEvent::Socket::" prefix are
exported by default.
$ipn = parse_ipv4 $dotted_quad
Tries to parse the given dotted quad IPv4 address and return it in
octet form (or undef when it isn't in a parsable format). Supports
all forms specified by POSIX (e.g. 10.0.0.1, 10.1, "10.0x020304",
0x12345678 or 0377.0377.0377.0377).
$ipn = parse_ipv6 $textual_ipv6_address
Tries to parse the given IPv6 address and return it in octet form
(or undef when it isn't in a parsable format).
Should support all forms specified by RFC 2373 (and additionally
all IPv4 forms supported by parse_ipv4). Note that scope-id's are
not supported (and will not parse).
This function works similarly to "inet_pton AF_INET6, ...".
$ipn = parse_address $ip
Combines "parse_ipv4" and "parse_ipv6" in one function. The address
here refers to the host address (not socket address) in network
form (binary).
If the $text is "unix/", then this function returns a special token
recognised by the other functions in this module to mean "UNIX
domain socket".
If the $text to parse is a mapped IPv4 in IPv6 address
perl v5.12.2 2009-09-29 1
AnyEvent::SockeUser)Contributed Perl DocumentAnyEvent::Socket(3p)
(:ffff::<ipv4>), then it will be treated as an IPv4 address. If you
don't want that, you have to call "parse_ipv4" and/or "parse_ipv6"
manually.
$ipn = AnyEvent::Socket::aton $ip
Same as "parse_address", but not exported (think
"Socket::inet_aton" but without name resolution).
($name, $aliases, $proto) = getprotobyname $name
Works like the builtin function of the same name, except it tries
hard to work even on broken platforms (well, that's windows), where
getprotobyname is traditionally very unreliable.
($host, $service) = parse_hostport $string[, $default_service]
Splitting a string of the form "hostname:port" is a common problem.
Unfortunately, just splitting on the colon makes it hard to specify
IPv6 addresses and doesn't support the less common but well
standardised "[ip literal]" syntax.
This function tries to do this job in a better way, it supports the
following formats, where "port" can be a numerical port number of a
service name, or a "name=port" string, and the " port" and ":port"
parts are optional. Also, everywhere where an IP address is
supported a hostname or unix domain socket address is also
supported (see "parse_unix").
hostname:port e.g. "www.linux.org", "www.x.de:443", "www.x.de:https=443"
ipv4:port e.g. "198.182.196.56", "127.1:22"
ipv6 e.g. "::1", "affe::1"
[ipv4or6]:port e.g. "[::1]", "[10.0.1]:80"
[ipv4or6] port e.g. "[127.0.0.1]", "[www.x.org] 17"
ipv4or6 port e.g. "::1 443", "10.0.0.1 smtp"
It also supports defaulting the service name in a simple way by
using $default_service if no service was detected. If neither a
service was detected nor a default was specified, then this
function returns the empty list. The same happens when a parse
error was detected, such as a hostname with a colon in it (the
function is rather conservative, though).
Example:
print join ",", parse_hostport "localhost:443";
# => "localhost,443"
print join ",", parse_hostport "localhost", "https";
# => "localhost,https"
print join ",", parse_hostport "[::1]";
# => "," (empty list)
$string = format_hostport $host, $port
Takes a host (in textual form) and a port and formats in
unambigiously in a way that "parse_hostport" can parse it again.
perl v5.12.2 2009-09-29 2
AnyEvent::SockeUser)Contributed Perl DocumentAnyEvent::Socket(3p)
$port can be "undef".
$sa_family = address_family $ipn
Returns the address family/protocol-family (AF_xxx/PF_xxx, in one
value :) of the given host address in network format.
$text = format_ipv4 $ipn
Expects a four octet string representing a binary IPv4 address and
returns its textual format. Rarely used, see "format_address" for a
nicer interface.
$text = format_ipv6 $ipn
Expects a sixteen octet string representing a binary IPv6 address
and returns its textual format. Rarely used, see "format_address"
for a nicer interface.
$text = format_address $ipn
Covnvert a host address in network format (e.g. 4 octets for IPv4
or 16 octets for IPv6) and convert it into textual form.
Returns "unix/" for UNIX domain sockets.
This function works similarly to "inet_ntop AF_INET || AF_INET6,
...", except it automatically detects the address type.
Returns "undef" if it cannot detect the type.
If the $ipn is a mapped IPv4 in IPv6 address (:ffff::<ipv4>), then
just the contained IPv4 address will be returned. If you do not
want that, you have to call "format_ipv6" manually.
$text = AnyEvent::Socket::ntoa $ipn
Same as format_address, but not exported (think "inet_ntoa").
inet_aton $name_or_address, $cb->(@addresses)
Works similarly to its Socket counterpart, except that it uses a
callback. Also, if a host has only an IPv6 address, this might be
passed to the callback instead (use the length to detect this - 4
for IPv4, 16 for IPv6).
Unlike the Socket function of the same name, you can get multiple
IPv4 and IPv6 addresses as result (and maybe even other adrdess
types).
$sa = AnyEvent::Socket::pack_sockaddr $service, $host
Pack the given port/host combination into a binary sockaddr
structure. Handles both IPv4 and IPv6 host addresses, as well as
UNIX domain sockets ($host == "unix/" and $service == absolute
pathname).
($service, $host) = AnyEvent::Socket::unpack_sockaddr $sa
Unpack the given binary sockaddr structure (as used by bind,
getpeername etc.) into a "$service, $host" combination.
perl v5.12.2 2009-09-29 3
AnyEvent::SockeUser)Contributed Perl DocumentAnyEvent::Socket(3p)
For IPv4 and IPv6, $service is the port number and $host the host
address in network format (binary).
For UNIX domain sockets, $service is the absolute pathname and
$host is a special token that is understood by the other functions
in this module ("format_address" converts it to "unix/").
resolve_sockaddr $node, $service, $proto, $family, $type,
$cb->([$family, $type, $proto, $sockaddr], ...)
Tries to resolve the given nodename and service name into protocol
families and sockaddr structures usable to connect to this node and
service in a protocol-independent way. It works remotely similar to
the getaddrinfo posix function.
For internet addresses, $node is either an IPv4 or IPv6 address or
an internet hostname, and $service is either a service name (port
name from /etc/services) or a numerical port number. If both $node
and $service are names, then SRV records will be consulted to find
the real service, otherwise they will be used as-is. If you know
that the service name is not in your services database, then you
can specify the service in the format "name=port" (e.g. "http=80").
For UNIX domain sockets, $node must be the string "unix/" and
$service must be the absolute pathname of the socket. In this case,
$proto will be ignored.
$proto must be a protocol name, currently "tcp", "udp" or "sctp".
The default is currently "tcp", but in the future, this function
might try to use other protocols such as "sctp", depending on the
socket type and any SRV records it might find.
$family must be either 0 (meaning any protocol is OK), 4 (use only
IPv4) or 6 (use only IPv6). The default is influenced by
$ENV{PERL_ANYEVENT_PROTOCOLS}.
$type must be "SOCK_STREAM", "SOCK_DGRAM" or "SOCK_SEQPACKET" (or
"undef" in which case it gets automatically chosen to be
"SOCK_STREAM" unless $proto is "udp").
The callback will receive zero or more array references that
contain "$family, $type, $proto" for use in "socket" and a binary
$sockaddr for use in "connect" (or "bind").
The application should try these in the order given.
Example:
resolve_sockaddr "google.com", "http", 0, undef, undef, sub { ... };
$guard = tcp_connect $host, $service, $connect_cb[, $prepare_cb]
This is a convenience function that creates a TCP socket and makes
a 100% non-blocking connect to the given $host (which can be a
hostname or a textual IP address, or the string "unix/" for UNIX
domain sockets) and $service (which can be a numeric port number or
perl v5.12.2 2009-09-29 4
AnyEvent::SockeUser)Contributed Perl DocumentAnyEvent::Socket(3p)
a service name, or a "servicename=portnumber" string, or the
pathname to a UNIX domain socket).
If both $host and $port are names, then this function will use SRV
records to locate the real target(s).
In either case, it will create a list of target hosts (e.g. for
multihomed hosts or hosts with both IPv4 and IPv6 addresses) and
try to connect to each in turn.
After the connection is established, then the $connect_cb will be
invoked with the socket file handle (in non-blocking mode) as first
and the peer host (as a textual IP address) and peer port as second
and third arguments, respectively. The fourth argument is a code
reference that you can call if, for some reason, you don't like
this connection, which will cause "tcp_connect" to try the next one
(or call your callback without any arguments if there are no more
connections). In most cases, you can simply ignore this argument.
$cb->($filehandle, $host, $port, $retry)
If the connect is unsuccessful, then the $connect_cb will be
invoked without any arguments and $! will be set appropriately
(with "ENXIO" indicating a DNS resolution failure).
The callback will never be invoked before "tcp_connect" returns,
even if "tcp_connect" was able to connect immediately (e.g. on unix
domain sockets).
The file handle is perfect for being plugged into AnyEvent::Handle,
but can be used as a normal perl file handle as well.
Unless called in void context, "tcp_connect" returns a guard object
that will automatically abort connecting when it gets destroyed (it
does not do anything to the socket after the connect was
successful).
Sometimes you need to "prepare" the socket before connecting, for
example, to "bind" it to some port, or you want a specific connect
timeout that is lower than your kernel's default timeout. In this
case you can specify a second callback, $prepare_cb. It will be
called with the file handle in not-yet-connected state as only
argument and must return the connection timeout value (or 0,
"undef" or the empty list to indicate the default timeout is to be
used).
Note that the socket could be either a IPv4 TCP socket or an IPv6
TCP socket (although only IPv4 is currently supported by this
module).
Note to the poor Microsoft Windows users: Windows (of course)
doesn't correctly signal connection errors, so unless your event
library works around this, failed connections will simply hang. The
only event libraries that handle this condition correctly are EV
perl v5.12.2 2009-09-29 5
AnyEvent::SockeUser)Contributed Perl DocumentAnyEvent::Socket(3p)
and Glib. Additionally, AnyEvent works around this bug with Event
and in its pure-perl backend. All other libraries cannot correctly
handle this condition. To lessen the impact of this windows bug, a
default timeout of 30 seconds will be imposed on windows. Cygwin is
not affected.
Simple Example: connect to localhost on port 22.
tcp_connect localhost => 22, sub {
my $fh = shift
or die "unable to connect: $!";
# do something
};
Complex Example: connect to www.google.com on port 80 and make a
simple GET request without much error handling. Also limit the
connection timeout to 15 seconds.
tcp_connect "www.google.com", "http",
sub {
my ($fh) = @_
or die "unable to connect: $!";
my $handle; # avoid direct assignment so on_eof has it in scope.
$handle = new AnyEvent::Handle
fh => $fh,
on_error => sub {
warn "error $_[2]\n";
$_[0]->destroy;
},
on_eof => sub {
$handle->destroy; # destroy handle
warn "done.\n";
};
$handle->push_write ("GET / HTTP/1.0\015\012\015\012");
$handle->push_read (line => "\015\012\015\012", sub {
my ($handle, $line) = @_;
# print response header
print "HEADER\n$line\n\nBODY\n";
$handle->on_read (sub {
# print response body
print $_[0]->rbuf;
$_[0]->rbuf = "";
});
});
}, sub {
my ($fh) = @_;
# could call $fh->bind etc. here
15
perl v5.12.2 2009-09-29 6
AnyEvent::SockeUser)Contributed Perl DocumentAnyEvent::Socket(3p)
};
Example: connect to a UNIX domain socket.
tcp_connect "unix/", "/tmp/.X11-unix/X0", sub {
...
}
$guard = tcp_server $host, $service, $accept_cb[, $prepare_cb]
Create and bind a stream socket to the given host, and port, set
the SO_REUSEADDR flag (if applicable) and call "listen". Unlike the
name implies, this function can also bind on UNIX domain sockets.
For internet sockets, $host must be an IPv4 or IPv6 address (or
"undef", in which case it binds either to 0 or to "::", depending
on whether IPv4 or IPv6 is the preferred protocol, and maybe to
both in future versions, as applicable).
To bind to the IPv4 wildcard address, use 0, to bind to the IPv6
wildcard address, use "::".
The port is specified by $service, which must be either a service
name or a numeric port number (or 0 or "undef", in which case an
ephemeral port will be used).
For UNIX domain sockets, $host must be "unix/" and $service must be
the absolute pathname of the socket. This function will try to
"unlink" the socket before it tries to bind to it. See SECURITY
CONSIDERATIONS, below.
For each new connection that could be "accept"ed, call the
"$accept_cb->($fh, $host, $port)" with the file handle (in non-
blocking mode) as first and the peer host and port as second and
third arguments (see "tcp_connect" for details).
Croaks on any errors it can detect before the listen.
If called in non-void context, then this function returns a guard
object whose lifetime it tied to the TCP server: If the object gets
destroyed, the server will be stopped (but existing accepted
connections will continue).
If you need more control over the listening socket, you can provide
a "$prepare_cb->($fh, $host, $port)", which is called just before
the "listen ()" call, with the listen file handle as first
argument, and IP address and port number of the local socket
endpoint as second and third arguments.
It should return the length of the listen queue (or 0 for the
default).
Note to IPv6 users: RFC-compliant behaviour for IPv6 sockets
listening on "::" is to bind to both IPv6 and IPv4 addresses by
default on dual-stack hosts. Unfortunately, only GNU/Linux seems to
perl v5.12.2 2009-09-29 7
AnyEvent::SockeUser)Contributed Perl DocumentAnyEvent::Socket(3p)
implement this properly, so if you want both IPv4 and IPv6
listening sockets you should create the IPv6 socket first and then
attempt to bind on the IPv4 socket, but ignore any "EADDRINUSE"
errors.
Example: bind on some TCP port on the local machine and tell each
client to go away.
tcp_server undef, undef, sub {
my ($fh, $host, $port) = @_;
syswrite $fh, "The internet is full, $host:$port. Go away!\015\012";
}, sub {
my ($fh, $thishost, $thisport) = @_;
warn "bound to $thishost, port $thisport\n";
};
Example: bind a server on a unix domain socket.
tcp_server "unix/", "/tmp/mydir/mysocket", sub {
my ($fh) = @_;
};
SECURITY CONSIDERATIONS
This module is quite powerful, with with power comes the ability to
abuse as well: If you accept "hostnames" and ports from untrusted
sources, then note that this can be abused to delete files
(host="unix/"). This is not really a problem with this module, however,
as blindly accepting any address and protocol and trying to bind a
server or connect to it is harmful in general.
AUTHOR
Marc Lehmann <schmorpATschmorp.de>
http://home.schmorp.de/
perl v5.12.2 2009-09-29 8
|
