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.