Socket::MsgHdr - sendmsg, recvmsg and ancillary data operations

       Michael J. Pomraning, co-maintained by Felipe Gasper

       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.

       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.

perl v5.40.0                                       2024-10-20                                Socket::MsgHdr(3pm)

       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.

       Socket::MsgHdr - sendmsg, recvmsg and ancillary data operations

sendmsg(2), recvmsg(2), File::FDpasser, RFC 2292 <https://tools.ietf.org/html/rfc2292>

         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!