Debian Codegraph @

upstream/opensuse-tumbleweed/man3/Net::NNTP.3pm

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