Debian Codegraph @

upstream/mageia-cauldron/man1/perl.1

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 "PERL 1"
61 .TH PERL 1 2025-06-24 "perl v5.42.0" "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 perl \- The Perl 5 language interpreter
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 \&\fBperl\fR [\ \fB\-sTtuUWX\fR\ ]
71 [\ \fB\-hv\fR\ ]\ [\ \fB\-V\fR[:\fIconfigvar\fR]\ ]
72 [\ \fB\-cw\fR\ ]\ [\ \fB\-d\fR[\fBt\fR][:\fIdebugger\fR]\ ]\ [\ \fB\-D\fR[\fInumber/list\fR]\ ]
73 [\ \fB\-pna\fR\ ]\ [\ \fB\-F\fR\fIpattern\fR\ ]\ [\ \fB\-l\fR[\fIoctal\fR]\ ]\ [\ \fB\-0\fR[\fIoctal/hexadecimal\fR]\ ]
74 [\ \fB\-I\fR\fIdir\fR\ ]\ [\ \fB\-m\fR[\fB\-\fR]\fImodule\fR\ ]\ [\ \fB\-M\fR[\fB\-\fR]\fI\*(Aqmodule...\*(Aq\fR\ ]\ [\ \fB\-f\fR\ ]
75 [\ \fB\-C\ [\fR\f(BInumber/list\fR\fB]\ \fR]
76 [\ \fB\-S\fR\ ]
77 [\ \fB\-x\fR[\fIdir\fR]\ ]
78 [\ \fB\-i\fR[\fIextension\fR]\ ]
79 [\ [\fB\-e\fR|\fB\-E\fR]\ \fI\*(Aqcommand\*(Aq\fR\ ]\ [\ \fB\-\-\fR\ ]\ [\ \fIprogramfile\fR\ ]\ [\ \fIargument\fR\ ]...
80 .PP
81 For more information on these options, you can run \f(CW\*(C`perldoc perlrun\*(C'\fR.
82 .SH "GETTING HELP"
83 .IX Header "GETTING HELP"
84 The \fIperldoc\fR program gives you access to all the documentation that comes
85 with Perl. You can get more documentation, tutorials and community support
86 online at <https://www.perl.org/>.
87 .PP
88 If you\*(Aqre new to Perl, you should start by running \f(CW\*(C`perldoc perlintro\*(C'\fR,
89 which is a general intro for beginners and provides some background to help
90 you navigate the rest of Perl\*(Aqs extensive documentation. Run \f(CW\*(C`perldoc
91 perldoc\*(C'\fR to learn more things you can do with \fIperldoc\fR.
92 .PP
93 For ease of access, the Perl manual has been split up into several sections.
94 .SS Overview
95 .IX Subsection "Overview"
96 .Vb 4
97 \& perl Perl overview (this section)
98 \& perlintro Perl introduction for beginners
99 \& perlrun Perl execution and options
100 \& perltoc Perl documentation table of contents
101 .Ve
102 .SS Tutorials
103 .IX Subsection "Tutorials"
104 .Vb 3
105 \& perlreftut Perl references short introduction
106 \& perldsc Perl data structures intro
107 \& perllol Perl data structures: arrays of arrays
108 \&
109 \& perlrequick Perl regular expressions quick start
110 \& perlretut Perl regular expressions tutorial
111 \&
112 \& perlootut Perl OO tutorial for beginners
113 \&
114 \& perlperf Perl Performance and Optimization Techniques
115 \&
116 \& perlstyle Perl style guide
117 \&
118 \& perlcheat Perl cheat sheet
119 \& perltrap Perl traps for the unwary
120 \& perldebtut Perl debugging tutorial
121 \&
122 \& perlfaq Perl frequently asked questions
123 \& perlfaq1 General Questions About Perl
124 \& perlfaq2 Obtaining and Learning about Perl
125 \& perlfaq3 Programming Tools
126 \& perlfaq4 Data Manipulation
127 \& perlfaq5 Files and Formats
128 \& perlfaq6 Regexes
129 \& perlfaq7 Perl Language Issues
130 \& perlfaq8 System Interaction
131 \& perlfaq9 Networking
132 .Ve
133 .SS "Reference Manual"
134 .IX Subsection "Reference Manual"
135 .Vb 10
136 \& perlsyn Perl syntax: declarations, statements, comments
137 \& perldata Perl data structures
138 \& perlop Perl expressions: operators, precedence, string literals
139 \& perlsub Perl subroutines
140 \& perlfunc Perl built\-in functions
141 \& perlopentut Perl open() tutorial
142 \& perlpacktut Perl pack() and unpack() tutorial
143 \& perlpod Perl plain old documentation
144 \& perlpodspec Perl plain old documentation format specification
145 \& perldocstyle Perl style guide for core docs
146 \& perlpodstyle Perl POD style guide
147 \& perldiag Perl diagnostic messages
148 \& perldeprecation Perl deprecations
149 \& perllexwarn Perl warnings and their control
150 \& perldebug Perl debugging
151 \& perlvar Perl predefined variables
152 \& perlre Perl regular expressions, the rest of the story
153 \& perlrebackslash Perl regular expression backslash sequences
154 \& perlrecharclass Perl regular expression character classes
155 \& perlreref Perl regular expressions quick reference
156 \& perlref Perl references, the rest of the story
157 \& perlform Perl formats
158 \& perlobj Perl objects
159 \& perltie Perl objects hidden behind simple variables
160 \& perldbmfilter Perl DBM filters
161 \& perlclass Perl class syntax
162 \&
163 \& perlipc Perl interprocess communication
164 \& perlfork Perl fork() information
165 \& perlnumber Perl number semantics
166 \&
167 \& perlthrtut Perl threads tutorial
168 \&
169 \& perlport Perl portability guide
170 \& perllocale Perl locale support
171 \& perluniintro Perl Unicode introduction
172 \& perlunicode Perl Unicode support
173 \& perlunicook Perl Unicode cookbook
174 \& perlunifaq Perl Unicode FAQ
175 \& perluniprops Index of Unicode properties in Perl
176 \& perlunitut Perl Unicode tutorial
177 \& perlebcdic Considerations for running Perl on EBCDIC platforms
178 \&
179 \& perlsec Perl security
180 \& perlsecpolicy Perl security report handling policy
181 \&
182 \& perlmod Perl modules: how they work
183 \& perlmodlib Perl modules: how to write and use
184 \& perlmodstyle Perl modules: how to write modules with style
185 \& perlmodinstall Perl modules: how to install from CPAN
186 \& perlnewmod Perl modules: preparing a new module for distribution
187 \& perlpragma Perl modules: writing a user pragma
188 \&
189 \& perlutil utilities packaged with the Perl distribution
190 \&
191 \& perlfilter Perl source filters
192 \&
193 \& perldtrace Perl\*(Aqs support for DTrace
194 \&
195 \& perlglossary Perl Glossary
196 .Ve
197 .SS "Internals and C Language Interface"
198 .IX Subsection "Internals and C Language Interface"
199 .Vb 12
200 \& perlembed Perl ways to embed perl in your C or C++ application
201 \& perldebguts Perl debugging guts and tips
202 \& perlxstut Perl XS tutorial
203 \& perlxs Perl XS application programming interface
204 \& perlxstypemap Perl XS C/Perl type conversion tools
205 \& perlclib Interacting with standard C library functions
206 \& perlguts Perl internal functions for those doing extensions
207 \& perlcall Perl calling conventions from C
208 \& perlmroapi Perl method resolution plugin interface
209 \& perlreapi Perl regular expression plugin interface
210 \& perlreguts Perl regular expression engine internals
211 \& perlclassguts Internals of class syntax
212 \&
213 \& perlapi Perl API listing (autogenerated)
214 \& perlintern Perl internal functions (autogenerated)
215 \& perliol C API for Perl\*(Aqs implementation of IO in Layers
216 \& perlapio Perl internal IO abstraction interface
217 \&
218 \& perlhack Perl hackers guide
219 \& perlsource Guide to the Perl source tree
220 \& perlinterp Overview of the Perl interpreter source and how it works
221 \& perlhacktut Walk through the creation of a simple C code patch
222 \& perlhacktips Tips for Perl core C code hacking
223 \& perlpolicy Perl development policies
224 \& perlgov Perl Rules of Governance
225 \& perlgit Using git with the Perl repository
226 .Ve
227 .SS History
228 .IX Subsection "History"
229 .Vb 10
230 \& perlhist Perl history records
231 \& perldelta Perl changes since previous version
232 \& perl5420delta Perl changes in version 5.42.0
233 \& perl5402delta Perl changes in version 5.40.2
234 \& perl5401delta Perl changes in version 5.40.1
235 \& perl5400delta Perl changes in version 5.40.0
236 \& perl5384delta Perl changes in version 5.38.4
237 \& perl5383delta Perl changes in version 5.38.3
238 \& perl5382delta Perl changes in version 5.38.2
239 \& perl5381delta Perl changes in version 5.38.1
240 \& perl5380delta Perl changes in version 5.38.0
241 \& perl5363delta Perl changes in version 5.36.3
242 \& perl5362delta Perl changes in version 5.36.2
243 \& perl5361delta Perl changes in version 5.36.1
244 \& perl5360delta Perl changes in version 5.36.0
245 \& perl5343delta Perl changes in version 5.34.3
246 \& perl5342delta Perl changes in version 5.34.2
247 \& perl5341delta Perl changes in version 5.34.1
248 \& perl5340delta Perl changes in version 5.34.0
249 \& perl5321delta Perl changes in version 5.32.1
250 \& perl5320delta Perl changes in version 5.32.0
251 \& perl5303delta Perl changes in version 5.30.3
252 \& perl5302delta Perl changes in version 5.30.2
253 \& perl5301delta Perl changes in version 5.30.1
254 \& perl5300delta Perl changes in version 5.30.0
255 \& perl5283delta Perl changes in version 5.28.3
256 \& perl5282delta Perl changes in version 5.28.2
257 \& perl5281delta Perl changes in version 5.28.1
258 \& perl5280delta Perl changes in version 5.28.0
259 \& perl5263delta Perl changes in version 5.26.3
260 \& perl5262delta Perl changes in version 5.26.2
261 \& perl5261delta Perl changes in version 5.26.1
262 \& perl5260delta Perl changes in version 5.26.0
263 \& perl5244delta Perl changes in version 5.24.4
264 \& perl5243delta Perl changes in version 5.24.3
265 \& perl5242delta Perl changes in version 5.24.2
266 \& perl5241delta Perl changes in version 5.24.1
267 \& perl5240delta Perl changes in version 5.24.0
268 \& perl5224delta Perl changes in version 5.22.4
269 \& perl5223delta Perl changes in version 5.22.3
270 \& perl5222delta Perl changes in version 5.22.2
271 \& perl5221delta Perl changes in version 5.22.1
272 \& perl5220delta Perl changes in version 5.22.0
273 \& perl5203delta Perl changes in version 5.20.3
274 \& perl5202delta Perl changes in version 5.20.2
275 \& perl5201delta Perl changes in version 5.20.1
276 \& perl5200delta Perl changes in version 5.20.0
277 \& perl5184delta Perl changes in version 5.18.4
278 \& perl5182delta Perl changes in version 5.18.2
279 \& perl5181delta Perl changes in version 5.18.1
280 \& perl5180delta Perl changes in version 5.18.0
281 \& perl5163delta Perl changes in version 5.16.3
282 \& perl5162delta Perl changes in version 5.16.2
283 \& perl5161delta Perl changes in version 5.16.1
284 \& perl5160delta Perl changes in version 5.16.0
285 \& perl5144delta Perl changes in version 5.14.4
286 \& perl5143delta Perl changes in version 5.14.3
287 \& perl5142delta Perl changes in version 5.14.2
288 \& perl5141delta Perl changes in version 5.14.1
289 \& perl5140delta Perl changes in version 5.14.0
290 \& perl5125delta Perl changes in version 5.12.5
291 \& perl5124delta Perl changes in version 5.12.4
292 \& perl5123delta Perl changes in version 5.12.3
293 \& perl5122delta Perl changes in version 5.12.2
294 \& perl5121delta Perl changes in version 5.12.1
295 \& perl5120delta Perl changes in version 5.12.0
296 \& perl5101delta Perl changes in version 5.10.1
297 \& perl5100delta Perl changes in version 5.10.0
298 \& perl589delta Perl changes in version 5.8.9
299 \& perl588delta Perl changes in version 5.8.8
300 \& perl587delta Perl changes in version 5.8.7
301 \& perl586delta Perl changes in version 5.8.6
302 \& perl585delta Perl changes in version 5.8.5
303 \& perl584delta Perl changes in version 5.8.4
304 \& perl583delta Perl changes in version 5.8.3
305 \& perl582delta Perl changes in version 5.8.2
306 \& perl581delta Perl changes in version 5.8.1
307 \& perl58delta Perl changes in version 5.8.0
308 \& perl561delta Perl changes in version 5.6.1
309 \& perl56delta Perl changes in version 5.6
310 \& perl5005delta Perl changes in version 5.005
311 \& perl5004delta Perl changes in version 5.004
312 .Ve
313 .SS Miscellaneous
314 .IX Subsection "Miscellaneous"
315 .Vb 2
316 \& perlbook Perl book information
317 \& perlcommunity Perl community information
318 \&
319 \& perldoc Look up Perl documentation in Pod format
320 \&
321 \& perlexperiment A listing of experimental features in Perl
322 \&
323 \& perlartistic Perl Artistic License
324 \& perlgpl GNU General Public License
325 .Ve
326 .SS Language\-Specific
327 .IX Subsection "Language-Specific"
328 .Vb 4
329 \& perlcn Perl for Simplified Chinese (in UTF\-8)
330 \& perljp Perl for Japanese (in EUC\-JP)
331 \& perlko Perl for Korean (in EUC\-KR)
332 \& perltw Perl for Traditional Chinese (in Big5)
333 .Ve
334 .SS Platform\-Specific
335 .IX Subsection "Platform-Specific"
336 .Vb 10
337 \& perlaix Perl notes for AIX
338 \& perlamiga Perl notes for AmigaOS
339 \& perlandroid Perl notes for Android
340 \& perlbs2000 Perl notes for POSIX\-BC BS2000
341 \& perlcygwin Perl notes for Cygwin
342 \& perlfreebsd Perl notes for FreeBSD
343 \& perlhaiku Perl notes for Haiku
344 \& perlhpux Perl notes for HP\-UX
345 \& perlhurd Perl notes for Hurd
346 \& perlirix Perl notes for Irix
347 \& perllinux Perl notes for Linux
348 \& perlmacosx Perl notes for Mac OS X
349 \& perlopenbsd Perl notes for OpenBSD
350 \& perlos2 Perl notes for OS/2
351 \& perlos390 Perl notes for OS/390
352 \& perlos400 Perl notes for OS/400
353 \& perlplan9 Perl notes for Plan 9
354 \& perlqnx Perl notes for QNX
355 \& perlriscos Perl notes for RISC OS
356 \& perlsolaris Perl notes for Solaris
357 \& perlsynology Perl notes for Synology
358 \& perltru64 Perl notes for Tru64
359 \& perlvms Perl notes for VMS
360 \& perlvos Perl notes for Stratus VOS
361 \& perlwin32 Perl notes for Windows
362 .Ve
363 .SS "Stubs for Deleted Documents"
364 .IX Subsection "Stubs for Deleted Documents"
365 .Vb 6
366 \& perlboot
367 \& perlbot
368 \& perlrepository
369 \& perltodo
370 \& perltooc
371 \& perltoot
372 .Ve
373 .PP
374 On a Unix\-like system, these documentation files will usually also be
375 available as manpages for use with the \fIman\fR program.
376 .PP
377 Some documentation is not available as man pages, so if a
378 cross\-reference is not found by man, try it with perldoc. Perldoc can
379 also take you directly to documentation for functions (with the \fB\-f\fR
380 switch). See \f(CW\*(C`perldoc\ \-\-help\*(C'\fR (or \f(CW\*(C`perldoc\ perldoc\*(C'\fR or
381 \&\f(CW\*(C`man\ perldoc\*(C'\fR) for other helpful options perldoc has to offer.
382 .PP
383 In general, if something strange has gone wrong with your program and you\*(Aqre
384 not sure where you should look for help, try making your code comply with
385 \&\fBuse strict\fR and \fBuse warnings\fR. These will often point out exactly
386 where the trouble is.
387 .SH DESCRIPTION
388 .IX Header "DESCRIPTION"
389 Perl officially stands for Practical Extraction and Report Language,
390 except when it doesn\*(Aqt.
391 .PP
392 Perl was originally a language optimized for scanning arbitrary
393 text files, extracting information from those text files, and printing
394 reports based on that information. It quickly became a good language
395 for many system management tasks. Over the years, Perl has grown into
396 a general\-purpose programming language. It\*(Aqs widely used for everything
397 from quick "one\-liners" to full\-scale application development.
398 .PP
399 The language is intended to be practical (easy to use, efficient,
400 complete) rather than beautiful (tiny, elegant, minimal). It combines
401 (in the author\*(Aqs opinion, anyway) some of the best features of \fBsed\fR,
402 \&\fBawk\fR, and \fBsh\fR, making it familiar and easy to use for Unix users to
403 whip up quick solutions to annoying problems. Its general\-purpose
404 programming facilities support procedural, functional, and
405 object\-oriented programming paradigms, making Perl a comfortable
406 language for the long haul on major projects, whatever your bent.
407 .PP
408 Perl\*(Aqs roots in text processing haven\*(Aqt been forgotten over the years.
409 It still boasts some of the most powerful regular expressions to be
410 found anywhere, and its support for Unicode text is world\-class. It
411 handles all kinds of structured text, too, through an extensive
412 collection of extensions. Those libraries, collected in the CPAN,
413 provide ready\-made solutions to an astounding array of problems. When
414 they haven\*(Aqt set the standard themselves, they steal from the best
415 \&\-\- just like Perl itself.
416 .SH AVAILABILITY
417 .IX Header "AVAILABILITY"
418 Perl is available for most operating systems, including virtually
419 all Unix\-like platforms. See "Supported Platforms" in perlport
420 for a listing.
421 .SH ENVIRONMENT
422 .IX Header "ENVIRONMENT"
423 See "ENVIRONMENT" in perlrun.
424 .SH AUTHOR
425 .IX Header "AUTHOR"
426 Larry Wall <[email protected]>, with the help of oodles of other folks.
427 .PP
428 If your Perl success stories and testimonials may be of help to others
429 who wish to advocate the use of Perl in their applications,
430 or if you wish to simply express your gratitude to Larry and the
431 Perl developers, please write to perl\[email protected] .
432 .SH FILES
433 .IX Header "FILES"
434 .Vb 1
435 \& "@INC" locations of perl libraries
436 .Ve
437 .PP
438 "@INC" above is a reference to the built\-in variable of the same name;
439 see perlvar for more information.
440 .SH "SEE ALSO"
441 .IX Header "SEE ALSO"
442 .IP <https://www.perl.org/> 4
443 .IX Item "<https://www.perl.org/>"
444 the Perl homepage
445 .IP <https://www.perl.com/> 4
446 .IX Item "<https://www.perl.com/>"
447 Perl articles
448 .IP <https://www.cpan.org/> 4
449 .IX Item "<https://www.cpan.org/>"
450 the Comprehensive Perl Archive
451 .IP <https://www.pm.org/> 4
452 .IX Item "<https://www.pm.org/>"
453 the Perl Mongers
454 .SH DIAGNOSTICS
455 .IX Header "DIAGNOSTICS"
456 Using the \f(CW\*(C`use strict\*(C'\fR pragma ensures that all variables are properly
457 declared and prevents other misuses of legacy Perl features.
458 These are enabled by default within the scope of
459 \&\f(CW\*(C`use v5.12\*(C'\fR (or higher).
460 .PP
461 The \f(CW\*(C`use warnings\*(C'\fR pragma produces some lovely diagnostics.
462 It is enabled by default when you say \f(CW\*(C`use v5.35\*(C'\fR (or higher).
463 One can also use the \fB\-w\fR flag, but its use is normally discouraged,
464 because it gets applied to all executed Perl code, including that not under
465 your control.
466 .PP
467 See perldiag for explanations of all Perl\*(Aqs diagnostics. The \f(CW\*(C`use
468 diagnostics\*(C'\fR pragma automatically turns Perl\*(Aqs normally terse warnings
469 and errors into these longer forms.
470 .PP
471 Compilation errors will tell you the line number of the error, with an
472 indication of the next token or token type that was to be examined.
473 (In a script passed to Perl via \fB\-e\fR switches, each
474 \&\fB\-e\fR is counted as one line.)
475 .PP
476 Setuid scripts have additional constraints that can produce error
477 messages such as "Insecure dependency". See perlsec.
478 .PP
479 Did we mention that you should definitely consider using the \fBuse warnings\fR
480 pragma?
481 .SH BUGS
482 .IX Header "BUGS"
483 The behavior implied by the \fBuse warnings\fR pragma is not mandatory.
484 .PP
485 Perl is at the mercy of your machine\*(Aqs definitions of various
486 operations such as type casting, \fBatof()\fR, and floating\-point
487 output with \fBsprintf()\fR.
488 .PP
489 If your stdio requires a seek or eof between reads and writes on a
490 particular stream, so does Perl. (This doesn\*(Aqt apply to \fBsysread()\fR
491 and \fBsyswrite()\fR.)
492 .PP
493 While none of the built\-in data types have any arbitrary size limits
494 (apart from memory size), there are still a few arbitrary limits: a
495 given variable name may not be longer than 251 characters. Line numbers
496 displayed by diagnostics are internally stored as short integers,
497 so they are limited to a maximum of 65535 (higher numbers usually being
498 affected by wraparound).
499 .PP
500 You may submit your bug reports (be sure to include full configuration
501 information as output by the myconfig program in the perl source
502 tree, or by \f(CW\*(C`perl \-V\*(C'\fR) to <https://github.com/Perl/perl5/issues>.
503 .PP
504 Perl actually stands for Pathologically Eclectic Rubbish Lister, but
505 don\*(Aqt tell anyone I said that.
506 .SH NOTES
507 .IX Header "NOTES"
508 The Perl motto is "There\*(Aqs more than one way to do it." Divining
509 how many more is left as an exercise to the reader.
510 .PP
511 The three principal virtues of a programmer are Laziness,
512 Impatience, and Hubris. See the Camel Book for why.