1Socket::MsgHdr(3) User Contributed Perl Documentation Socket::MsgHdr(3)
2
6 Socket::MsgHdr - sendmsg, recvmsg and ancillary data operations
7
9 use Socket::MsgHdr;
10 use Socket;
11 # sendto() behavior
13 my $echo = sockaddr_in(7, inet_aton("10.20.30.40"));
14 my $outMsg = new Socket::MsgHdr(buf => "Testing echo service",
15 name => $echo);
16 sendmsg(OUT, $outMsg, 0) or die "sendmsg: $!\n";
17 # recvfrom() behavior, OO-style
19 my $msgHdr = new Socket::MsgHdr(buflen => 512)
20 $msgHdr->buflen(8192); # maybe 512 wasn't enough!
22 $msgHdr->namelen(256); # only 16 bytes needed for IPv4
23 die "recvmsg: $!\n" unless defined recvmsg(IN, $msgHdr, 0);
25 my ($port, $iaddr) = sockaddr_in($msgHdr->name());
27 my $dotted = inet_ntoa($iaddr);
28 print "$dotted:$port said: " . $msgHdr->buf() . "\n";
29 # Pack ancillary data for sending
31 $outHdr->cmsghdr(SOL_SOCKET, # cmsg_level
32 SCM_RIGHTS, # cmsg_type
33 pack("i", fileno(STDIN))); # cmsg_data
34 sendmsg(OUT, $outHdr);
35 # Unpack the same
37 my $inHdr = Socket::MsgHdr->new(buflen => 8192, controllen => 256);
38 recvmsg(IN, $inHdr, $flags);
39 my ($level, $type, $data) = $inHdr->cmsghdr();
40 my $new_fileno = unpack('i', $data);
41 open(NewFH, '<&=' . $new_fileno); # voila!
42
44 Socket::MsgHdr provides advanced socket messaging operations via
45 sendmsg and recvmsg. Like their C counterparts, these functions accept
46 few parameters, instead stuffing a lot of information into a complex
47 structure.
48 This structure describes the message sent or received (buf), the peer
50 on the other end of the socket (name), and ancillary or so-called
51 control information (cmsghdr). This ancillary data may be used for
52 file descriptor passing, IPv6 operations, and a host of implemenation-
53 specific extensions.
54 FUNCTIONS
56 sendmsg SOCKET, MSGHDR
57 sendmsg SOCKET, MSGHDR, FLAGS
58 Send a message as described by "Socket::MsgHdr" MSGHDR over SOCKET,
59 optionally as specified by FLAGS (default 0). MSGHDR should supply
60 at least a buf member, and connectionless socket senders might also
61 supply a name member. Ancillary data may be sent via control.
62 Returns number of bytes sent, or undef on failure.
64 recvmsg SOCKET, MSGHDR
66 recvmsg SOCKET, MSGHDR, FLAGS
67 Receive a message as requested by "Socket::MsgHdr" MSGHDR from
68 SOCKET, optionally as specified by FLAGS (default 0). The caller
69 requests buflen bytes in MSGHDR, possibly also recording up to
70 namelen bytes of the sender's (packed) address and perhaps
71 controllen bytes of ancillary data.
72 Returns number of bytes received, or undef on failure. buflen et.
74 al. are updated to reflect the actual lengths of received data.
75 Socket::MsgHdr
77 new [PARAMETERS]
78 Return a new Socket::MsgHdr object. Optional PARAMETERS may
79 specify method names ("buf", "name", "control", "flags" or their
80 corresponding ...len methods where applicable) and values, sparing
81 an explicit call to those methods.
82 buf [SCALAR]
84 buflen LENGTH
85 "buf" gets the current message buffer or sets it to SCALAR.
86 "buflen" allocates LENGTH bytes for use in recvmsg.
87 name [SCALAR]
89 namelen LENGTH
90 Get or set the socket name (address) buffer, an attribute analogous
91 to the optional TO and FROM parameters of "send" in perlfunc and
92 "recv" in perlfunc. Note that socket names are packed structures.
93 controllen LENGTH
95 Prepare the ancillary data buffer to receive LENGTH bytes. There
96 is a corresponding "control" method, but its use is discouraged --
97 you have to "pack" in perlfunc the "struct cmsghdr" yourself.
98 Instead see cmsghdr below for convenient access to the control
99 member.
100 flags [FLAGS]
102 Get or set the Socket::MsgHdr flags, distinct from the sendmsg or
103 recvmsg flags. Example:
104 $hdr = new Socket::MsgHdr (buflen => 512, controllen => 3);
106 recvmsg(IN, $hdr);
107 if ($hdr->flags & MSG_CTRUNC) { # &Socket::MSG_CTRUNC
108 warn "Yikes! Ancillary data was truncated\n";
109 }
110 cmsghdr
112 cmsghdr LEVEL, TYPE, DATA [ LEVEL, TYPE, DATA ... ]
113 Without arguments, this method returns a list of "LEVEL, TYPE,
114 DATA, ...", or an empty list if there is no ancillary data. With
115 arguments, this method copies and flattens its parameters into the
116 internal control buffer.
117 In any case, DATA is in a message-specific format which likely
119 requires special treatment (packing or unpacking).
120 Examples:
122 my @cmsg = $hdr->cmsghdr();
124 while (my ($level, $type, $data) = splice(@cmsg, 0, 3)) {
125 warn "unknown cmsg LEVEL\n", next unless $level == IPPROTO_IPV6;
126 warn "unknown cmsg TYPE\n", next unless $type == IPV6_PKTINFO;
127 ...
128 }
129 my $data = pack("i" x @filehandles, map {fileno $_} @filehandles);
131 my $hdr->cmsghdr(SOL_SOCKET, SCM_RIGHTS, $data);
132 sendmsg(S, $hdr);
133 EXPORT
135 "Socket::MsgHdr" exports sendmsg and recvmsg by default into the
136 caller's namespace, and in any case these methods into the IO::Socket
137 namespace.
138
140 The underlying XS presently makes use of RFC 2292 CMSG_* manipulation
141 macros, which may not be available on all systems supporting
142 sendmsg/recvmsg as known to 4.3BSD Reno/POSIX.1g. Older "struct
143 msghdr" definitions with "msg_accrights" members (instead of
144 "msg_control") are not supported at all.
145 There is no Socket::CMsgHdr, which may be a good thing. Examples are
147 meager, see the t/ directory for send(to) and recv(from) emulations in
148 terms of this module.
149
151 sendmsg(2), recvmsg(2), File::FDpasser, RFC 2292
152 <https://tools.ietf.org/html/rfc2292>
153
155 Michael J. Pomraning, co-maintained by Felipe Gasper
156
158 Copyright 2003, 2010 by Michael J. Pomraning
159 This library is free software; you can redistribute it and/or modify it
161 under the same terms as Perl itself.
162perl v5.38.0 2023-07-21 Socket::MsgHdr(3)