1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>open - perldoc.perl.org</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta http-equiv="Content-Language" content="en-gb">
<link href="../static/css-20090810.css" rel="stylesheet" rev="stylesheet" type="text/css" media="screen">
</head>
<body onLoad="perldoc.startup();" onPageShow="if (event.persisted) perldoc.startup();">
<div id="page">
<div id="header">
<div id="homepage_link">
<a href="../index.html"></a>
</div>
<div id="search_form">
<form action="../search.html" method="GET" id="search">
<input type="text" name="q" id="search_box" alt="Search">
</form>
</div>
</div>
<div id="body">
<div id="left_column">
<div class="side_group">
<div class="side_panel doc_panel">
<p>Manual</p>
<ul>
<li><a href="../index-overview.html">Overview</a>
<li><a href="../index-tutorials.html">Tutorials</a>
<li><a href="../index-faq.html">FAQs</a>
<li><a href="../index-history.html">History / Changes</a>
<li><a href="../index-licence.html">License</a>
</ul>
</div>
<div class="side_panel doc_panel">
<p>Reference</p>
<ul>
<li><a href="../index-language.html">Language</a>
<li><a href="../index-functions.html">Functions</a>
<li><a href="../perlop.html">Operators</a>
<li><a href="../perlvar.html">Special Variables</a>
<li><a href="../index-pragmas.html">Pragmas</a>
<li><a href="../index-utilities.html">Utilities</a>
<li><a href="../index-internals.html">Internals</a></li>
<li><a href="../index-platforms.html">Platform Specific</a>
</ul>
</div>
<div class="side_panel doc_panel">
<p>Modules</p>
<ul>
<li>
<a href="../index-modules-A.html">A</a>
•
<a href="../index-modules-B.html">B</a>
•
<a href="../index-modules-C.html">C</a>
•
<a href="../index-modules-D.html">D</a>
•
<a href="../index-modules-E.html">E</a>
<li>
<a href="../index-modules-F.html">F</a>
•
<a href="../index-modules-G.html">G</a>
•
<a href="../index-modules-H.html">H</a>
•
<a href="../index-modules-I.html">I</a>
•
<a href="../index-modules-L.html">L</a>
<li>
<a href="../index-modules-M.html">M</a>
•
<a href="../index-modules-N.html">N</a>
•
<a href="../index-modules-O.html">O</a>
•
<a href="../index-modules-P.html">P</a>
•
<a href="../index-modules-S.html">S</a>
<li>
<a href="../index-modules-T.html">T</a>
•
<a href="../index-modules-U.html">U</a>
•
<a href="../index-modules-X.html">X</a>
</ul>
</div>
</div>
<div class="side_group">
<div class="side_panel links_panel">
<p>News / Blogs</p>
<ul>
<li><a href="http://perlbuzz.com">Perl Buzz</a></li>
<li><a href="http://ironman.enlightenedperl.org">Perl Iron Man</a></li>
<li><a href="http://perlsphere.net">Perlsphere</a></li>
<li><a href="http://planet.perl.org">Planet Perl</a></li>
<li><a href="http://news.perlfoundation.org/">TPF news</a></li>
<li><a href="http://use.perl.org">Use Perl</a></li>
</ul>
</div>
<div class="side_panel links_panel">
<p>See also</p>
<ul>
<li><a href="http://search.cpan.org">CPAN</a></li>
<li><a href="http://www.perl.org">Perl.org</a></li>
<li><a href="http://www.perl.com">Perl.com</a></li>
<li><a href="http://www.perlfoundation.org/perl5/index.cgi">Perl 5 Wiki</a></li>
<li><a href="http://jobs.perl.org">Perl Jobs</a></li>
<li><a href="http://www.pm.org">Perl Mongers</a></li>
<li><a href="http://www.perlmonks.org">Perl Monks</a></li>
</ul>
</div>
<div class="side_panel links_panel">
<p>Contact</p>
<ul>
<li><a href="http://perl.jonallen.info">Site designed and maintained by Jon Allen (JJ)</a>
<li><a href="http://perl.jonallen.info">http://perl.jonallen.info</a>
</ul>
<ul>
<li><a href="http://perl.jonallen.info/projects/perldoc">View the project page and FAQs</a>
</ul>
</div>
</div>
</div>
<div id="centre_column">
<div id="content_header">
<div id="title_bar">
<div id="page_name">
<h1>open</h1>
</div>
<div id="perl_version">
Perl 5 version 10.1 documentation
</div>
<div id="page_links">
<a href="#" onClick="toolbar.goToTop();return false;">Go to top</a>
</div>
</div>
<div id="breadcrumbs">
<a href="../index.html">Home</a> >
<a href="../index-language.html">Language reference</a> >
<a href="../index-functions.html">Functions</a> >
open
</div>
</div>
<div id="content_body">
<!--[if lt IE 7]>
<div class="noscript">
<p>
<strong>It looks like you're using Internet Explorer 6. This is a very old
browser which does not offer full support for modern websites.</strong>
</p>
<p>
Unfortunately this means that this website will not work on
your computer.
</p>
<p>
Don't miss out though! To view the site (and get a better experience from
many other websites), simply upgrade to
<a href="http://www.microsoft.com/windows/Internet-explorer/default.aspx">Internet
Explorer 8</a>
or download an alternative browser such as
<a href="http://www.mozilla.com/en-US/firefox/firefox.html">Firefox</a>,
<a href="http://www.apple.com/safari/download/">Safari</a>, or
<a href="http://www.google.co.uk/chrome">Google Chrome</a>.
</p>
<p>
All of these browsers are free. If you're using a PC at work, you may
need to contact your IT administrator.
</p>
</div>
<![endif]-->
<noscript>
<div class="noscript">
<p>
<strong>Please note: Many features of this site require JavaScript. You appear to have JavaScript disabled,
or are running a non-JavaScript capable web browser.</strong>
</p>
<p>
To get the best experience, please enable JavaScript or download a modern web browser such as <a href="http://www.microsoft.com/windows/Internet-explorer/default.aspx">Internet Explorer 8</a>, <a href="http://www.mozilla.com/en-US/firefox/firefox.html">Firefox</a>, <a href="http://www.apple.com/safari/download/">Safari</a>, or <a href="http://www.google.co.uk/chrome">Google Chrome</a>.
</p>
</div>
</noscript>
<div id="from_search"></div>
<h1>open</h1>
<div class="mod_az_list">
<a href="../index-functions.html">Perl functions A-Z</a> |
<a href="../index-functions-by-cat.html">Perl functions by category</a> |
<a href="../perlfunc.html">The 'perlfunc' manpage</a>
</div>
<!-- -->
<ul>
<li><a name="open-FILEHANDLE%2cEXPR"></a><b>open FILEHANDLE,EXPR</b>
<p> </p>
</li>
</ul>
<ul>
<li><a name="open-FILEHANDLE%2cMODE%2cEXPR"></a><b>open FILEHANDLE,MODE,EXPR</b>
</li>
<li><a name="open-FILEHANDLE%2cMODE%2cEXPR%2cLIST"></a><b>open FILEHANDLE,MODE,EXPR,LIST</b>
</li>
<li><a name="open-FILEHANDLE%2cMODE%2cREFERENCE"></a><b>open FILEHANDLE,MODE,REFERENCE</b>
</li>
<li><a name="open-FILEHANDLE"></a><b>open FILEHANDLE</b>
<p>Opens the file whose filename is given by EXPR, and associates it with
FILEHANDLE.</p>
<p>Simple examples to open a file for reading:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><a class="l_k" href="../functions/my.html">my</a> <span class="i">$fh</span><span class="cm">,</span> <span class="q">'<'</span><span class="cm">,</span> <span class="q">"input.txt"</span><span class="s">)</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="i">$!</span><span class="sc">;</span></li></ol></pre><p>and for writing:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><a class="l_k" href="../functions/my.html">my</a> <span class="i">$fh</span><span class="cm">,</span> <span class="q">'>'</span><span class="cm">,</span> <span class="q">"output.txt"</span><span class="s">)</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="i">$!</span><span class="sc">;</span></li></ol></pre><p>(The following is a comprehensive reference to open(): for a gentler
introduction you may consider <a href="../perlopentut.html">perlopentut</a>.)</p>
<p>If FILEHANDLE is an undefined scalar variable (or array or hash element)
the variable is assigned a reference to a new anonymous filehandle,
otherwise if FILEHANDLE is an expression, its value is used as the name of
the real filehandle wanted. (This is considered a symbolic reference, so
<code class="inline"><a class="l_k" href="../functions/use.html">use</a> <span class="w">strict</span> <span class="q">'refs'</span></code>
should <i>not</i> be in effect.)</p>
<p>If EXPR is omitted, the scalar variable of the same name as the
FILEHANDLE contains the filename. (Note that lexical variables--those
declared with <code class="inline"><a class="l_k" href="../functions/my.html">my</a></code>--will not work for this purpose; so if you're
using <code class="inline"><a class="l_k" href="../functions/my.html">my</a></code>, specify EXPR in your call to open.)</p>
<p>If three or more arguments are specified then the mode of opening and
the file name are separate. If MODE is <code class="inline"><span class="q">'<'</span></code>
or nothing, the file
is opened for input. If MODE is <code class="inline"><span class="q">'>'</span></code>
, the file is truncated and
opened for output, being created if necessary. If MODE is <code class="inline"><span class="q">'>>'</span></code>
,
the file is opened for appending, again being created if necessary.</p>
<p>You can put a <code class="inline"><span class="q">'+'</span></code>
in front of the <code class="inline"><span class="q">'>'</span></code>
or <code class="inline"><span class="q">'<'</span></code>
to
indicate that you want both read and write access to the file; thus
<code class="inline"><span class="q">'+<'</span></code>
is almost always preferred for read/write updates--the <code class="inline"><span class="q">'+>'</span></code>
mode would clobber the file first. You can't usually use
either read-write mode for updating textfiles, since they have
variable length records. See the <b>-i</b> switch in <a href="../perlrun.html">perlrun</a> for a
better approach. The file is created with permissions of <code class="inline"><span class="n">0666</span></code>
modified by the process' <code class="inline"><a class="l_k" href="../functions/umask.html">umask</a></code> value.</p>
<p>These various prefixes correspond to the fopen(3) modes of <code class="inline"><span class="q">'r'</span></code>
,
<code class="inline"><span class="q">'r+'</span></code>
, <code class="inline"><span class="q">'w'</span></code>
, <code class="inline"><span class="q">'w+'</span></code>
, <code class="inline"><span class="q">'a'</span></code>
, and <code class="inline"><span class="q">'a+'</span></code>
.</p>
<p>In the 2-arguments (and 1-argument) form of the call the mode and
filename should be concatenated (in this order), possibly separated by
spaces. It is possible to omit the mode in these forms if the mode is
<code class="inline"><span class="q">'<'</span></code>
.</p>
<p>If the filename begins with <code class="inline"><span class="q">'|'</span></code>
, the filename is interpreted as a
command to which output is to be piped, and if the filename ends with a
<code class="inline"><span class="q">'|'</span></code>
, the filename is interpreted as a command which pipes output to
us. See <a href="../perlipc.html#Using-open()-for-IPC">"Using open() for IPC" in perlipc</a>
for more examples of this. (You are not allowed to <code class="inline"><a class="l_k" href="../functions/open.html">open</a></code> to a command
that pipes both in <i>and</i> out, but see <a href="../IPC/Open2.html">IPC::Open2</a>, <a href="../IPC/Open3.html">IPC::Open3</a>,
and <a href="../perlipc.html#Bidirectional-Communication-with-Another-Process">"Bidirectional Communication with Another Process" in perlipc</a>
for alternatives.)</p>
<p>For three or more arguments if MODE is <code class="inline"><span class="q">'|-'</span></code>
, the filename is
interpreted as a command to which output is to be piped, and if MODE
is <code class="inline"><span class="q">'-|'</span></code>
, the filename is interpreted as a command which pipes
output to us. In the 2-arguments (and 1-argument) form one should
replace dash (<code class="inline"><span class="q">'-'</span></code>
) with the command.
See <a href="../perlipc.html#Using-open()-for-IPC">"Using open() for IPC" in perlipc</a> for more examples of this.
(You are not allowed to <code class="inline"><a class="l_k" href="../functions/open.html">open</a></code> to a command that pipes both in <i>and</i>
out, but see <a href="../IPC/Open2.html">IPC::Open2</a>, <a href="../IPC/Open3.html">IPC::Open3</a>, and
<a href="../perlipc.html#Bidirectional-Communication">"Bidirectional Communication" in perlipc</a> for alternatives.)</p>
<p>In the three-or-more argument form of pipe opens, if LIST is specified
(extra arguments after the command name) then LIST becomes arguments
to the command invoked if the platform supports it. The meaning of
<code class="inline"><a class="l_k" href="../functions/open.html">open</a></code> with more than three arguments for non-pipe modes is not yet
specified. Experimental "layers" may give extra LIST arguments
meaning.</p>
<p>In the 2-arguments (and 1-argument) form opening <code class="inline"><span class="q">'-'</span></code>
opens STDIN
and opening <code class="inline"><span class="q">'>-'</span></code>
opens STDOUT.</p>
<p>You may use the three-argument form of open to specify IO "layers"
(sometimes also referred to as "disciplines") to be applied to the handle
that affect how the input and output are processed (see <a href="../open.html">open</a> and
<a href="../PerlIO.html">PerlIO</a> for more details). For example</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><a class="l_k" href="../functions/my.html">my</a> <span class="i">$fh</span><span class="cm">,</span> <span class="q">"<:encoding(UTF-8)"</span><span class="cm">,</span> <span class="q">"file"</span><span class="s">)</span></li></ol></pre><p>will open the UTF-8 encoded file containing Unicode characters,
see <a href="../perluniintro.html">perluniintro</a>. Note that if layers are specified in the
three-arg form then default layers stored in ${^OPEN} (see <a href="../perlvar.html">perlvar</a>;
usually set by the <b>open</b> pragma or the switch <b>-CioD</b>) are ignored.</p>
<p>Open returns nonzero upon success, the undefined value otherwise. If
the <code class="inline"><a class="l_k" href="../functions/open.html">open</a></code> involved a pipe, the return value happens to be the pid of
the subprocess.</p>
<p>If you're running Perl on a system that distinguishes between text
files and binary files, then you should check out <a href="../functions/binmode.html">"binmode"</a> for tips
for dealing with this. The key distinction between systems that need
<code class="inline"><a class="l_k" href="../functions/binmode.html">binmode</a></code> and those that don't is their text file formats. Systems
like Unix, Mac OS, and Plan 9, which delimit lines with a single
character, and which encode that character in C as <code class="inline"><span class="q">"\n"</span></code>
, do not
need <code class="inline"><a class="l_k" href="../functions/binmode.html">binmode</a></code>. The rest need it.</p>
<p>When opening a file, it's usually a bad idea to continue normal execution
if the request failed, so <code class="inline"><a class="l_k" href="../functions/open.html">open</a></code> is frequently used in connection with
<code class="inline"><a class="l_k" href="../functions/die.html">die</a></code>. Even if <code class="inline"><a class="l_k" href="../functions/die.html">die</a></code> won't do what you want (say, in a CGI script,
where you want to make a nicely formatted error message (but there are
modules that can help with that problem)) you should always check
the return value from opening a file. The infrequent exception is when
working with an unopened filehandle is actually what you want to do.</p>
<p>As a special case the 3-arg form with a read/write mode and the third
argument being <code class="inline"><a class="l_k" href="../functions/undef.html">undef</a></code>:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><a class="l_k" href="../functions/my.html">my</a> <span class="i">$tmp</span><span class="cm">,</span> <span class="q">"+>"</span><span class="cm">,</span> <a class="l_k" href="../functions/undef.html">undef</a><span class="s">)</span> or <a class="l_k" href="../functions/die.html">die</a> ...</li></ol></pre><p>opens a filehandle to an anonymous temporary file. Also using "+<"
works for symmetry, but you really should consider writing something
to the temporary file first. You will need to seek() to do the
reading.</p>
<p>Since v5.8.0, perl has built using PerlIO by default. Unless you've
changed this (i.e. Configure -Uuseperlio), you can open file handles to
"in memory" files held in Perl scalars via:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="i">$fh</span><span class="cm">,</span> <span class="q">'>'</span><span class="cm">,</span> \<span class="i">$variable</span><span class="s">)</span> || ..</li></ol></pre><p>Though if you try to re-open <code class="inline"><span class="w">STDOUT</span></code>
or <code class="inline"><span class="w">STDERR</span></code>
as an "in memory"
file, you have to close it first:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/close.html">close</a> <span class="w">STDOUT</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a> <span class="w">STDOUT</span><span class="cm">,</span> <span class="q">'>'</span><span class="cm">,</span> \<span class="i">$variable</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't open STDOUT: $!"</span><span class="sc">;</span></li></ol></pre><p>Examples:</p>
<pre class="verbatim"><ol><li> $ARTICLE = 100;</li><li> open ARTICLE or die "Can't find article $ARTICLE: $!\n";</li><li> while (<ARTICLE>) {...</li><li></li><li> open(LOG, '>>/usr/spool/news/twitlog'); # (log is reserved)</li><li> # if the open fails, output is discarded</li><li></li><li> open(my $dbase, '+<', 'dbase.mine') # open for update</li><li> or die "Can't open 'dbase.mine' for update: $!";</li><li></li><li> open(my $dbase, '+<dbase.mine') # ditto</li><li> or die "Can't open 'dbase.mine' for update: $!";</li><li></li><li> open(ARTICLE, '-|', "caesar <$article") # decrypt article</li><li> or die "Can't start caesar: $!";</li><li></li><li> open(ARTICLE, "caesar <$article |") # ditto</li><li> or die "Can't start caesar: $!";</li><li></li><li> open(EXTRACT, "|sort >Tmp$$") # $$ is our process id</li><li> or die "Can't start sort: $!";</li><li></li><li> # in memory files</li><li> open(MEMORY,'>', \$var)</li><li> or die "Can't open memory file: $!";</li><li> print MEMORY "foo!\n"; # output will end up in $var</li><li></li><li> # process argument list of files along with any includes</li><li></li><li> foreach $file (@ARGV) {</li><li> process($file, 'fh00');</li><li> }</li><li></li><li> sub process {</li><li> my($filename, $input) = @_;</li><li> $input++; # this is a string increment</li><li> unless (open($input, $filename)) {</li><li> print STDERR "Can't open $filename: $!\n";</li><li> return;</li><li> }</li><li></li><li> local $_;</li><li> while (<$input>) { # note use of indirection</li><li> if (/^#include "(.*)"/) {</li><li> process($1, $input);</li><li> next;</li><li> }</li><li> #... # whatever</li><li> }</li><li> }</li></ol></pre><p>See <a href="../perliol.html">perliol</a> for detailed info on PerlIO.</p>
<p>You may also, in the Bourne shell tradition, specify an EXPR beginning
with <code class="inline"><span class="q">'>&'</span></code>
, in which case the rest of the string is interpreted
as the name of a filehandle (or file descriptor, if numeric) to be
duped (as <code class="inline"><span class="i">dup</span><span class="s">(</span><span class="n">2</span><span class="s">)</span></code>
) and opened. You may use <code class="inline"><span class="i">&</span></code>
after <code class="inline">></code>,
<code class="inline">>></code>
, <code class="inline"><</code>
, <code class="inline">+></code>, <code class="inline">+>></code>
, and <code class="inline">+<</code>
.
The mode you specify should match the mode of the original filehandle.
(Duping a filehandle does not take into account any existing contents
of IO buffers.) If you use the 3-arg form then you can pass either a
number, the name of a filehandle or the normal "reference to a glob".</p>
<p>Here is a script that saves, redirects, and restores <code class="inline"><span class="w">STDOUT</span></code>
and
<code class="inline"><span class="w">STDERR</span></code>
using various methods:</p>
<pre class="verbatim"><ol><li> <span class="c">#!/usr/bin/perl</span></li><li> <a class="l_k" href="../functions/open.html">open</a> <a class="l_k" href="../functions/my.html">my</a> <span class="i">$oldout</span><span class="cm">,</span> <span class="q">">&STDOUT"</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't dup STDOUT: $!"</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a> <span class="w">OLDERR</span><span class="cm">,</span> <span class="q">">&"</span><span class="cm">,</span> \<span class="i">*STDERR</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't dup STDERR: $!"</span><span class="sc">;</span></li><li></li><li> <a class="l_k" href="../functions/open.html">open</a> <span class="w">STDOUT</span><span class="cm">,</span> <span class="q">'>'</span><span class="cm">,</span> <span class="q">"foo.out"</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't redirect STDOUT: $!"</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a> <span class="w">STDERR</span><span class="cm">,</span> <span class="q">">&STDOUT"</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't dup STDOUT: $!"</span><span class="sc">;</span></li><li></li><li> <a class="l_k" href="../functions/select.html">select</a> <span class="w">STDERR</span><span class="sc">;</span> <span class="i">$|</span> = <span class="n">1</span><span class="sc">;</span> <span class="c"># make unbuffered</span></li><li> <a class="l_k" href="../functions/select.html">select</a> <span class="w">STDOUT</span><span class="sc">;</span> <span class="i">$|</span> = <span class="n">1</span><span class="sc">;</span> <span class="c"># make unbuffered</span></li><li></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="i">STDOUT</span> <span class="q">"stdout 1\n"</span><span class="sc">;</span> <span class="c"># this works for</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="i">STDERR</span> <span class="q">"stderr 1\n"</span><span class="sc">;</span> <span class="c"># subprocesses too</span></li><li></li><li> <a class="l_k" href="../functions/open.html">open</a> <span class="w">STDOUT</span><span class="cm">,</span> <span class="q">">&"</span><span class="cm">,</span> <span class="i">$oldout</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't dup \$oldout: $!"</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a> <span class="w">STDERR</span><span class="cm">,</span> <span class="q">">&OLDERR"</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't dup OLDERR: $!"</span><span class="sc">;</span></li><li></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="i">STDOUT</span> <span class="q">"stdout 2\n"</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="i">STDERR</span> <span class="q">"stderr 2\n"</span><span class="sc">;</span></li></ol></pre><p>If you specify <code class="inline"><span class="q">'<&=X'</span></code>
, where <code class="inline"><span class="w">X</span></code>
is a file descriptor number
or a filehandle, then Perl will do an equivalent of C's <code class="inline"><span class="w">fdopen</span></code>
of
that file descriptor (and not call <code class="inline"><span class="i">dup</span><span class="s">(</span><span class="n">2</span><span class="s">)</span></code>
); this is more
parsimonious of file descriptors. For example:</p>
<pre class="verbatim"><ol><li> <span class="c"># open for input, reusing the fileno of $fd</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FILEHANDLE</span><span class="cm">,</span> <span class="q">"<&=$fd"</span><span class="s">)</span></li></ol></pre><p>or</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FILEHANDLE</span><span class="cm">,</span> <span class="q">"<&="</span><span class="cm">,</span> <span class="i">$fd</span><span class="s">)</span></li></ol></pre><p>or</p>
<pre class="verbatim"><ol><li> <span class="c"># open for append, using the fileno of OLDFH</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FH</span><span class="cm">,</span> <span class="q">">>&="</span><span class="cm">,</span> <span class="w">OLDFH</span><span class="s">)</span></li></ol></pre><p>or</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FH</span><span class="cm">,</span> <span class="q">">>&=OLDFH"</span><span class="s">)</span></li></ol></pre><p>Being parsimonious on filehandles is also useful (besides being
parsimonious) for example when something is dependent on file
descriptors, like for example locking using flock(). If you do just
<code class="inline"><a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">A</span><span class="cm">,</span> <span class="q">'>>&B'</span><span class="s">)</span></code>
, the filehandle A will not have the same file
descriptor as B, and therefore flock(A) will not flock(B), and vice
versa. But with <code class="inline"><a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">A</span><span class="cm">,</span> <span class="q">'>>&=B'</span><span class="s">)</span></code>
the filehandles will share
the same file descriptor.</p>
<p>Note that if you are using Perls older than 5.8.0, Perl will be using
the standard C libraries' fdopen() to implement the "=" functionality.
On many UNIX systems fdopen() fails when file descriptors exceed a
certain value, typically 255. For Perls 5.8.0 and later, PerlIO is
most often the default.</p>
<p>You can see whether Perl has been compiled with PerlIO or not by
running <code class="inline"><span class="w">perl</span> -<span class="w">V</span></code>
and looking for <code class="inline"><span class="w">useperlio</span>=</code>
line. If <code class="inline"><span class="w">useperlio</span></code>
is <code class="inline"><span class="w">define</span></code>
, you have PerlIO, otherwise you don't.</p>
<p>If you open a pipe on the command <code class="inline"><span class="q">'-'</span></code>
, i.e., either <code class="inline"><span class="q">'|-'</span></code>
or <code class="inline"><span class="q">'-|'</span></code>
with 2-arguments (or 1-argument) form of open(), then
there is an implicit fork done, and the return value of open is the pid
of the child within the parent process, and <code class="inline"><span class="n">0</span></code>
within the child
process. (Use <code class="inline"><a class="l_k" href="../functions/defined.html">defined($pid)</a></code> to determine whether the open was successful.)
The filehandle behaves normally for the parent, but i/o to that
filehandle is piped from/to the STDOUT/STDIN of the child process.
In the child process the filehandle isn't opened--i/o happens from/to
the new STDOUT or STDIN. Typically this is used like the normal
piped open when you want to exercise more control over just how the
pipe command gets executed, such as when you are running setuid, and
don't want to have to scan shell commands for metacharacters.
The following triples are more or less equivalent:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FOO</span><span class="cm">,</span> <span class="q">"|tr '[a-z]' '[A-Z]'"</span><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FOO</span><span class="cm">,</span> <span class="q">'|-'</span><span class="cm">,</span> <span class="q">"tr '[a-z]' '[A-Z]'"</span><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FOO</span><span class="cm">,</span> <span class="q">'|-'</span><span class="s">)</span> || <a class="l_k" href="../functions/exec.html">exec</a> <span class="q">'tr'</span><span class="cm">,</span> <span class="q">'[a-z]'</span><span class="cm">,</span> <span class="q">'[A-Z]'</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FOO</span><span class="cm">,</span> <span class="q">'|-'</span><span class="cm">,</span> <span class="q">"tr"</span><span class="cm">,</span> <span class="q">'[a-z]'</span><span class="cm">,</span> <span class="q">'[A-Z]'</span><span class="s">)</span><span class="sc">;</span></li><li></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FOO</span><span class="cm">,</span> <span class="q">"cat -n '$file'|"</span><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FOO</span><span class="cm">,</span> <span class="q">'-|'</span><span class="cm">,</span> <span class="q">"cat -n '$file'"</span><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FOO</span><span class="cm">,</span> <span class="q">'-|'</span><span class="s">)</span> || <a class="l_k" href="../functions/exec.html">exec</a> <span class="q">'cat'</span><span class="cm">,</span> <span class="q">'-n'</span><span class="cm">,</span> <span class="i">$file</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FOO</span><span class="cm">,</span> <span class="q">'-|'</span><span class="cm">,</span> <span class="q">"cat"</span><span class="cm">,</span> <span class="q">'-n'</span><span class="cm">,</span> <span class="i">$file</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>The last example in each block shows the pipe as "list form", which is
not yet supported on all platforms. A good rule of thumb is that if
your platform has true <code class="inline"><a class="l_k" href="../functions/fork.html">fork()</a></code> (in other words, if your platform is
UNIX) you can use the list form.</p>
<p>See <a href="../perlipc.html#Safe-Pipe-Opens">"Safe Pipe Opens" in perlipc</a> for more examples of this.</p>
<p>Beginning with v5.6.0, Perl will attempt to flush all files opened for
output before any operation that may do a fork, but this may not be
supported on some platforms (see <a href="../perlport.html">perlport</a>). To be safe, you may need
to set <code class="inline"><span class="i">$|</span></code>
($AUTOFLUSH in English) or call the <code class="inline"><span class="i">autoflush</span><span class="s">(</span><span class="s">)</span></code>
method
of <code class="inline"><span class="w">IO::Handle</span></code>
on any open handles.</p>
<p>On systems that support a close-on-exec flag on files, the flag will
be set for the newly opened file descriptor as determined by the value
of $^F. See <a href="../perlvar.html#%24%5eF">"$^F" in perlvar</a>.</p>
<p>Closing any piped filehandle causes the parent process to wait for the
child to finish, and returns the status value in <code class="inline"><span class="i">$?</span></code>
and
<code class="inline"><span class="i">$</span>{<span class="w">^CHILD_ERROR_NATIVE</span>}</code>
.</p>
<p>The filename passed to 2-argument (or 1-argument) form of open() will
have leading and trailing whitespace deleted, and the normal
redirection characters honored. This property, known as "magic open",
can often be used to good effect. A user could specify a filename of
<i>"rsh cat file |"</i>, or you could change certain filenames as needed:</p>
<pre class="verbatim"><ol><li> <span class="i">$filename</span> =~ <span class="q">s/(.*\.gz)\s*$/gzip -dc < $1|/</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FH</span><span class="cm">,</span> <span class="i">$filename</span><span class="s">)</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"Can't open $filename: $!"</span><span class="sc">;</span></li></ol></pre><p>Use 3-argument form to open a file with arbitrary weird characters in it,</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FOO</span><span class="cm">,</span> <span class="q">'<'</span><span class="cm">,</span> <span class="i">$file</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>otherwise it's necessary to protect any leading and trailing whitespace:</p>
<pre class="verbatim"><ol><li> <span class="i">$file</span> =~ <span class="q">s#^(\s)#./$1#</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="w">FOO</span><span class="cm">,</span> <span class="q">"< $file\0"</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>(this may not work on some bizarre filesystems). One should
conscientiously choose between the <i>magic</i> and 3-arguments form
of open():</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a> <span class="w">IN</span><span class="cm">,</span> <span class="i">$ARGV</span>[<span class="n">0</span>]<span class="sc">;</span></li></ol></pre><p>will allow the user to specify an argument of the form <code class="inline"><span class="q">"rsh cat file |"</span></code>
,
but will not work on a filename which happens to have a trailing space, while</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/open.html">open</a> <span class="w">IN</span><span class="cm">,</span> <span class="q">'<'</span><span class="cm">,</span> <span class="i">$ARGV</span>[<span class="n">0</span>]<span class="sc">;</span></li></ol></pre><p>will have exactly the opposite restrictions.</p>
<p>If you want a "real" C <code class="inline"><a class="l_k" href="../functions/open.html">open</a></code> (see <code class="inline"><a class="l_k" href="../functions/open.html">open(2)</a></code> on your system), then you
should use the <code class="inline"><a class="l_k" href="../functions/sysopen.html">sysopen</a></code> function, which involves no such magic (but
may use subtly different filemodes than Perl open(), which is mapped
to C fopen()). This is
another way to protect your filenames from interpretation. For example:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">IO::Handle</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/sysopen.html">sysopen</a><span class="s">(</span><span class="w">HANDLE</span><span class="cm">,</span> <span class="i">$path</span><span class="cm">,</span> <span class="w">O_RDWR</span>|<span class="w">O_CREAT</span>|<span class="w">O_EXCL</span><span class="s">)</span></li><li> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"sysopen $path: $!"</span><span class="sc">;</span></li><li> <span class="i">$oldfh</span> = <a class="l_k" href="../functions/select.html">select</a><span class="s">(</span><span class="w">HANDLE</span><span class="s">)</span><span class="sc">;</span> <span class="i">$|</span> = <span class="n">1</span><span class="sc">;</span> <a class="l_k" href="../functions/select.html">select</a><span class="s">(</span><span class="i">$oldfh</span><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="i">HANDLE</span> <span class="q">"stuff $$\n"</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/seek.html">seek</a><span class="s">(</span><span class="w">HANDLE</span><span class="cm">,</span> <span class="n">0</span><span class="cm">,</span> <span class="n">0</span><span class="s">)</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/print.html">print</a> <span class="q">"File contains: "</span><span class="cm">,</span> <span class="q"><HANDLE></span><span class="sc">;</span></li></ol></pre><p>Using the constructor from the <code class="inline"><span class="w">IO::Handle</span></code>
package (or one of its
subclasses, such as <code class="inline"><span class="w">IO::File</span></code>
or <code class="inline"><span class="w">IO::Socket</span></code>
), you can generate anonymous
filehandles that have the scope of whatever variables hold references to
them, and automatically close whenever and however you leave that scope:</p>
<pre class="verbatim"><ol><li> <a class="l_k" href="../functions/use.html">use</a> <span class="w">IO::File</span><span class="sc">;</span></li><li> <span class="c">#...</span></li><li><a name="read_myfile_munged"></a> sub <span class="m">read_myfile_munged</span> <span class="s">{</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="i">$ALL</span> = <a class="l_k" href="../functions/shift.html">shift</a><span class="sc">;</span></li><li> <a class="l_k" href="../functions/my.html">my</a> <span class="i">$handle</span> = <span class="w">IO::File</span><span class="w">->new</span><span class="sc">;</span></li><li> <a class="l_k" href="../functions/open.html">open</a><span class="s">(</span><span class="i">$handle</span><span class="cm">,</span> <span class="q">"myfile"</span><span class="s">)</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"myfile: $!"</span><span class="sc">;</span></li><li> <span class="i">$first</span> = <span class="q"><$handle></span></li><li> or <a class="l_k" href="../functions/return.html">return</a> <span class="s">(</span><span class="s">)</span><span class="sc">;</span> <span class="c"># Automatically closed here.</span></li><li> <span class="w">mung</span> <span class="i">$first</span> or <a class="l_k" href="../functions/die.html">die</a> <span class="q">"mung failed"</span><span class="sc">;</span> <span class="c"># Or here.</span></li><li> <a class="l_k" href="../functions/return.html">return</a> <span class="i">$first</span><span class="cm">,</span> <span class="q"><$handle></span> if <span class="i">$ALL</span><span class="sc">;</span> <span class="c"># Or here.</span></li><li> <span class="i">$first</span><span class="sc">;</span> <span class="c"># Or here.</span></li><li> <span class="s">}</span></li></ol></pre><p>See <a href="../functions/seek.html">"seek"</a> for some details about mixing reading and writing.</p>
</li>
</ul>
</div>
<div id="content_footer">
</div>
</div>
<div id="right_column">
<div class="side_group">
<div class="side_panel tools_panel">
<p>Recently read</p>
<div id="recent_pages"></div>
</div>
<div class="side_panel tools_panel">
<p>Tools</p>
<ul>
<li><a href="../preferences.html">Preferences</a>
</ul>
</div>
</div>
</div>
<div class="clear"></div>
</div>
<div id="footer">
<div id="footer_content">
</div>
</div>
</div>
<script language="JavaScript" src="../static/combined-20090809.js" type="text/javascript"></script>
<script language="JavaScript" type="text/javascript">
perldoc.setPath(1);
perldoc.pageName = 'open';
perldoc.pageAddress = 'functions/open.html';
perldoc.contentPage = 1;
</script>
</body>
</html>
|
