Help-Site Computer Manuals
Software
Hardware
Programming
Networking
  Algorithms & Data Structures   Programming Languages   Revision Control
  Protocols
  Cameras   Computers   Displays   Keyboards & Mice   Motherboards   Networking   Printers & Scanners   Storage
  Windows   Linux & Unix   Mac

Socket::MsgHdr
sendmsg, recvmsg and ancillary data operations

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


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, $msgHdr);

  # 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 (the name manpage), 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 perlfunc/send and perlfunc/recv. 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 perlfunc/pack 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), the File::FDpasser manpage, RFC 2292


AUTHOR

Michael J. Pomraning

Please report bugs to <mjp-perl AT pilcrow.madison.wi.us >


COPYRIGHT AND LICENSE

Copyright 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.

Programminig
Wy
Wy
yW
Wy
Programming
Wy
Wy
Wy
Wy