NAME
    IO::EventMux::Socket::MsgHdr - sendmsg, recvmsg and ancillary data
    operations

SYNOPSIS
      use IO::EventMux::Socket::MsgHdr;
      use Socket;

      # sendto() behavior
      my $echo = sockaddr_in(7, inet_aton("10.20.30.40"));
      my $outMsg = new IO::EventMux::Socket::MsgHdr(buf  => "Testing echo service",
                                      name => $echo);
      sendmsg(OUT, $outMsg, 0) or die "sendmsg: $!\n";

      # recvfrom() behavior, OO-style
      my $msgHdr = new IO::EventMux::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, $msgHdr);

      # Unpack the same
      my $inHdr = IO::EventMux::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
    IO::EventMux::Socket::MsgHdr is a fork of Socket::MsgHdr as the old
    author did not respond in regards to a cleanup patch to get rid of
    warnings in both modules and tests. This fork has since restructured the
    module so it's simpler to understand and maintain.

    IO::EventMux::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
    implementation-specific extensions.

METHODS
    new()
        Return a new IO::EventMux::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.

    name [SCALAR]
        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.

    namelen LENGTH
    buf [SCALAR]
    buflen LENGTH
        "buf" gets the current message buffer or sets it to SCALAR. "buflen"
        allocates LENGTH bytes for use in recvmsg.

    control()
    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 IO::EventMux::Socket::MsgHdr flags, distinct from the
        sendmsg or recvmsg flags. Example:

          $hdr = new IO::EventMux::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 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);

    sendmsg SOCKET, MSGHDR
    sendmsg SOCKET, MSGHDR, FLAGS
        Send a message as described by "IO::EventMux::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 "IO::EventMux::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.

    pack_cmsghdr
    unpack_cmsghdr
    socket_errors($socket)
        Read "MSG_ERRQUEUE" errors on socket and decode ICMP error msg

EXPORT
    "IO::EventMux::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), "RFC 2292"

AUTHOR
    Troels Liebe Bentsen <tlb@rapanden.dk>

COPYRIGHT AND LICENSE
    Copyright(C) 2007-2008 by Troels Liebe Bentsen Copyright(C) 2003 by
    Michael J. Pomraning

    This library is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.

