1Socket::MsgHdr(3)     User Contributed Perl Documentation    Socket::MsgHdr(3)
2
3
4

NAME

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

SYNOPSIS

9         use Socket::MsgHdr;
10         use Socket;
11
12         # 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
18         # recvfrom() behavior, OO-style
19         my $msgHdr = new Socket::MsgHdr(buflen => 512)
20
21         $msgHdr->buflen(8192);    # maybe 512 wasn't enough!
22         $msgHdr->namelen(256);    # only 16 bytes needed for IPv4
23
24         die "recvmsg: $!\n" unless defined recvmsg(IN, $msgHdr, 0);
25
26         my ($port, $iaddr) = sockaddr_in($msgHdr->name());
27         my $dotted = inet_ntoa($iaddr);
28         print "$dotted:$port said: " . $msgHdr->buf() . "\n";
29
30         # 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
36         # 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

DESCRIPTION

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
49       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
55   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
63           Returns number of bytes sent, or undef on failure.
64
65       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
73           Returns number of bytes received, or undef on failure.  buflen et.
74           al. are updated to reflect the actual lengths of received data.
75
76   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
83       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
88       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
94       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
101       flags [FLAGS]
102           Get or set the Socket::MsgHdr flags, distinct from the sendmsg or
103           recvmsg flags.  Example:
104
105             $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
111       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
118           In any case, DATA is in a message-specific format which likely
119           requires special treatment (packing or unpacking).
120
121           Examples:
122
123              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
130              my $data = pack("i" x @filehandles, map {fileno $_} @filehandles);
131              my $hdr->cmsghdr(SOL_SOCKET, SCM_RIGHTS, $data);
132              sendmsg(S, $hdr);
133
134   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

BUGS

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
146       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

SEE ALSO

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

AUTHOR

155       Michael J. Pomraning, co-maintained by Felipe Gasper
156
158       Copyright 2003, 2010 by Michael J. Pomraning
159
160       This library is free software; you can redistribute it and/or modify it
161       under the same terms as Perl itself.
162
163
164
165perl v5.38.0                      2023-07-21                 Socket::MsgHdr(3)
Impressum