Debian Codegraph @

upstream/debian-unstable/man1/perl.1

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 "PERL 1"
58 .TH PERL 1 2026-04-10 "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 perl \- The Perl 5 language interpreter
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 \&\fBperl\fR [\ \fB\-sTtuUWX\fR\ ]
68 [\ \fB\-hv\fR\ ]\ [\ \fB\-V\fR[:\fIconfigvar\fR]\ ]
69 [\ \fB\-cw\fR\ ]\ [\ \fB\-d\fR[\fBt\fR][:\fIdebugger\fR]\ ]\ [\ \fB\-D\fR[\fInumber/list\fR]\ ]
70 [\ \fB\-pna\fR\ ]\ [\ \fB\-F\fR\fIpattern\fR\ ]\ [\ \fB\-l\fR[\fIoctal\fR]\ ]\ [\ \fB\-0\fR[\fIoctal/hexadecimal\fR]\ ]
71 [\ \fB\-I\fR\fIdir\fR\ ]\ [\ \fB\-m\fR[\fB\-\fR]\fImodule\fR\ ]\ [\ \fB\-M\fR[\fB\-\fR]\fI'module...'\fR\ ]\ [\ \fB\-f\fR\ ]
72 [\ \fB\-C\ [\fR\f(BInumber/list\fR\fB]\ \fR]
73 [\ \fB\-S\fR\ ]
74 [\ \fB\-x\fR[\fIdir\fR]\ ]
75 [\ \fB\-i\fR[\fIextension\fR]\ ]
76 [\ [\fB\-e\fR|\fB\-E\fR]\ \fI'command'\fR\ ]\ [\ \fB\-\-\fR\ ]\ [\ \fIprogramfile\fR\ ]\ [\ \fIargument\fR\ ]...
77 .PP
78 For more information on these options, you can run \f(CW\*(C`perldoc perlrun\*(C'\fR.
79 .SH "GETTING HELP"
80 .IX Header "GETTING HELP"
81 The \fIperldoc\fR program gives you access to all the documentation that comes
82 with Perl. You can get more documentation, tutorials and community support
83 online at <https://www.perl.org/>.
84 .PP
85 If you're new to Perl, you should start by running \f(CW\*(C`perldoc perlintro\*(C'\fR,
86 which is a general intro for beginners and provides some background to help
87 you navigate the rest of Perl's extensive documentation. Run \f(CW\*(C`perldoc
88 perldoc\*(C'\fR to learn more things you can do with \fIperldoc\fR.
89 .PP
90 For ease of access, the Perl manual has been split up into several sections.
91 .SS Overview
92 .IX Subsection "Overview"
93 .Vb 4
94 \& perl Perl overview (this section)
95 \& perlintro Perl introduction for beginners
96 \& perlrun Perl execution and options
97 \& perltoc Perl documentation table of contents
98 .Ve
99 .SS Tutorials
100 .IX Subsection "Tutorials"
101 .Vb 3
102 \& perlreftut Perl references short introduction
103 \& perldsc Perl data structures intro
104 \& perllol Perl data structures: arrays of arrays
105 \&
106 \& perlrequick Perl regular expressions quick start
107 \& perlretut Perl regular expressions tutorial
108 \&
109 \& perlootut Perl OO tutorial for beginners
110 \&
111 \& perlperf Perl Performance and Optimization Techniques
112 \&
113 \& perlstyle Perl style guide
114 \&
115 \& perlcheat Perl cheat sheet
116 \& perltrap Perl traps for the unwary
117 \& perldebtut Perl debugging tutorial
118 \&
119 \& perlfaq Perl frequently asked questions
120 \& perlfaq1 General Questions About Perl
121 \& perlfaq2 Obtaining and Learning about Perl
122 \& perlfaq3 Programming Tools
123 \& perlfaq4 Data Manipulation
124 \& perlfaq5 Files and Formats
125 \& perlfaq6 Regexes
126 \& perlfaq7 Perl Language Issues
127 \& perlfaq8 System Interaction
128 \& perlfaq9 Networking
129 .Ve
130 .SS "Reference Manual"
131 .IX Subsection "Reference Manual"
132 .Vb 10
133 \& perlsyn Perl syntax: declarations, statements, comments
134 \& perldata Perl data structures
135 \& perlop Perl expressions: operators, precedence, string literals
136 \& perlsub Perl subroutines
137 \& perlfunc Perl built\-in functions
138 \& perlopentut Perl open() tutorial
139 \& perlpacktut Perl pack() and unpack() tutorial
140 \& perlpod Perl plain old documentation
141 \& perlpodspec Perl plain old documentation format specification
142 \& perldocstyle Perl style guide for core docs
143 \& perlpodstyle Perl POD style guide
144 \& perldiag Perl diagnostic messages
145 \& perldeprecation Perl deprecations
146 \& perllexwarn Perl warnings and their control
147 \& perldebug Perl debugging
148 \& perlvar Perl predefined variables
149 \& perlre Perl regular expressions, the rest of the story
150 \& perlrebackslash Perl regular expression backslash sequences
151 \& perlrecharclass Perl regular expression character classes
152 \& perlreref Perl regular expressions quick reference
153 \& perlref Perl references, the rest of the story
154 \& perlform Perl formats
155 \& perlobj Perl objects
156 \& perltie Perl objects hidden behind simple variables
157 \& perldbmfilter Perl DBM filters
158 \& perlclass Perl class syntax
159 \&
160 \& perlipc Perl interprocess communication
161 \& perlfork Perl fork() information
162 \& perlnumber Perl number semantics
163 \&
164 \& perlthrtut Perl threads tutorial
165 \&
166 \& perlport Perl portability guide
167 \& perllocale Perl locale support
168 \& perluniintro Perl Unicode introduction
169 \& perlunicode Perl Unicode support
170 \& perlunicook Perl Unicode cookbook
171 \& perlunifaq Perl Unicode FAQ
172 \& perluniprops Index of Unicode properties in Perl
173 \& perlunitut Perl Unicode tutorial
174 \& perlebcdic Considerations for running Perl on EBCDIC platforms
175 \&
176 \& perlsec Perl security
177 \& perlsecpolicy Perl security report handling policy
178 \&
179 \& perlmod Perl modules: how they work
180 \& perlmodlib Perl modules: how to write and use
181 \& perlmodstyle Perl modules: how to write modules with style
182 \& perlmodinstall Perl modules: how to install from CPAN
183 \& perlnewmod Perl modules: preparing a new module for distribution
184 \& perlpragma Perl modules: writing a user pragma
185 \&
186 \& perlutil utilities packaged with the Perl distribution
187 \&
188 \& perlfilter Perl source filters
189 \&
190 \& perldtrace Perl\*(Aqs support for DTrace
191 \&
192 \& perlglossary Perl Glossary
193 .Ve
194 .SS "Internals and C Language Interface"
195 .IX Subsection "Internals and C Language Interface"
196 .Vb 12
197 \& perlembed Perl ways to embed perl in your C or C++ application
198 \& perldebguts Perl debugging guts and tips
199 \& perlxstut Perl XS tutorial
200 \& perlxs Perl XS application programming interface
201 \& perlxstypemap Perl XS C/Perl type conversion tools
202 \& perlclib Interacting with standard C library functions
203 \& perlguts Perl internal functions for those doing extensions
204 \& perlcall Perl calling conventions from C
205 \& perlmroapi Perl method resolution plugin interface
206 \& perlreapi Perl regular expression plugin interface
207 \& perlreguts Perl regular expression engine internals
208 \& perlclassguts Internals of class syntax
209 \&
210 \& perlapi Perl API listing (autogenerated)
211 \& perlintern Perl internal functions (autogenerated)
212 \& perliol C API for Perl\*(Aqs implementation of IO in Layers
213 \& perlapio Perl internal IO abstraction interface
214 \&
215 \& perlhack Perl hackers guide
216 \& perlsource Guide to the Perl source tree
217 \& perlinterp Overview of the Perl interpreter source and how it works
218 \& perlhacktut Walk through the creation of a simple C code patch
219 \& perlhacktips Tips for Perl core C code hacking
220 \& perlpolicy Perl development policies
221 \& perlgov Perl Rules of Governance
222 \& perlgit Using git with the Perl repository
223 .Ve
224 .SS History
225 .IX Subsection "History"
226 .Vb 10
227 \& perlhist Perl history records
228 \& perldelta Perl changes since previous version
229 \& perl5400delta Perl changes in version 5.40.0
230 \& perl5382delta Perl changes in version 5.38.2
231 \& perl5381delta Perl changes in version 5.38.1
232 \& perl5380delta Perl changes in version 5.38.0
233 \& perl5363delta Perl changes in version 5.36.3
234 \& perl5362delta Perl changes in version 5.36.2
235 \& perl5361delta Perl changes in version 5.36.1
236 \& perl5360delta Perl changes in version 5.36.0
237 \& perl5343delta Perl changes in version 5.34.3
238 \& perl5342delta Perl changes in version 5.34.2
239 \& perl5341delta Perl changes in version 5.34.1
240 \& perl5340delta Perl changes in version 5.34.0
241 \& perl5321delta Perl changes in version 5.32.1
242 \& perl5320delta Perl changes in version 5.32.0
243 \& perl5303delta Perl changes in version 5.30.3
244 \& perl5302delta Perl changes in version 5.30.2
245 \& perl5301delta Perl changes in version 5.30.1
246 \& perl5300delta Perl changes in version 5.30.0
247 \& perl5283delta Perl changes in version 5.28.3
248 \& perl5282delta Perl changes in version 5.28.2
249 \& perl5281delta Perl changes in version 5.28.1
250 \& perl5280delta Perl changes in version 5.28.0
251 \& perl5263delta Perl changes in version 5.26.3
252 \& perl5262delta Perl changes in version 5.26.2
253 \& perl5261delta Perl changes in version 5.26.1
254 \& perl5260delta Perl changes in version 5.26.0
255 \& perl5244delta Perl changes in version 5.24.4
256 \& perl5243delta Perl changes in version 5.24.3
257 \& perl5242delta Perl changes in version 5.24.2
258 \& perl5241delta Perl changes in version 5.24.1
259 \& perl5240delta Perl changes in version 5.24.0
260 \& perl5224delta Perl changes in version 5.22.4
261 \& perl5223delta Perl changes in version 5.22.3
262 \& perl5222delta Perl changes in version 5.22.2
263 \& perl5221delta Perl changes in version 5.22.1
264 \& perl5220delta Perl changes in version 5.22.0
265 \& perl5203delta Perl changes in version 5.20.3
266 \& perl5202delta Perl changes in version 5.20.2
267 \& perl5201delta Perl changes in version 5.20.1
268 \& perl5200delta Perl changes in version 5.20.0
269 \& perl5184delta Perl changes in version 5.18.4
270 \& perl5182delta Perl changes in version 5.18.2
271 \& perl5181delta Perl changes in version 5.18.1
272 \& perl5180delta Perl changes in version 5.18.0
273 \& perl5163delta Perl changes in version 5.16.3
274 \& perl5162delta Perl changes in version 5.16.2
275 \& perl5161delta Perl changes in version 5.16.1
276 \& perl5160delta Perl changes in version 5.16.0
277 \& perl5144delta Perl changes in version 5.14.4
278 \& perl5143delta Perl changes in version 5.14.3
279 \& perl5142delta Perl changes in version 5.14.2
280 \& perl5141delta Perl changes in version 5.14.1
281 \& perl5140delta Perl changes in version 5.14.0
282 \& perl5125delta Perl changes in version 5.12.5
283 \& perl5124delta Perl changes in version 5.12.4
284 \& perl5123delta Perl changes in version 5.12.3
285 \& perl5122delta Perl changes in version 5.12.2
286 \& perl5121delta Perl changes in version 5.12.1
287 \& perl5120delta Perl changes in version 5.12.0
288 \& perl5101delta Perl changes in version 5.10.1
289 \& perl5100delta Perl changes in version 5.10.0
290 \& perl589delta Perl changes in version 5.8.9
291 \& perl588delta Perl changes in version 5.8.8
292 \& perl587delta Perl changes in version 5.8.7
293 \& perl586delta Perl changes in version 5.8.6
294 \& perl585delta Perl changes in version 5.8.5
295 \& perl584delta Perl changes in version 5.8.4
296 \& perl583delta Perl changes in version 5.8.3
297 \& perl582delta Perl changes in version 5.8.2
298 \& perl581delta Perl changes in version 5.8.1
299 \& perl58delta Perl changes in version 5.8.0
300 \& perl561delta Perl changes in version 5.6.1
301 \& perl56delta Perl changes in version 5.6
302 \& perl5005delta Perl changes in version 5.005
303 \& perl5004delta Perl changes in version 5.004
304 .Ve
305 .SS Miscellaneous
306 .IX Subsection "Miscellaneous"
307 .Vb 2
308 \& perlbook Perl book information
309 \& perlcommunity Perl community information
310 \&
311 \& perldoc Look up Perl documentation in Pod format
312 \&
313 \& perlexperiment A listing of experimental features in Perl
314 \&
315 \& perlartistic Perl Artistic License
316 \& perlgpl GNU General Public License
317 .Ve
318 .SS Language-Specific
319 .IX Subsection "Language-Specific"
320 .Vb 4
321 \& perlcn Perl for Simplified Chinese (in UTF\-8)
322 \& perljp Perl for Japanese (in EUC\-JP)
323 \& perlko Perl for Korean (in EUC\-KR)
324 \& perltw Perl for Traditional Chinese (in Big5)
325 .Ve
326 .SS Platform-Specific
327 .IX Subsection "Platform-Specific"
328 .Vb 10
329 \& perlaix Perl notes for AIX
330 \& perlamiga Perl notes for AmigaOS
331 \& perlandroid Perl notes for Android
332 \& perlbs2000 Perl notes for POSIX\-BC BS2000
333 \& perlcygwin Perl notes for Cygwin
334 \& perlfreebsd Perl notes for FreeBSD
335 \& perlhaiku Perl notes for Haiku
336 \& perlhpux Perl notes for HP\-UX
337 \& perlhurd Perl notes for Hurd
338 \& perlirix Perl notes for Irix
339 \& perllinux Perl notes for Linux
340 \& perlmacosx Perl notes for Mac OS X
341 \& perlopenbsd Perl notes for OpenBSD
342 \& perlos2 Perl notes for OS/2
343 \& perlos390 Perl notes for OS/390
344 \& perlos400 Perl notes for OS/400
345 \& perlplan9 Perl notes for Plan 9
346 \& perlqnx Perl notes for QNX
347 \& perlriscos Perl notes for RISC OS
348 \& perlsolaris Perl notes for Solaris
349 \& perlsynology Perl notes for Synology
350 \& perltru64 Perl notes for Tru64
351 \& perlvms Perl notes for VMS
352 \& perlvos Perl notes for Stratus VOS
353 \& perlwin32 Perl notes for Windows
354 .Ve
355 .SS "Stubs for Deleted Documents"
356 .IX Subsection "Stubs for Deleted Documents"
357 .Vb 6
358 \& perlboot
359 \& perlbot
360 \& perlrepository
361 \& perltodo
362 \& perltooc
363 \& perltoot
364 .Ve
365 .PP
366 On Debian systems, you need to install the \fBperl-doc\fR package which
367 contains the majority of the standard Perl documentation and the
368 \&\fIperldoc\fR program.
369 .PP
370 Extensive additional documentation for Perl modules is available, both
371 those distributed with Perl and third-party modules which are packaged
372 or locally installed.
373 .PP
374 You should be able to view Perl's documentation with your \fBman\fR\|(1)
375 program or \fBperldoc\fR\|(1).
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're
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't.
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's 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's 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's roots in text processing haven't 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't 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's diagnostics. The \f(CW\*(C`use
468 diagnostics\*(C'\fR pragma automatically turns Perl's 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's 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't 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't tell anyone I said that.
506 .SH NOTES
507 .IX Header "NOTES"
508 The Perl motto is "There's 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.