Debian Codegraph @

upstream/debian-unstable/man3/Net::NNTP.3perl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "Net::NNTP 3perl"
58 .TH Net::NNTP 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 Net::NNTP \- NNTP Client class
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 1
68 \& use Net::NNTP;
69 \&
70 \& $nntp = Net::NNTP\->new("some.host.name");
71 \& $nntp\->quit;
72 \&
73 \& # start with SSL, e.g. nntps
74 \& $nntp = Net::NNTP\->new("some.host.name", SSL => 1);
75 \&
76 \& # start with plain and upgrade to SSL
77 \& $nntp = Net::NNTP\->new("some.host.name");
78 \& $nntp\->starttls;
79 .Ve
80 .SH DESCRIPTION
81 .IX Header "DESCRIPTION"
82 \&\f(CW\*(C`Net::NNTP\*(C'\fR is a class implementing a simple NNTP client in Perl as described
83 in RFC977 and RFC4642.
84 With IO::Socket::SSL installed it also provides support for implicit and
85 explicit TLS encryption, i.e. NNTPS or NNTP+STARTTLS.
86 .PP
87 The Net::NNTP class is a subclass of Net::Cmd and (depending on avaibility) of
88 IO::Socket::IP, IO::Socket::INET6 or IO::Socket::INET.
89 .SS "Class Methods"
90 .IX Subsection "Class Methods"
91 .ie n .IP """new([$host][, %options])""" 4
92 .el .IP "\f(CWnew([$host][, %options])\fR" 4
93 .IX Item "new([$host][, %options])"
94 This is the constructor for a new Net::NNTP object. \f(CW$host\fR is the
95 name of the remote host to which a NNTP connection is required. If not
96 given then it may be passed as the \f(CW\*(C`Host\*(C'\fR option described below. If no host is passed
97 then two environment variables are checked, first \f(CW\*(C`NNTPSERVER\*(C'\fR then
98 \&\f(CW\*(C`NEWSHOST\*(C'\fR, then \f(CW\*(C`Net::Config\*(C'\fR is checked, and if a host is not found
99 then \f(CW\*(C`news\*(C'\fR is used.
100 .Sp
101 \&\f(CW%options\fR are passed in a hash like fashion, using key and value pairs.
102 Possible options are:
103 .Sp
104 \&\fBHost\fR \- NNTP host to connect to. It may be a single scalar, as defined for
105 the \f(CW\*(C`PeerAddr\*(C'\fR option in IO::Socket::INET, or a reference to
106 an array with hosts to try in turn. The "host" method will return the value
107 which was used to connect to the host.
108 .Sp
109 \&\fBPort\fR \- port to connect to.
110 Default \- 119 for plain NNTP and 563 for immediate SSL (nntps).
111 .Sp
112 \&\fBSSL\fR \- If the connection should be done from start with SSL, contrary to later
113 upgrade with \f(CW\*(C`starttls\*(C'\fR.
114 You can use SSL arguments as documented in IO::Socket::SSL, but it will
115 usually use the right arguments already.
116 .Sp
117 \&\fBTimeout\fR \- Maximum time, in seconds, to wait for a response from the
118 NNTP server, a value of zero will cause all IO operations to block.
119 (default: 120)
120 .Sp
121 \&\fBDebug\fR \- Enable the printing of debugging information to STDERR
122 .Sp
123 \&\fBReader\fR \- If the remote server is INN then initially the connection
124 will be to innd, by default \f(CW\*(C`Net::NNTP\*(C'\fR will issue a \f(CW\*(C`MODE READER\*(C'\fR command
125 so that the remote server becomes nnrpd. If the \f(CW\*(C`Reader\*(C'\fR option is given
126 with a value of zero, then this command will not be sent and the
127 connection will be left talking to innd.
128 .Sp
129 \&\fBLocalAddr\fR and \fBLocalPort\fR \- These parameters are passed directly
130 to IO::Socket to allow binding the socket to a specific local address and port.
131 .Sp
132 \&\fBDomain\fR \- This parameter is passed directly to IO::Socket and makes it
133 possible to enforce IPv4 connections even if IO::Socket::IP is used as super
134 class. Alternatively \fBFamily\fR can be used.
135 .SS "Object Methods"
136 .IX Subsection "Object Methods"
137 Unless otherwise stated all methods return either a \fItrue\fR or \fIfalse\fR
138 value, with \fItrue\fR meaning that the operation was a success. When a method
139 states that it returns a value, failure will be returned as \fIundef\fR or an
140 empty list.
141 .PP
142 \&\f(CW\*(C`Net::NNTP\*(C'\fR inherits from \f(CW\*(C`Net::Cmd\*(C'\fR so methods defined in \f(CW\*(C`Net::Cmd\*(C'\fR may
143 be used to send commands to the remote NNTP server in addition to the methods
144 documented here.
145 .ie n .IP host() 4
146 .el .IP \f(CWhost()\fR 4
147 .IX Item "host()"
148 Returns the value used by the constructor, and passed to IO::Socket::INET,
149 to connect to the host.
150 .ie n .IP starttls() 4
151 .el .IP \f(CWstarttls()\fR 4
152 .IX Item "starttls()"
153 Upgrade existing plain connection to SSL.
154 Any arguments necessary for SSL must be given in \f(CW\*(C`new\*(C'\fR already.
155 .ie n .IP """article([{$msgid|$msgnum}[, $fh]])""" 4
156 .el .IP "\f(CWarticle([{$msgid|$msgnum}[, $fh]])\fR" 4
157 .IX Item "article([{$msgid|$msgnum}[, $fh]])"
158 Retrieve the header, a blank line, then the body (text) of the
159 specified article.
160 .Sp
161 If \f(CW$fh\fR is specified then it is expected to be a valid filehandle
162 and the result will be printed to it, on success a true value will be
163 returned. If \f(CW$fh\fR is not specified then the return value, on success,
164 will be a reference to an array containing the article requested, each
165 entry in the array will contain one line of the article.
166 .Sp
167 If no arguments are passed then the current article in the currently
168 selected newsgroup is fetched.
169 .Sp
170 \&\f(CW$msgnum\fR is a numeric id of an article in the current newsgroup, and
171 will change the current article pointer. \f(CW$msgid\fR is the message id of
172 an article as shown in that article's header. It is anticipated that the
173 client will obtain the \f(CW$msgid\fR from a list provided by the \f(CW\*(C`newnews\*(C'\fR
174 command, from references contained within another article, or from the
175 message-id provided in the response to some other commands.
176 .Sp
177 If there is an error then \f(CW\*(C`undef\*(C'\fR will be returned.
178 .ie n .IP """body([{$msgid|$msgnum}[, [$fh]])""" 4
179 .el .IP "\f(CWbody([{$msgid|$msgnum}[, [$fh]])\fR" 4
180 .IX Item "body([{$msgid|$msgnum}[, [$fh]])"
181 Like \f(CW\*(C`article\*(C'\fR but only fetches the body of the article.
182 .ie n .IP """head([{$msgid|$msgnum}[, [$fh]])""" 4
183 .el .IP "\f(CWhead([{$msgid|$msgnum}[, [$fh]])\fR" 4
184 .IX Item "head([{$msgid|$msgnum}[, [$fh]])"
185 Like \f(CW\*(C`article\*(C'\fR but only fetches the headers for the article.
186 .ie n .IP articlefh([{$msgid|$msgnum}]) 4
187 .el .IP \f(CWarticlefh([{$msgid|$msgnum}])\fR 4
188 .IX Item "articlefh([{$msgid|$msgnum}])"
189 .PD 0
190 .ie n .IP bodyfh([{$msgid|$msgnum}]) 4
191 .el .IP \f(CWbodyfh([{$msgid|$msgnum}])\fR 4
192 .IX Item "bodyfh([{$msgid|$msgnum}])"
193 .ie n .IP headfh([{$msgid|$msgnum}]) 4
194 .el .IP \f(CWheadfh([{$msgid|$msgnum}])\fR 4
195 .IX Item "headfh([{$msgid|$msgnum}])"
196 .PD
197 These are similar to \fBarticle()\fR, \fBbody()\fR and \fBhead()\fR, but rather than
198 returning the requested data directly, they return a tied filehandle
199 from which to read the article.
200 .ie n .IP nntpstat([{$msgid|$msgnum}]) 4
201 .el .IP \f(CWnntpstat([{$msgid|$msgnum}])\fR 4
202 .IX Item "nntpstat([{$msgid|$msgnum}])"
203 The \f(CW\*(C`nntpstat\*(C'\fR command is similar to the \f(CW\*(C`article\*(C'\fR command except that no
204 text is returned. When selecting by message number within a group,
205 the \f(CW\*(C`nntpstat\*(C'\fR command serves to set the "current article pointer" without
206 sending text.
207 .Sp
208 Using the \f(CW\*(C`nntpstat\*(C'\fR command to
209 select by message-id is valid but of questionable value, since a
210 selection by message-id does \fBnot\fR alter the "current article pointer".
211 .Sp
212 Returns the message-id of the "current article".
213 .ie n .IP group([$group]) 4
214 .el .IP \f(CWgroup([$group])\fR 4
215 .IX Item "group([$group])"
216 Set and/or get the current group. If \f(CW$group\fR is not given then information
217 is returned on the current group.
218 .Sp
219 In a scalar context it returns the group name.
220 .Sp
221 In an array context the return value is a list containing, the number
222 of articles in the group, the number of the first article, the number
223 of the last article and the group name.
224 .ie n .IP help() 4
225 .el .IP \f(CWhelp()\fR 4
226 .IX Item "help()"
227 Request help text (a short summary of commands that are understood by this
228 implementation) from the server. Returns the text or undef upon failure.
229 .ie n .IP """ihave($msgid[, $message])""" 4
230 .el .IP "\f(CWihave($msgid[, $message])\fR" 4
231 .IX Item "ihave($msgid[, $message])"
232 The \f(CW\*(C`ihave\*(C'\fR command informs the server that the client has an article
233 whose id is \f(CW$msgid\fR. If the server desires a copy of that
234 article and \f(CW$message\fR has been given then it will be sent.
235 .Sp
236 Returns \fItrue\fR if the server desires the article and \f(CW$message\fR was
237 successfully sent, if specified.
238 .Sp
239 If \f(CW$message\fR is not specified then the message must be sent using the
240 \&\f(CW\*(C`datasend\*(C'\fR and \f(CW\*(C`dataend\*(C'\fR methods from Net::Cmd
241 .Sp
242 \&\f(CW$message\fR can be either an array of lines or a reference to an array
243 and must be encoded by the caller to octets of whatever encoding is required,
244 e.g. by using the Encode module's \f(CWencode()\fR function.
245 .ie n .IP last() 4
246 .el .IP \f(CWlast()\fR 4
247 .IX Item "last()"
248 Set the "current article pointer" to the previous article in the current
249 newsgroup.
250 .Sp
251 Returns the message-id of the article.
252 .ie n .IP date() 4
253 .el .IP \f(CWdate()\fR 4
254 .IX Item "date()"
255 Returns the date on the remote server. This date will be in a UNIX time
256 format (seconds since 1970)
257 .ie n .IP postok() 4
258 .el .IP \f(CWpostok()\fR 4
259 .IX Item "postok()"
260 \&\f(CW\*(C`postok\*(C'\fR will return \fItrue\fR if the servers initial response indicated
261 that it will allow posting.
262 .ie n .IP """authinfo($user, $pass)""" 4
263 .el .IP "\f(CWauthinfo($user, $pass)\fR" 4
264 .IX Item "authinfo($user, $pass)"
265 Authenticates to the server (using the original AUTHINFO USER / AUTHINFO PASS
266 form, defined in RFC2980) using the supplied username and password. Please
267 note that the password is sent in clear text to the server. This command
268 should not be used with valuable passwords unless the connection to the server
269 is somehow protected.
270 .ie n .IP """authinfo_simple($user, $pass)""" 4
271 .el .IP "\f(CWauthinfo_simple($user, $pass)\fR" 4
272 .IX Item "authinfo_simple($user, $pass)"
273 Authenticates to the server (using the proposed NNTP V2 AUTHINFO SIMPLE form,
274 defined and deprecated in RFC2980) using the supplied username and password.
275 As with "authinfo" the password is sent in clear text.
276 .ie n .IP list() 4
277 .el .IP \f(CWlist()\fR 4
278 .IX Item "list()"
279 Obtain information about all the active newsgroups. The results is a reference
280 to a hash where the key is a group name and each value is a reference to an
281 array. The elements in this array are:\- the last article number in the group,
282 the first article number in the group and any information flags about the group.
283 .ie n .IP """newgroups($since[, $distributions])""" 4
284 .el .IP "\f(CWnewgroups($since[, $distributions])\fR" 4
285 .IX Item "newgroups($since[, $distributions])"
286 \&\f(CW$since\fR is a time value and \f(CW$distributions\fR is either a distribution
287 pattern or a reference to a list of distribution patterns.
288 The result is the same as \f(CW\*(C`list\*(C'\fR, but the
289 groups return will be limited to those created after \f(CW$since\fR and, if
290 specified, in one of the distribution areas in \f(CW$distributions\fR.
291 .ie n .IP """newnews($since[, $groups[, $distributions]])""" 4
292 .el .IP "\f(CWnewnews($since[, $groups[, $distributions]])\fR" 4
293 .IX Item "newnews($since[, $groups[, $distributions]])"
294 \&\f(CW$since\fR is a time value. \f(CW$groups\fR is either a group pattern or a reference
295 to a list of group patterns. \f(CW$distributions\fR is either a distribution
296 pattern or a reference to a list of distribution patterns.
297 .Sp
298 Returns a reference to a list which contains the message-ids of all news posted
299 after \f(CW$since\fR, that are in a groups which matched \f(CW$groups\fR and a
300 distribution which matches \f(CW$distributions\fR.
301 .ie n .IP next() 4
302 .el .IP \f(CWnext()\fR 4
303 .IX Item "next()"
304 Set the "current article pointer" to the next article in the current
305 newsgroup.
306 .Sp
307 Returns the message-id of the article.
308 .ie n .IP post([$message]) 4
309 .el .IP \f(CWpost([$message])\fR 4
310 .IX Item "post([$message])"
311 Post a new article to the news server. If \f(CW$message\fR is specified and posting
312 is allowed then the message will be sent.
313 .Sp
314 If \f(CW$message\fR is not specified then the message must be sent using the
315 \&\f(CW\*(C`datasend\*(C'\fR and \f(CW\*(C`dataend\*(C'\fR methods from Net::Cmd
316 .Sp
317 \&\f(CW$message\fR can be either an array of lines or a reference to an array
318 and must be encoded by the caller to octets of whatever encoding is required,
319 e.g. by using the Encode module's \f(CWencode()\fR function.
320 .Sp
321 The message, either sent via \f(CW\*(C`datasend\*(C'\fR or as the \f(CW$message\fR
322 parameter, must be in the format as described by RFC822 and must
323 contain From:, Newsgroups: and Subject: headers.
324 .ie n .IP postfh() 4
325 .el .IP \f(CWpostfh()\fR 4
326 .IX Item "postfh()"
327 Post a new article to the news server using a tied filehandle. If
328 posting is allowed, this method will return a tied filehandle that you
329 can \fBprint()\fR the contents of the article to be posted. You must
330 explicitly \fBclose()\fR the filehandle when you are finished posting the
331 article, and the return value from the \fBclose()\fR call will indicate
332 whether the message was successfully posted.
333 .ie n .IP slave() 4
334 .el .IP \f(CWslave()\fR 4
335 .IX Item "slave()"
336 Tell the remote server that I am not a user client, but probably another
337 news server.
338 .ie n .IP quit() 4
339 .el .IP \f(CWquit()\fR 4
340 .IX Item "quit()"
341 Quit the remote server and close the socket connection.
342 .ie n .IP can_inet6() 4
343 .el .IP \f(CWcan_inet6()\fR 4
344 .IX Item "can_inet6()"
345 Returns whether we can use IPv6.
346 .ie n .IP can_ssl() 4
347 .el .IP \f(CWcan_ssl()\fR 4
348 .IX Item "can_ssl()"
349 Returns whether we can use SSL.
350 .SS "Extension Methods"
351 .IX Subsection "Extension Methods"
352 These methods use commands that are not part of the RFC977 documentation. Some
353 servers may not support all of them.
354 .ie n .IP newsgroups([$pattern]) 4
355 .el .IP \f(CWnewsgroups([$pattern])\fR 4
356 .IX Item "newsgroups([$pattern])"
357 Returns a reference to a hash where the keys are all the group names which
358 match \f(CW$pattern\fR, or all of the groups if no pattern is specified, and
359 each value contains the description text for the group.
360 .ie n .IP distributions() 4
361 .el .IP \f(CWdistributions()\fR 4
362 .IX Item "distributions()"
363 Returns a reference to a hash where the keys are all the possible
364 distribution names and the values are the distribution descriptions.
365 .ie n .IP distribution_patterns() 4
366 .el .IP \f(CWdistribution_patterns()\fR 4
367 .IX Item "distribution_patterns()"
368 Returns a reference to an array where each element, itself an array
369 reference, consists of the three fields of a line of the distrib.pats list
370 maintained by some NNTP servers, namely: a weight, a wildmat and a value
371 which the client may use to construct a Distribution header.
372 .ie n .IP subscriptions() 4
373 .el .IP \f(CWsubscriptions()\fR 4
374 .IX Item "subscriptions()"
375 Returns a reference to a list which contains a list of groups which
376 are recommended for a new user to subscribe to.
377 .ie n .IP overview_fmt() 4
378 .el .IP \f(CWoverview_fmt()\fR 4
379 .IX Item "overview_fmt()"
380 Returns a reference to an array which contain the names of the fields returned
381 by \f(CW\*(C`xover\*(C'\fR.
382 .ie n .IP active_times() 4
383 .el .IP \f(CWactive_times()\fR 4
384 .IX Item "active_times()"
385 Returns a reference to a hash where the keys are the group names and each
386 value is a reference to an array containing the time the groups was created
387 and an identifier, possibly an Email address, of the creator.
388 .ie n .IP active([$pattern]) 4
389 .el .IP \f(CWactive([$pattern])\fR 4
390 .IX Item "active([$pattern])"
391 Similar to \f(CW\*(C`list\*(C'\fR but only active groups that match the pattern are returned.
392 \&\f(CW$pattern\fR can be a group pattern.
393 .ie n .IP xgtitle($pattern) 4
394 .el .IP \f(CWxgtitle($pattern)\fR 4
395 .IX Item "xgtitle($pattern)"
396 Returns a reference to a hash where the keys are all the group names which
397 match \f(CW$pattern\fR and each value is the description text for the group.
398 .ie n .IP """xhdr($header, $message_spec)""" 4
399 .el .IP "\f(CWxhdr($header, $message_spec)\fR" 4
400 .IX Item "xhdr($header, $message_spec)"
401 Obtain the header field \f(CW$header\fR for all the messages specified.
402 .Sp
403 The return value will be a reference
404 to a hash where the keys are the message numbers and each value contains
405 the text of the requested header for that message.
406 .ie n .IP xover($message_spec) 4
407 .el .IP \f(CWxover($message_spec)\fR 4
408 .IX Item "xover($message_spec)"
409 The return value will be a reference
410 to a hash where the keys are the message numbers and each value contains
411 a reference to an array which contains the overview fields for that
412 message.
413 .Sp
414 The names of the fields can be obtained by calling \f(CW\*(C`overview_fmt\*(C'\fR.
415 .ie n .IP xpath($message_id) 4
416 .el .IP \f(CWxpath($message_id)\fR 4
417 .IX Item "xpath($message_id)"
418 Returns the path name to the file on the server which contains the specified
419 message.
420 .ie n .IP """xpat($header, $pattern, $message_spec)""" 4
421 .el .IP "\f(CWxpat($header, $pattern, $message_spec)\fR" 4
422 .IX Item "xpat($header, $pattern, $message_spec)"
423 The result is the same as \f(CW\*(C`xhdr\*(C'\fR except the is will be restricted to
424 headers where the text of the header matches \f(CW$pattern\fR
425 .ie n .IP xrover($message_spec) 4
426 .el .IP \f(CWxrover($message_spec)\fR 4
427 .IX Item "xrover($message_spec)"
428 The XROVER command returns reference information for the article(s)
429 specified.
430 .Sp
431 Returns a reference to a HASH where the keys are the message numbers and the
432 values are the References: lines from the articles
433 .ie n .IP listgroup([$group]) 4
434 .el .IP \f(CWlistgroup([$group])\fR 4
435 .IX Item "listgroup([$group])"
436 Returns a reference to a list of all the active messages in \f(CW$group\fR, or
437 the current group if \f(CW$group\fR is not specified.
438 .ie n .IP reader() 4
439 .el .IP \f(CWreader()\fR 4
440 .IX Item "reader()"
441 Tell the server that you are a reader and not another server.
442 .Sp
443 This is required by some servers. For example if you are connecting to
444 an INN server and you have transfer permission your connection will
445 be connected to the transfer daemon, not the NNTP daemon. Issuing
446 this command will cause the transfer daemon to hand over control
447 to the NNTP daemon.
448 .Sp
449 Some servers do not understand this command, but issuing it and ignoring
450 the response is harmless.
451 .SS Unsupported
452 .IX Subsection "Unsupported"
453 The following NNTP command are unsupported by the package, and there are
454 no plans to do so.
455 .PP
456 .Vb 4
457 \& AUTHINFO GENERIC
458 \& XTHREAD
459 \& XSEARCH
460 \& XINDEX
461 .Ve
462 .SS Definitions
463 .IX Subsection "Definitions"
464 .ie n .IP $message_spec 4
465 .el .IP \f(CW$message_spec\fR 4
466 .IX Item "$message_spec"
467 \&\f(CW$message_spec\fR is either a single message-id, a single message number, or
468 a reference to a list of two message numbers.
469 .Sp
470 If \f(CW$message_spec\fR is a reference to a list of two message numbers and the
471 second number in a range is less than or equal to the first then the range
472 represents all messages in the group after the first message number.
473 .Sp
474 \&\fBNOTE\fR For compatibility reasons only with earlier versions of Net::NNTP
475 a message spec can be passed as a list of two numbers, this is deprecated
476 and a reference to the list should now be passed
477 .ie n .IP $pattern 4
478 .el .IP \f(CW$pattern\fR 4
479 .IX Item "$pattern"
480 The \f(CW\*(C`NNTP\*(C'\fR protocol uses the \f(CW\*(C`WILDMAT\*(C'\fR format for patterns.
481 The WILDMAT format was first developed by Rich Salz based on
482 the format used in the UNIX "find" command to articulate
483 file names. It was developed to provide a uniform mechanism
484 for matching patterns in the same manner that the UNIX shell
485 matches filenames.
486 .Sp
487 Patterns are implicitly anchored at the
488 beginning and end of each string when testing for a match.
489 .Sp
490 There are five pattern matching operations other than a strict
491 one-to-one match between the pattern and the source to be
492 checked for a match.
493 .Sp
494 The first is an asterisk \f(CW\*(C`*\*(C'\fR to match any sequence of zero or more
495 characters.
496 .Sp
497 The second is a question mark \f(CW\*(C`?\*(C'\fR to match any single character. The
498 third specifies a specific set of characters.
499 .Sp
500 The set is specified as a list of characters, or as a range of characters
501 where the beginning and end of the range are separated by a minus (or dash)
502 character, or as any combination of lists and ranges. The dash can
503 also be included in the set as a character it if is the beginning
504 or end of the set. This set is enclosed in square brackets. The
505 close square bracket \f(CW\*(C`]\*(C'\fR may be used in a set if it is the first
506 character in the set.
507 .Sp
508 The fourth operation is the same as the
509 logical not of the third operation and is specified the same
510 way as the third with the addition of a caret character \f(CW\*(C`^\*(C'\fR at
511 the beginning of the test string just inside the open square
512 bracket.
513 .Sp
514 The final operation uses the backslash character to
515 invalidate the special meaning of an open square bracket \f(CW\*(C`[\*(C'\fR,
516 the asterisk, backslash or the question mark. Two backslashes in
517 sequence will result in the evaluation of the backslash as a
518 character with no special meaning.
519 .RS 4
520 .IP Examples 4
521 .IX Item "Examples"
522 .PD 0
523 .ie n .IP """[^]\-]""" 4
524 .el .IP \f(CW[^]\-]\fR 4
525 .IX Item "[^]-]"
526 .PD
527 matches any single character other than a close square
528 bracket or a minus sign/dash.
529 .ie n .IP *bdc 4
530 .el .IP \f(CW*bdc\fR 4
531 .IX Item "*bdc"
532 matches any string that ends with the string "bdc"
533 including the string "bdc" (without quotes).
534 .ie n .IP """[0\-9a\-zA\-Z]""" 4
535 .el .IP \f(CW[0\-9a\-zA\-Z]\fR 4
536 .IX Item "[0-9a-zA-Z]"
537 matches any single printable alphanumeric ASCII character.
538 .ie n .IP """a??d""" 4
539 .el .IP \f(CWa??d\fR 4
540 .IX Item "a??d"
541 matches any four character string which begins
542 with a and ends with d.
543 .RE
544 .RS 4
545 .RE
546 .SH EXPORTS
547 .IX Header "EXPORTS"
548 \&\fINone\fR.
549 .SH "KNOWN BUGS"
550 .IX Header "KNOWN BUGS"
551 See <https://rt.cpan.org/Dist/Display.html?Status=Active&Queue=libnet>.
552 .SH "SEE ALSO"
553 .IX Header "SEE ALSO"
554 Net::Cmd,
555 IO::Socket::SSL.
556 .SH AUTHOR
557 .IX Header "AUTHOR"
558 Graham Barr <[email protected] <mailto:[email protected]>>.
559 .PP
560 Steve Hay <[email protected] <mailto:[email protected]>> is now maintaining
561 libnet as of version 1.22_02.
562 .SH COPYRIGHT
563 .IX Header "COPYRIGHT"
564 Copyright (C) 1995\-1997 Graham Barr. All rights reserved.
565 .PP
566 Copyright (C) 2013\-2016, 2020 Steve Hay. All rights reserved.
567 .SH LICENCE
568 .IX Header "LICENCE"
569 This module is free software; you can redistribute it and/or modify it under the
570 same terms as Perl itself, i.e. under the terms of either the GNU General Public
571 License or the Artistic License, as specified in the \fILICENCE\fR file.
572 .SH VERSION
573 .IX Header "VERSION"
574 Version 3.15
575 .SH DATE
576 .IX Header "DATE"
577 20 March 2023
578 .SH HISTORY
579 .IX Header "HISTORY"
580 See the \fIChanges\fR file.