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.