NAME¶
Socket::MsgHdr - sendmsg, recvmsg and ancillary data operations
SYNOPSIS¶
use Socket::MsgHdr;
use Socket;
# sendto() behavior
my $echo = sockaddr_in(7, inet_aton("10.20.30.40"));
my $outMsg = new Socket::MsgHdr(buf => "Testing echo service",
name => $echo);
sendmsg(OUT, $outMsg, 0) or die "sendmsg: $!\n";
# recvfrom() behavior, OO-style
my $msgHdr = new Socket::MsgHdr(buflen => 512)
$msgHdr->buflen(8192); # maybe 512 wasn't enough!
$msgHdr->namelen(256); # only 16 bytes needed for IPv4
die "recvmsg: $!\n" unless defined recvmsg(IN, $msgHdr, 0);
my ($port, $iaddr) = sockaddr_in($msgHdr->name());
my $dotted = inet_ntoa($iaddr);
print "$dotted:$port said: " . $msgHdr->buf() . "\n";
# Pack ancillary data for sending
$outHdr->cmsghdr(SOL_SOCKET, # cmsg_level
SCM_RIGHTS, # cmsg_type
pack("i", fileno(STDIN))); # cmsg_data
sendmsg(OUT, $outHdr);
# Unpack the same
my $inHdr = Socket::MsgHdr->new(buflen => 8192, controllen => 256);
recvmsg(IN, $inHdr, $flags);
my ($level, $type, $data) = $inHdr->cmsghdr();
my $new_fileno = unpack('i', $data);
open(NewFH, '<&=' . $new_fileno); # voila!
DESCRIPTION¶
Socket::MsgHdr provides advanced socket messaging operations via sendmsg and
recvmsg. Like their C counterparts, these functions accept few parameters,
instead stuffing a lot of information into a complex structure.
This structure describes the message sent or received (buf), the peer on the
other end of the socket (name), and ancillary or so-called control information
(cmsghdr). This ancillary data may be used for file descriptor passing, IPv6
operations, and a host of implemenation-specific extensions.
FUNCTIONS¶
- sendmsg SOCKET, MSGHDR
- sendmsg SOCKET, MSGHDR, FLAGS
- Send a message as described by "Socket::MsgHdr" MSGHDR over
SOCKET, optionally as specified by FLAGS (default 0). MSGHDR should supply
at least a buf member, and connectionless socket senders might also
supply a name member. Ancillary data may be sent via
control.
Returns number of bytes sent, or undef on failure.
- recvmsg SOCKET, MSGHDR
- recvmsg SOCKET, MSGHDR, FLAGS
- Receive a message as requested by "Socket::MsgHdr" MSGHDR from
SOCKET, optionally as specified by FLAGS (default 0). The caller requests
buflen bytes in MSGHDR, possibly also recording up to
namelen bytes of the sender's (packed) address and perhaps
controllen bytes of ancillary data.
Returns number of bytes received, or undef on failure. buflen et. al.
are updated to reflect the actual lengths of received data.
Socket::MsgHdr¶
- new [PARAMETERS]
- Return a new Socket::MsgHdr object. Optional PARAMETERS may specify method
names ("buf", "name", "control",
"flags" or their corresponding ...len methods where
applicable) and values, sparing an explicit call to those methods.
- buf [SCALAR]
- buflen LENGTH
- "buf" gets the current message buffer or sets it to SCALAR.
"buflen" allocates LENGTH bytes for use in recvmsg.
- name [SCALAR]
- namelen LENGTH
- Get or set the socket name (address) buffer, an attribute analogous to the
optional TO and FROM parameters of "send" in perlfunc and
"recv" in perlfunc. Note that socket names are packed
structures.
- controllen LENGTH
- Prepare the ancillary data buffer to receive LENGTH bytes. There is a
corresponding "control" method, but its use is discouraged --
you have to "pack" in perlfunc the "struct cmsghdr"
yourself. Instead see cmsghdr below for convenient access to the control
member.
- flags [FLAGS]
- Get or set the Socket::MsgHdr flags, distinct from the sendmsg or recvmsg
flags. Example:
$hdr = new Socket::MsgHdr (buflen => 512, controllen => 3);
recvmsg(IN, $hdr);
if ($hdr->flags & MSG_CTRUNC) { # &Socket::MSG_CTRUNC
warn "Yikes! Ancillary data was truncated\n";
}
- cmsghdr
- cmsghdr LEVEL, TYPE, DATA [ LEVEL, TYPE, DATA ... ]
- Without arguments, this method returns a list of "LEVEL, TYPE, DATA,
...", or an empty list if there is no ancillary data. With arguments,
this method copies and flattens its parameters into the internal control
buffer.
In any case, DATA is in a message-specific format which likely requires
special treatment (packing or unpacking).
Examples:
my @cmsg = $hdr->cmsghdr();
while (my ($level, $type, $data) = splice(@cmsg, 0, 3)) {
warn "unknown cmsg LEVEL\n", next unless $level == IPPROTO_IPV6;
warn "unknown cmsg TYPE\n", next unless $type == IPV6_PKTINFO;
...
}
my $data = pack("i" x @filehandles, map {fileno $_} @filehandles);
my $hdr->cmsghdr(SOL_SOCKET, SCM_RIGHTS, $data);
sendmsg(S, $hdr);
EXPORT¶
"Socket::MsgHdr" exports sendmsg and recvmsg by default into the
caller's namespace, and in any case these methods into the IO::Socket
namespace.
BUGS¶
The underlying XS presently makes use of RFC 2292 CMSG_* manipulation macros,
which may not be available on all systems supporting sendmsg/recvmsg as known
to 4.3BSD Reno/POSIX.1g. Older "struct msghdr" definitions with
"msg_accrights" members (instead of "msg_control") are not
supported at all.
There is no Socket::CMsgHdr, which may be a good thing. Examples are meager, see
the t/ directory for send(to) and recv(from) emulations in terms of this
module.
SEE ALSO¶
sendmsg(2),
recvmsg(2), File::FDpasser, "RFC 2292"
AUTHOR¶
Michael J. Pomraning
Please report bugs to <mjp AT cpan DOT org >
COPYRIGHT AND LICENSE¶
Copyright 2003, 2010 by Michael J. Pomraning
This library is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.