perlfaq8.html 144 KB
Newer Older
1 2 3
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
4 5
<head>
  <title>perlfaq8 - perldoc.perl.org</title>
6 7
  <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
  <meta http-equiv="Content-Language" content="en-gb">
8 9 10
  <link rel="search" type="application/opensearchdescription+xml" title="Search perldoc.perl.org" href="/static/search.xml"/>
  <link href="static/css-20100830.css" rel="stylesheet" rev="stylesheet" type="text/css" media="screen">
  <link href="static/exploreperl.css" rel="stylesheet" rev="stylesheet" type="text/css">
11 12
</head>

13 14 15 16 17 18 19
<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>
20 21 22 23 24 25 26 27 28
	<div id="strapline">
	  Perl Programming Documentation
	</div>
	<div id="download_link" class="download">
	  <a href="http://www.perl.org/get.html">Download Perl</a>
	</div>
	<div id="explore_link" class="download">
	  <a id="explore_anchor" href="#">Explore</a>
	</div>
29
      </div>
30 31 32 33
      
      <div id="body">
        <div id="left_column">
          <div class="side_group">
34 35
            
	    <div class="side_panel doc_panel">
36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53
              <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>
54
                <li><a href="index-internals.html">Internals</a>
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
                <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>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-B.html">B</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-C.html">C</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-D.html">D</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-E.html">E</a>
                    
                      
                        <li>
                      
                    
                
                    <a href="index-modules-F.html">F</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-G.html">G</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-H.html">H</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-I.html">I</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-L.html">L</a>
                    
                      
                        <li>
                      
                    
                
                    <a href="index-modules-M.html">M</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-N.html">N</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-O.html">O</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-P.html">P</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-S.html">S</a>
                    
                      
                        <li>
                      
                    
                
                    <a href="index-modules-T.html">T</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-U.html">U</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-X.html">X</a>
                    
                
              </ul>
            </div>
277 278 279 280 281 282 283 284
            
	      <div class="side_panel doc_panel">
		<p>Tools</p>
		<ul>
		  <li><a href="preferences.html">Preferences</a>
		</ul>
	      </div>
            
285 286 287 288 289 290 291 292 293
          </div>
        </div>
        <div id="centre_column">
          <div id="content_header">
            <div id="title_bar">
              <div id="page_name">
                <h1>perlfaq8</h1>
              </div>
              <div id="perl_version">
294
                Perl 5 version 26.0 documentation
295
              </div>
296
              <div class="page_links" id="page_links_top">
297 298
                <a href="#" onClick="toolbar.goToTop();return false;">Go to top</a>
		
299 300
              </div>
	      <div class="page_links" id="page_links_bottom">
301
		
302
                  <a href="#" id="page_index_toggle">Show page index</a> &bull;
303
		
304 305 306 307 308 309 310
                <a href="#" id="recent_pages_toggle">Show recent pages</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>
311 312 313 314 315 316 317 318 319 320 321
            </div>
            <div id="breadcrumbs">
                
    <a href="index.html">Home</a> &gt;
    
      
        <a href="index-faq.html">FAQs</a> &gt;
      
    
    perlfaq8
  
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
            </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>
363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378

	    <div id="recent_pages" class="hud_container">
	      <div id="recent_pages_header" class="hud_header">
		<div id="recent_pages_close" class="hud_close"><a href="#" onClick="recentPages.hide();return false;"></a></div>
		<div id="recent_pages_title" class="hud_title"><span class="hud_span_top">Recently read</span></div>
		<div id="recent_pages_topright" class="hud_topright"></div>
	      </div>
	      <div id="recent_pages_content" class="hud_content">
	      </div>
	      <div id="recent_pages_footer" class="hud_footer">
		<div id="recent_pages_bottomleft" class="hud_bottomleft"></div>
		<div id="recent_pages_bottom" class="hud_bottom"><span class="hud_span_bottom"></span></div>
		<div id="recent_pages_resize" class="hud_resize"></div>
	      </div>
	    </div>
  
379 380 381 382 383
	    <div id="from_search"></div>
            <h1>perlfaq8</h1>


  <!--    -->
384
<ul><li><a href="#NAME">NAME</a><li><a href="#VERSION">VERSION</a><li><a href="#DESCRIPTION">DESCRIPTION</a><ul><li><a href="#How-do-I-find-out-which-operating-system-I'm-running-under%3f">How do I find out which operating system I'm running under?</a><li><a href="#How-come-exec()-doesn't-return%3f">How come exec() doesn't return?
385
    </a><li><a href="#How-do-I-do-fancy-stuff-with-the-keyboard%2fscreen%2fmouse%3f">How do I do fancy stuff with the keyboard/screen/mouse?</a><li><a href="#How-do-I-print-something-out-in-color%3f">How do I print something out in color?</a><li><a href="#How-do-I-read-just-one-key-without-waiting-for-a-return-key%3f">How do I read just one key without waiting for a return key?</a><li><a href="#How-do-I-check-whether-input-is-ready-on-the-keyboard%3f">How do I check whether input is ready on the keyboard?</a><li><a href="#How-do-I-clear-the-screen%3f">How do I clear the screen?</a><li><a href="#How-do-I-get-the-screen-size%3f">How do I get the screen size?</a><li><a href="#How-do-I-ask-the-user-for-a-password%3f">How do I ask the user for a password?</a><li><a href="#How-do-I-read-and-write-the-serial-port%3f">How do I read and write the serial port?</a><li><a href="#How-do-I-decode-encrypted-password-files%3f">How do I decode encrypted password files?</a><li><a href="#How-do-I-start-a-process-in-the-background%3f">How do I start a process in the background?</a><li><a href="#How-do-I-trap-control-characters%2fsignals%3f">How do I trap control characters/signals?</a><li><a href="#How-do-I-modify-the-shadow-password-file-on-a-Unix-system%3f">How do I modify the shadow password file on a Unix system?</a><li><a href="#How-do-I-set-the-time-and-date%3f">How do I set the time and date?</a><li><a href="#How-can-I-sleep()-or-alarm()-for-under-a-second%3f">How can I sleep() or alarm() for under a second?
386
   </a><li><a href="#How-can-I-measure-time-under-a-second%3f">How can I measure time under a second?
387
   </a><li><a href="#How-can-I-do-an-atexit()-or-setjmp()%2flongjmp()%3f-(Exception-handling)">How can I do an atexit() or setjmp()/longjmp()? (Exception handling)</a><li><a href="#Why-doesn't-my-sockets-program-work-under-System-V-(Solaris)%3f-What-does-the-error-message-%22Protocol-not-supported%22-mean%3f">Why doesn't my sockets program work under System V (Solaris)? What does the error message "Protocol not supported" mean?</a><li><a href="#How-can-I-call-my-system's-unique-C-functions-from-Perl%3f">How can I call my system's unique C functions from Perl?</a><li><a href="#Where-do-I-get-the-include-files-to-do-ioctl()-or-syscall()%3f">Where do I get the include files to do ioctl() or syscall()?</a><li><a href="#Why-do-setuid-perl-scripts-complain-about-kernel-problems%3f">Why do setuid perl scripts complain about kernel problems?</a><li><a href="#How-can-I-open-a-pipe-both-to-and-from-a-command%3f">How can I open a pipe both to and from a command?</a><li><a href="#Why-can't-I-get-the-output-of-a-command-with-system()%3f">Why can't I get the output of a command with system()?</a><li><a href="#How-can-I-capture-STDERR-from-an-external-command%3f">How can I capture STDERR from an external command?</a><li><a href="#Why-doesn't-open()-return-an-error-when-a-pipe-open-fails%3f">Why doesn't open() return an error when a pipe open fails?</a><li><a href="#What's-wrong-with-using-backticks-in-a-void-context%3f">What's wrong with using backticks in a void context?</a><li><a href="#How-can-I-call-backticks-without-shell-processing%3f">How can I call backticks without shell processing?</a><li><a href="#Why-can't-my-script-read-from-STDIN-after-I-gave-it-EOF-(%5eD-on-Unix%2c-%5eZ-on-MS-DOS)%3f">Why can't my script read from STDIN after I gave it EOF (^D on Unix, ^Z on MS-DOS)?</a><li><a href="#How-can-I-convert-my-shell-script-to-perl%3f">How can I convert my shell script to perl?</a><li><a href="#Can-I-use-perl-to-run-a-telnet-or-ftp-session%3f">Can I use perl to run a telnet or ftp session?</a><li><a href="#How-can-I-write-expect-in-Perl%3f">How can I write expect in Perl?</a><li><a href="#Is-there-a-way-to-hide-perl's-command-line-from-programs-such-as-%22ps%22%3f">Is there a way to hide perl's command line from programs such as "ps"?</a><li><a href="#I-%7bchanged-directory%2c-modified-my-environment%7d-in-a-perl-script.-How-come-the-change-disappeared-when-I-exited-the-script%3f-How-do-I-get-my-changes-to-be-visible%3f">I {changed directory, modified my environment} in a perl script. How come the change disappeared when I exited the script? How do I get my changes to be visible?</a><li><a href="#How-do-I-close-a-process's-filehandle-without-waiting-for-it-to-complete%3f">How do I close a process's filehandle without waiting for it to complete?</a><li><a href="#How-do-I-fork-a-daemon-process%3f">How do I fork a daemon process?</a><li><a href="#How-do-I-find-out-if-I'm-running-interactively-or-not%3f">How do I find out if I'm running interactively or not?</a><li><a href="#How-do-I-timeout-a-slow-event%3f">How do I timeout a slow event?</a><li><a href="#How-do-I-set-CPU-limits%3f">How do I set CPU limits?
388
  </a><li><a href="#How-do-I-avoid-zombies-on-a-Unix-system%3f">How do I avoid zombies on a Unix system?</a><li><a href="#How-do-I-use-an-SQL-database%3f">How do I use an SQL database?</a><li><a href="#How-do-I-make-a-system()-exit-on-control-C%3f">How do I make a system() exit on control-C?</a><li><a href="#How-do-I-open-a-file-without-blocking%3f">How do I open a file without blocking?</a><li><a href="#How-do-I-tell-the-difference-between-errors-from-the-shell-and-perl%3f">How do I tell the difference between errors from the shell and perl?</a><li><a href="#How-do-I-install-a-module-from-CPAN%3f">How do I install a module from CPAN?</a><li><a href="#What's-the-difference-between-require-and-use%3f">What's the difference between require and use?</a><li><a href="#How-do-I-keep-my-own-module%2flibrary-directory%3f">How do I keep my own module/library directory?</a><li><a href="#How-do-I-add-the-directory-my-program-lives-in-to-the-module%2flibrary-search-path%3f">How do I add the directory my program lives in to the module/library search path?</a><li><a href="#How-do-I-add-a-directory-to-my-include-path-(%40INC)-at-runtime%3f">How do I add a directory to my include path (@INC) at runtime?</a><li><a href="#Where-are-modules-installed%3f">Where are modules installed?</a><li><a href="#What-is-socket.ph-and-where-do-I-get-it%3f">What is socket.ph and where do I get it?</a></ul><li><a href="#AUTHOR-AND-COPYRIGHT">AUTHOR AND COPYRIGHT</a></ul><a name="NAME"></a><h1>NAME</h1>
389
<p>perlfaq8 - System Interaction</p>
390
<a name="VERSION"></a><h1>VERSION</h1>
391
<p>version 5.021011</p>
392 393
<a name="DESCRIPTION"></a><h1>DESCRIPTION</h1>
<p>This section of the Perl FAQ covers questions involving operating
394
system interaction. Topics include interprocess communication (IPC),
395 396 397
control over the user-interface (keyboard, screen and pointing
devices), and most anything else not related to data manipulation.</p>
<p>Read the FAQs and documentation specific to the port of perl to your
398
operating system (eg, <a href="perlvms.html">perlvms</a>, <a href="perlplan9.html">perlplan9</a>, ...). These should
399
contain more detailed information on the vagaries of your perl.</p>
400 401 402 403 404 405 406 407
<a name="How-do-I-find-out-which-operating-system-I'm-running-under%3f"></a><h2>How do I find out which operating system I'm running under?</h2>
<p>The <code class="inline"><span class="i">$^O</span></code>
 variable (<code class="inline"><span class="i">$OSNAME</span></code>
 if you use <code class="inline"><span class="w">English</span></code>
) contains an
indication of the name of the operating system (not its release
number) that your perl binary was built for.</p>
<a name="How-come-exec()-doesn't-return%3f"></a><h2>How come exec() doesn't return?
408 409
    </h2>
<p>(contributed by brian d foy)</p>
410 411
<p>The <code class="inline"><a class="l_k" href="functions/exec.html">exec</a></code> function's job is to turn your process into another
command and never to return. If that's not what you want to do, don't
412 413 414
use <code class="inline"><a class="l_k" href="functions/exec.html">exec</a></code>. :)</p>
<p>If you want to run an external command and still keep your Perl process
going, look at a piped <code class="inline"><a class="l_k" href="functions/open.html">open</a></code>, <code class="inline"><a class="l_k" href="functions/fork.html">fork</a></code>, or <code class="inline"><a class="l_k" href="functions/system.html">system</a></code>.</p>
415 416
<a name="How-do-I-do-fancy-stuff-with-the-keyboard%2fscreen%2fmouse%3f"></a><h2>How do I do fancy stuff with the keyboard/screen/mouse?</h2>
<p>How you access/control keyboards, screens, and pointing devices
417
("mice") is system-dependent. Try the following modules:</p>
418 419
<ul>
<li><a name="Keyboard"></a><b>Keyboard</b>
420
<pre class="verbatim"><ol><li>    <span class="w">Term::Cap</span>               <span class="w">Standard</span> <span class="w">perl</span> <span class="w">distribution</span></li><li>    <span class="w">Term::ReadKey</span>           <span class="w">CPAN</span></li><li>    <span class="w">Term::ReadLine::Gnu</span>     <span class="w">CPAN</span></li><li>    <span class="w">Term::ReadLine::Perl</span>    <span class="w">CPAN</span></li><li>    <span class="w">Term::Screen</span>            <span class="w">CPAN</span></li></ol></pre></li>
421
<li><a name="Screen"></a><b>Screen</b>
422
<pre class="verbatim"><ol><li>    <span class="w">Term::Cap</span>               <span class="w">Standard</span> <span class="w">perl</span> <span class="w">distribution</span></li><li>    <span class="w">Curses</span>                  <span class="w">CPAN</span></li><li>    <span class="w">Term::ANSIColor</span>         <span class="w">CPAN</span></li></ol></pre></li>
423
<li><a name="Mouse"></a><b>Mouse</b>
424
<pre class="verbatim"><ol><li>    <span class="w">Tk</span>                      <span class="w">CPAN</span></li><li>    <span class="w">Wx</span>                      <span class="w">CPAN</span></li><li>    <span class="w">Gtk2</span>                    <span class="w">CPAN</span></li><li>    <span class="w">Qt4</span>                     <span class="w">kdebindings4</span> <span class="i">package</span></li></ol></pre></li>
425 426 427 428
</ul>
<p>Some of these specific cases are shown as examples in other answers
in this section of the perlfaq.</p>
<a name="How-do-I-print-something-out-in-color%3f"></a><h2>How do I print something out in color?</h2>
429
<p>In general, you don't, because you don't know whether
430
the recipient has a color-aware display device. If you
431
know that they have an ANSI terminal that understands
432 433 434
color, you can use the <a href="Term/ANSIColor.html">Term::ANSIColor</a> module from CPAN:</p>
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/use.html">use</a> <span class="w">Term::ANSIColor</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/print.html">print</a> <span class="i">color</span><span class="s">(</span><span class="q">&quot;red&quot;</span><span class="s">)</span><span class="cm">,</span> <span class="q">&quot;Stop!\n&quot;</span><span class="cm">,</span> <span class="i">color</span><span class="s">(</span><span class="q">&quot;reset&quot;</span><span class="s">)</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/print.html">print</a> <span class="i">color</span><span class="s">(</span><span class="q">&quot;green&quot;</span><span class="s">)</span><span class="cm">,</span> <span class="q">&quot;Go!\n&quot;</span><span class="cm">,</span> <span class="i">color</span><span class="s">(</span><span class="q">&quot;reset&quot;</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>Or like this:</p>
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/use.html">use</a> <span class="w">Term::ANSIColor</span> <span class="q">qw(:constants)</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/print.html">print</a> <span class="i">RED</span><span class="cm">,</span> <span class="q">&quot;Stop!\n&quot;</span><span class="cm">,</span> <span class="w">RESET</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/print.html">print</a> <span class="i">GREEN</span><span class="cm">,</span> <span class="q">&quot;Go!\n&quot;</span><span class="cm">,</span> <span class="w">RESET</span><span class="sc">;</span></li></ol></pre><a name="How-do-I-read-just-one-key-without-waiting-for-a-return-key%3f"></a><h2>How do I read just one key without waiting for a return key?</h2>
435 436
<p>Controlling input buffering is a remarkably system-dependent matter.
On many systems, you can just use the <b>stty</b> command as shown in
437
<a href="functions/getc.html">getc</a>, but as you see, that's already getting you into
438
portability snags.</p>
439
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/open.html">open</a><span class="s">(</span><span class="w">TTY</span><span class="cm">,</span> <span class="q">&quot;+&lt;/dev/tty&quot;</span><span class="s">)</span> <a class="l_k" href="functions/or.html">or</a> <a class="l_k" href="functions/die.html">die</a> <span class="q">&quot;no tty: $!&quot;</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/system.html">system</a> <span class="q">&quot;stty  cbreak &lt;/dev/tty &gt;/dev/tty 2&gt;&amp;1&quot;</span><span class="sc">;</span></li><li>    <span class="i">$key</span> = <a class="l_k" href="functions/getc.html">getc</a><span class="s">(</span><span class="w">TTY</span><span class="s">)</span><span class="sc">;</span>        <span class="c"># perhaps this works</span></li><li>    <span class="c"># OR ELSE</span></li><li>    <a class="l_k" href="functions/sysread.html">sysread</a><span class="s">(</span><span class="w">TTY</span><span class="cm">,</span> <span class="i">$key</span><span class="cm">,</span> <span class="n">1</span><span class="s">)</span><span class="sc">;</span>    <span class="c"># probably this does</span></li><li>    <a class="l_k" href="functions/system.html">system</a> <span class="q">&quot;stty -cbreak &lt;/dev/tty &gt;/dev/tty 2&gt;&amp;1&quot;</span><span class="sc">;</span></li></ol></pre><p>The <a href="http://search.cpan.org/perldoc/Term::ReadKey">Term::ReadKey</a> module from CPAN offers an easy-to-use interface that
440 441
should be more efficient than shelling out to <b>stty</b> for each key.
It even includes limited support for Windows.</p>
442 443 444
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/use.html">use</a> <span class="w">Term::ReadKey</span><span class="sc">;</span></li><li>    <span class="i">ReadMode</span><span class="s">(</span><span class="q">&#39;cbreak&#39;</span><span class="s">)</span><span class="sc">;</span></li><li>    <span class="i">$key</span> = <span class="i">ReadKey</span><span class="s">(</span><span class="n">0</span><span class="s">)</span><span class="sc">;</span></li><li>    <span class="i">ReadMode</span><span class="s">(</span><span class="q">&#39;normal&#39;</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>However, using the code requires that you have a working C compiler
and can use it to build and install a CPAN module. Here's a solution
using the standard <a href="POSIX.html">POSIX</a> module, which is already on your system
445
(assuming your system supports POSIX).</p>
446
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/use.html">use</a> <span class="w">HotKey</span><span class="sc">;</span></li><li>    <span class="i">$key</span> = <span class="i">readkey</span><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>And here's the <code class="inline"><span class="w">HotKey</span></code>
447
 module, which hides the somewhat mystifying calls
448
to manipulate the POSIX termios structures.</p>
449
<pre class="verbatim"><ol><li>    <span class="c"># HotKey.pm</span></li><li><a name="package-HotKey"></a>    package <span class="i">HotKey</span><span class="sc">;</span></li><li></li><li>    <a class="l_k" href="functions/use.html">use</a> <span class="w">strict</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/use.html">use</a> <span class="w">warnings</span><span class="sc">;</span></li><li></li><li>    <a class="l_k" href="functions/use.html">use</a> <span class="w">parent</span> <span class="q">&#39;Exporter&#39;</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/our.html">our</a> <span class="i">@EXPORT</span> = <span class="q">qw(cbreak cooked readkey)</span><span class="sc">;</span></li><li></li><li>    <a class="l_k" href="functions/use.html">use</a> <span class="w">POSIX</span> <span class="q">qw(:termios_h)</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/my.html">my</a> <span class="s">(</span><span class="i">$term</span><span class="cm">,</span> <span class="i">$oterm</span><span class="cm">,</span> <span class="i">$echo</span><span class="cm">,</span> <span class="i">$noecho</span><span class="cm">,</span> <span class="i">$fd_stdin</span><span class="s">)</span><span class="sc">;</span></li><li></li><li>    <span class="i">$fd_stdin</span> = <a class="l_k" href="functions/fileno.html">fileno</a><span class="s">(</span><span class="w">STDIN</span><span class="s">)</span><span class="sc">;</span></li><li>    <span class="i">$term</span>     = <span class="w">POSIX::Termios</span><span class="w">-&gt;new</span><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li>    <span class="i">$term</span><span class="i">-&gt;getattr</span><span class="s">(</span><span class="i">$fd_stdin</span><span class="s">)</span><span class="sc">;</span></li><li>    <span class="i">$oterm</span>     = <span class="i">$term</span><span class="i">-&gt;getlflag</span><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li></li><li>    <span class="i">$echo</span>     = <span class="w">ECHO</span> | <span class="w">ECHOK</span> | <span class="w">ICANON</span><span class="sc">;</span></li><li>    <span class="i">$noecho</span>   = <span class="i">$oterm</span> &amp; ~<span class="i">$echo</span><span class="sc">;</span></li><li></li><li><a name="cbreak"></a>    sub <span class="m">cbreak</span> <span class="s">{</span></li><li>        <span class="i">$term</span><span class="i">-&gt;setlflag</span><span class="s">(</span><span class="i">$noecho</span><span class="s">)</span><span class="sc">;</span>  <span class="c"># ok, so i don&#39;t want echo either</span></li><li>        <span class="i">$term</span><span class="i">-&gt;setcc</span><span class="s">(</span><span class="w">VTIME</span><span class="cm">,</span> <span class="n">1</span><span class="s">)</span><span class="sc">;</span></li><li>        <span class="i">$term</span><span class="i">-&gt;setattr</span><span class="s">(</span><span class="i">$fd_stdin</span><span class="cm">,</span> <span class="w">TCSANOW</span><span class="s">)</span><span class="sc">;</span></li><li>    <span class="s">}</span></li><li></li><li><a name="cooked"></a>    sub <span class="m">cooked</span> <span class="s">{</span></li><li>        <span class="i">$term</span><span class="i">-&gt;setlflag</span><span class="s">(</span><span class="i">$oterm</span><span class="s">)</span><span class="sc">;</span></li><li>        <span class="i">$term</span><span class="i">-&gt;setcc</span><span class="s">(</span><span class="w">VTIME</span><span class="cm">,</span> <span class="n">0</span><span class="s">)</span><span class="sc">;</span></li><li>        <span class="i">$term</span><span class="i">-&gt;setattr</span><span class="s">(</span><span class="i">$fd_stdin</span><span class="cm">,</span> <span class="w">TCSANOW</span><span class="s">)</span><span class="sc">;</span></li><li>    <span class="s">}</span></li><li></li><li><a name="readkey"></a>    sub <span class="m">readkey</span> <span class="s">{</span></li><li>        <a class="l_k" href="functions/my.html">my</a> <span class="i">$key</span> = <span class="q">&#39;&#39;</span><span class="sc">;</span></li><li>        <span class="i">cbreak</span><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li>        <a class="l_k" href="functions/sysread.html">sysread</a><span class="s">(</span><span class="w">STDIN</span><span class="cm">,</span> <span class="i">$key</span><span class="cm">,</span> <span class="n">1</span><span class="s">)</span><span class="sc">;</span></li><li>        <span class="i">cooked</span><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li>        <a class="l_k" href="functions/return.html">return</a> <span class="i">$key</span><span class="sc">;</span></li><li>    <span class="s">}</span></li><li></li><li>    <a class="l_k" href="functions/END.html">END</a> <span class="s">{</span> <span class="i">cooked</span><span class="s">(</span><span class="s">)</span> <span class="s">}</span></li><li></li><li>    <span class="n">1</span><span class="sc">;</span></li></ol></pre><a name="How-do-I-check-whether-input-is-ready-on-the-keyboard%3f"></a><h2>How do I check whether input is ready on the keyboard?</h2>
450
<p>The easiest way to do this is to read a key in nonblocking mode with the
451
<a href="http://search.cpan.org/perldoc/Term::ReadKey">Term::ReadKey</a> module from CPAN, passing it an argument of -1 to indicate
452
not to block:</p>
453
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/use.html">use</a> <span class="w">Term::ReadKey</span><span class="sc">;</span></li><li></li><li>    <span class="i">ReadMode</span><span class="s">(</span><span class="q">&#39;cbreak&#39;</span><span class="s">)</span><span class="sc">;</span></li><li></li><li>    <a class="l_k" href="functions/if.html">if</a> <span class="s">(</span><a class="l_k" href="functions/defined.html">defined</a> <span class="s">(</span><a class="l_k" href="functions/my.html">my</a> <span class="i">$char</span> = <span class="i">ReadKey</span><span class="s">(</span><span class="n">-1</span><span class="s">)</span><span class="s">)</span> <span class="s">)</span> <span class="s">{</span></li><li>        <span class="c"># input was waiting and it was $char</span></li><li>    <span class="s">}</span> <a class="l_k" href="functions/else.html">else</a> <span class="s">{</span></li><li>        <span class="c"># no input was waiting</span></li><li>    <span class="s">}</span></li><li></li><li>    <span class="i">ReadMode</span><span class="s">(</span><span class="q">&#39;normal&#39;</span><span class="s">)</span><span class="sc">;</span>                  <span class="c"># restore normal tty settings</span></li></ol></pre><a name="How-do-I-clear-the-screen%3f"></a><h2>How do I clear the screen?</h2>
454 455 456 457
<p>(contributed by brian d foy)</p>
<p>To clear the screen, you just have to print the special sequence
that tells the terminal to clear the screen. Once you have that
sequence, output it when you want to clear the screen.</p>
458
<p>You can use the <a href="http://search.cpan.org/perldoc/Term::ANSIScreen">Term::ANSIScreen</a> module to get the special
459 460 461
sequence. Import the <code class="inline"><span class="w">cls</span></code>
 function (or the <code class="inline"><span class="j">:</span><span class="w">screen</span></code>
 tag):</p>
462
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/use.html">use</a> <span class="w">Term::ANSIScreen</span> <span class="q">qw(cls)</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/my.html">my</a> <span class="i">$clear_screen</span> = <span class="i">cls</span><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li></li><li>    <a class="l_k" href="functions/print.html">print</a> <span class="i">$clear_screen</span><span class="sc">;</span></li></ol></pre><p>The <a href="Term/Cap.html">Term::Cap</a> module can also get the special sequence if you want
463 464 465
to deal with the low-level details of terminal control. The <code class="inline"><span class="w">Tputs</span></code>

method returns the string for the given capability:</p>
466
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/use.html">use</a> <span class="w">Term::Cap</span><span class="sc">;</span></li><li></li><li>    <a class="l_k" href="functions/my.html">my</a> <span class="i">$terminal</span> = <span class="w">Term::Cap</span><span class="w">-&gt;Tgetent</span><span class="s">(</span> <span class="s">{</span> <span class="w">OSPEED</span> <span class="cm">=&gt;</span> <span class="n">9600</span> <span class="s">}</span> <span class="s">)</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/my.html">my</a> <span class="i">$clear_screen</span> = <span class="i">$terminal</span><span class="i">-&gt;Tputs</span><span class="s">(</span><span class="q">&#39;cl&#39;</span><span class="s">)</span><span class="sc">;</span></li><li></li><li>    <a class="l_k" href="functions/print.html">print</a> <span class="i">$clear_screen</span><span class="sc">;</span></li></ol></pre><p>On Windows, you can use the <a href="http://search.cpan.org/perldoc/Win32::Console">Win32::Console</a> module. After creating
467 468 469
an object for the output filehandle you want to affect, call the
<code class="inline"><span class="w">Cls</span></code>
 method:</p>
470
<pre class="verbatim"><ol><li>    <span class="w">Win32::Console</span><span class="sc">;</span></li><li></li><li>    <a class="l_k" href="functions/my.html">my</a> <span class="i">$OUT</span> = <span class="w">Win32::Console</span><span class="w">-&gt;new</span><span class="s">(</span><span class="w">STD_OUTPUT_HANDLE</span><span class="s">)</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/my.html">my</a> <span class="i">$clear_string</span> = <span class="i">$OUT</span><span class="i">-&gt;Cls</span><span class="sc">;</span></li><li></li><li>    <a class="l_k" href="functions/print.html">print</a> <span class="i">$clear_screen</span><span class="sc">;</span></li></ol></pre><p>If you have a command-line program that does the job, you can call
471 472
it in backticks to capture whatever it outputs so you can use it
later:</p>
473 474
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/my.html">my</a> <span class="i">$clear_string</span> = <span class="q">`clear`</span><span class="sc">;</span></li><li></li><li>    <a class="l_k" href="functions/print.html">print</a> <span class="i">$clear_string</span><span class="sc">;</span></li></ol></pre><a name="How-do-I-get-the-screen-size%3f"></a><h2>How do I get the screen size?</h2>
<p>If you have <a href="http://search.cpan.org/perldoc/Term::ReadKey">Term::ReadKey</a> module installed from CPAN,
475 476
you can use it to fetch the width and height in characters
and in pixels:</p>
477
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/use.html">use</a> <span class="w">Term::ReadKey</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/my.html">my</a> <span class="s">(</span><span class="i">$wchar</span><span class="cm">,</span> <span class="i">$hchar</span><span class="cm">,</span> <span class="i">$wpixels</span><span class="cm">,</span> <span class="i">$hpixels</span><span class="s">)</span> = <span class="i">GetTerminalSize</span><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>This is more portable than the raw <code class="inline"><a class="l_k" href="functions/ioctl.html">ioctl</a></code>, but not as
478
illustrative:</p>
479
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/require.html">require</a> <span class="q">&#39;./sys/ioctl.ph&#39;</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/die.html">die</a> <span class="q">&quot;no TIOCGWINSZ &quot;</span> <a class="l_k" href="functions/unless.html">unless</a> <a class="l_k" href="functions/defined.html">defined</a> <span class="i">&amp;TIOCGWINSZ</span><span class="sc">;</span></li><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">$tty_fh</span><span class="cm">,</span> <span class="q">&quot;+&lt;/dev/tty&quot;</span><span class="s">)</span>                     <a class="l_k" href="functions/or.html">or</a> <a class="l_k" href="functions/die.html">die</a> <span class="q">&quot;No tty: $!&quot;</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/unless.html">unless</a> <span class="s">(</span><a class="l_k" href="functions/ioctl.html">ioctl</a><span class="s">(</span><span class="i">$tty_fh</span><span class="cm">,</span> <span class="i">&amp;TIOCGWINSZ</span><span class="cm">,</span> <span class="i">$winsize</span>=<span class="q">&#39;&#39;</span><span class="s">)</span><span class="s">)</span> <span class="s">{</span></li><li>        <a class="l_k" href="functions/die.html">die</a> <a class="l_k" href="functions/sprintf.html">sprintf</a> <span class="q">&quot;$0: ioctl TIOCGWINSZ (%08x: $!)\n&quot;</span><span class="cm">,</span> <span class="i">&amp;TIOCGWINSZ</span><span class="sc">;</span></li><li>    <span class="s">}</span></li><li>    <a class="l_k" href="functions/my.html">my</a> <span class="s">(</span><span class="i">$row</span><span class="cm">,</span> <span class="i">$col</span><span class="cm">,</span> <span class="i">$xpixel</span><span class="cm">,</span> <span class="i">$ypixel</span><span class="s">)</span> = <a class="l_k" href="functions/unpack.html">unpack</a><span class="s">(</span><span class="q">&#39;S4&#39;</span><span class="cm">,</span> <span class="i">$winsize</span><span class="s">)</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/print.html">print</a> <span class="q">&quot;(row,col) = ($row,$col)&quot;</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/print.html">print</a> <span class="q">&quot;  (xpixel,ypixel) = ($xpixel,$ypixel)&quot;</span> <a class="l_k" href="functions/if.html">if</a> <span class="i">$xpixel</span> || <span class="i">$ypixel</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/print.html">print</a> <span class="q">&quot;\n&quot;</span><span class="sc">;</span></li></ol></pre><a name="How-do-I-ask-the-user-for-a-password%3f"></a><h2>How do I ask the user for a password?</h2>
480
<p>(This question has nothing to do with the web. See a different
481
FAQ for that.)</p>
482
<p>There's an example of this in <a href="functions/crypt.html">crypt</a>). First, you put the
483 484
terminal into "no echo" mode, then just read the password normally.
You may do this with an old-style <code class="inline"><a class="l_k" href="functions/ioctl.html">ioctl()</a></code> function, POSIX terminal
485 486
control (see <a href="POSIX.html">POSIX</a> or its documentation the Camel Book), or a call
to the <b>stty</b> program, with varying degrees of portability.</p>
487
<p>You can also do this for most systems using the <a href="http://search.cpan.org/perldoc/Term::ReadKey">Term::ReadKey</a> module
488
from CPAN, which is easier to use and in theory more portable.</p>
489 490
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/use.html">use</a> <span class="w">Term::ReadKey</span><span class="sc">;</span></li><li></li><li>    <span class="i">ReadMode</span><span class="s">(</span><span class="q">&#39;noecho&#39;</span><span class="s">)</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/my.html">my</a> <span class="i">$password</span> = <span class="i">ReadLine</span><span class="s">(</span><span class="n">0</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><a name="How-do-I-read-and-write-the-serial-port%3f"></a><h2>How do I read and write the serial port?</h2>
<p>This depends on which operating system your program is running on. In
491
the case of Unix, the serial ports will be accessible through files in
492 493
<code class="inline"><span class="q">/dev</span></code>
; on other systems, device names will doubtless differ.
494 495 496 497
Several problem areas common to all device interaction are the
following:</p>
<ul>
<li><a name="lockfiles"></a><b>lockfiles</b>
498 499
<p>Your system may use lockfiles to control multiple access. Make sure
you follow the correct protocol. Unpredictable behavior can result
500 501 502 503
from multiple processes reading from one device.</p>
</li>
<li><a name="open-mode"></a><b>open mode</b>
<p>If you expect to use both read and write operations on the device,
504
you'll have to open it for update (see <a href="functions/open.html">open</a> for
505
details). You may wish to open it without running the risk of
506
blocking by using <code class="inline"><a class="l_k" href="functions/sysopen.html">sysopen()</a></code> and <code class="inline"><span class="w">O_RDWR</span>|<span class="w">O_NDELAY</span>|<span class="w">O_NOCTTY</span></code>
507
 from the
508
<a href="Fcntl.html">Fcntl</a> module (part of the standard perl distribution). See
509 510 511
<a href="functions/sysopen.html">sysopen</a> for more on this approach.</p>
</li>
<li><a name="end-of-line"></a><b>end of line</b>
512
<p>Some devices will be expecting a "\r" at the end of each line rather
513 514
than a "\n". In some ports of perl, "\r" and "\n" are different from
their usual (Unix) ASCII values of "\015" and "\012". You may have to
515 516
give the numeric values you want directly, using octal ("\015"), hex
("0x0D"), or as a control-character specification ("\cM").</p>
517
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/print.html">print</a> <span class="i">DEV</span> <span class="q">&quot;atv1\012&quot;</span><span class="sc">;</span>    <span class="c"># wrong, for some devices</span></li><li>    <a class="l_k" href="functions/print.html">print</a> <span class="i">DEV</span> <span class="q">&quot;atv1\015&quot;</span><span class="sc">;</span>    <span class="c"># right, for some devices</span></li></ol></pre><p>Even though with normal text files a "\n" will do the trick, there is
518 519
still no unified scheme for terminating a line that is portable
between Unix, DOS/Win, and Macintosh, except to terminate <i>ALL</i> line
520
ends with "\015\012", and strip what you don't need from the output.
521 522 523 524
This applies especially to socket I/O and autoflushing, discussed
next.</p>
</li>
<li><a name="flushing-output"></a><b>flushing output</b>
525
<p>If you expect characters to get to your device when you <code class="inline"><a class="l_k" href="functions/print.html">print()</a></code> them,
526
you'll want to autoflush that filehandle. You can use <code class="inline"><a class="l_k" href="functions/select.html">select()</a></code>
527 528
and the <code class="inline"><span class="i">$|</span></code>
 variable to control autoflushing (see <i>perlvar/$</i>
529
and <a href="functions/select.html">select</a>, or <a href="perlfaq5.html">perlfaq5</a>, "How do I flush/unbuffer an
530 531 532
output filehandle? Why must I do this?"):</p>
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/my.html">my</a> <span class="i">$old_handle</span> = <a class="l_k" href="functions/select.html">select</a><span class="s">(</span><span class="i">$dev_fh</span><span class="s">)</span><span class="sc">;</span></li><li>    <span class="i">$|</span> = <span class="n">1</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/select.html">select</a><span class="s">(</span><span class="i">$old_handle</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>You'll also see code that does this without a temporary variable, as in</p>
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/select.html">select</a><span class="s">(</span><span class="s">(</span><a class="l_k" href="functions/select.html">select</a><span class="s">(</span><span class="i">$deb_handle</span><span class="s">)</span><span class="cm">,</span> <span class="i">$|</span> = <span class="n">1</span><span class="s">)</span>[<span class="n">0</span>]<span class="s">)</span><span class="sc">;</span></li></ol></pre><p>Or if you don't mind pulling in a few thousand lines
533 534
of code just because you're afraid of a little <code class="inline"><span class="i">$|</span></code>
 variable:</p>
535 536
<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>    <span class="i">$dev_fh</span><span class="i">-&gt;autoflush</span><span class="s">(</span><span class="n">1</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>As mentioned in the previous item, this still doesn't work when using
socket I/O between Unix and Macintosh. You'll need to hard code your
537 538 539
line terminators, in that case.</p>
</li>
<li><a name="non-blocking-input"></a><b>non-blocking input</b>
540
<p>If you are doing a blocking <code class="inline"><a class="l_k" href="functions/read.html">read()</a></code> or <code class="inline"><a class="l_k" href="functions/sysread.html">sysread()</a></code>, you'll have to
541
arrange for an alarm handler to provide a timeout (see
542
<a href="functions/alarm.html">alarm</a>). If you have a non-blocking open, you'll likely
543
have a non-blocking read, which means you may have to use a 4-arg
544
<code class="inline"><a class="l_k" href="functions/select.html">select()</a></code> to determine whether I/O is ready on that device (see
545 546 547
<a href="functions/select.html">select</a>.</p>
</li>
</ul>
548 549 550 551 552 553 554
<p>While trying to read from his caller-id box, the notorious Jamie
Zawinski <code class="inline"><span class="q">&lt;jwz@netscape.com&gt;</span></code>
, after much gnashing of teeth and
fighting with <code class="inline"><a class="l_k" href="functions/sysread.html">sysread</a></code>, <code class="inline"><a class="l_k" href="functions/sysopen.html">sysopen</a></code>, POSIX's <code class="inline"><span class="w">tcgetattr</span></code>
 business,
and various other functions that go bump in the night, finally came up
with this:</p>
555
<pre class="verbatim"><ol><li><a name="open_modem"></a>    sub <span class="m">open_modem</span> <span class="s">{</span></li><li>        <a class="l_k" href="functions/use.html">use</a> <span class="w">IPC::Open2</span><span class="sc">;</span></li><li>        <a class="l_k" href="functions/my.html">my</a> <span class="i">$stty</span> = <span class="q">`/bin/stty -g`</span><span class="sc">;</span></li><li>        <span class="i">open2</span><span class="s">(</span> \<span class="i">*MODEM_IN</span><span class="cm">,</span> \<span class="i">*MODEM_OUT</span><span class="cm">,</span> <span class="q">&quot;cu -l$modem_device -s2400 2&gt;&amp;1&quot;</span><span class="s">)</span><span class="sc">;</span></li><li>        <span class="c"># starting cu hoses /dev/tty&#39;s stty settings, even when it has</span></li><li>        <span class="c"># been opened on a pipe...</span></li><li>        <a class="l_k" href="functions/system.html">system</a><span class="s">(</span><span class="q">&quot;/bin/stty $stty&quot;</span><span class="s">)</span><span class="sc">;</span></li><li>        <span class="i">$_</span> = <span class="q">&lt;MODEM_IN&gt;</span><span class="sc">;</span></li><li>        <a class="l_k" href="functions/chomp.html">chomp</a><span class="sc">;</span></li><li>        <a class="l_k" href="functions/if.html">if</a> <span class="s">(</span> !<span class="q">m/^Connected/</span> <span class="s">)</span> <span class="s">{</span></li><li>            <a class="l_k" href="functions/print.html">print</a> <span class="i">STDERR</span> <span class="q">&quot;$0: cu printed `$_&#39; instead of `Connected&#39;\n&quot;</span><span class="sc">;</span></li><li>        <span class="s">}</span></li><li>    <span class="s">}</span></li></ol></pre><a name="How-do-I-decode-encrypted-password-files%3f"></a><h2>How do I decode encrypted password files?</h2>
556 557
<p>You spend lots and lots of money on dedicated hardware, but this is
bound to get you talked about.</p>
558
<p>Seriously, you can't if they are Unix password files--the Unix
559 560 561
password system employs one-way encryption. It's more like hashing
than encryption. The best you can do is check whether something else
hashes to the same string. You can't turn a hash back into the
562
original string. Programs like Crack can forcibly (and intelligently)
563 564
try to guess passwords, but don't (can't) guarantee quick success.</p>
<p>If you're worried about users selecting bad passwords, you should
565
proactively check when they try to change their password (by modifying
566
<i>passwd(1)</i>, for example).</p>
567
<a name="How-do-I-start-a-process-in-the-background%3f"></a><h2>How do I start a process in the background?</h2>
568
<p>(contributed by brian d foy)</p>
569
<p>There's not a single way to run code in the background so you don't
570 571
have to wait for it to finish before your program moves on to other
tasks. Process management depends on your particular operating system,
572 573 574 575 576
and many of the techniques are covered in <a href="perlipc.html">perlipc</a>.</p>
<p>Several CPAN modules may be able to help, including <a href="IPC/Open2.html">IPC::Open2</a> or
<a href="IPC/Open3.html">IPC::Open3</a>, <a href="http://search.cpan.org/perldoc/IPC::Run">IPC::Run</a>, <a href="http://search.cpan.org/perldoc/Parallel::Jobs">Parallel::Jobs</a>,
<a href="http://search.cpan.org/perldoc/Parallel::ForkManager">Parallel::ForkManager</a>, <a href="http://search.cpan.org/perldoc/POE">POE</a>, <a href="http://search.cpan.org/perldoc/Proc::Background">Proc::Background</a>, and
<a href="http://search.cpan.org/perldoc/Win32::Process">Win32::Process</a>. There are many other modules you might use, so
577 578
check those namespaces for other options too.</p>
<p>If you are on a Unix-like system, you might be able to get away with a
579 580
system call where you put an <code class="inline"><span class="i">&amp;</span></code>
 on the end of the command:</p>
581
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/system.html">system</a><span class="s">(</span><span class="q">&quot;cmd &amp;&quot;</span><span class="s">)</span></li></ol></pre><p>You can also try using <code class="inline"><a class="l_k" href="functions/fork.html">fork</a></code>, as described in <a href="perlfunc.html">perlfunc</a> (although
582
this is the same thing that many of the modules will do for you).</p>
583 584
<ul>
<li><a name="STDIN%2c-STDOUT%2c-and-STDERR-are-shared"></a><b>STDIN, STDOUT, and STDERR are shared</b>
585
<p>Both the main process and the backgrounded one (the "child" process)
586 587 588
share the same STDIN, STDOUT and STDERR filehandles. If both try to
access them at once, strange things can happen. You may want to close
or reopen these for the child. You can get around this with
589 590 591 592
<code class="inline"><a class="l_k" href="functions/open.html">open</a></code>ing a pipe (see <a href="functions/open.html">open</a>) but on some systems this
means that the child process cannot outlive the parent.</p>
</li>
<li><a name="Signals"></a><b>Signals</b>
593
<p>You'll have to catch the SIGCHLD signal, and possibly SIGPIPE too.
594
SIGCHLD is sent when the backgrounded process finishes. SIGPIPE is
595
sent when you write to a filehandle whose child process has closed (an
596
untrapped SIGPIPE can cause your program to silently die). This is
597
not an issue with <code class="inline"><a class="l_k" href="functions/system.html">system("cmd&")</a></code>.</p>
598 599
</li>
<li><a name="Zombies"></a><b>Zombies</b>
600
<p>You have to be prepared to "reap" the child process when it finishes.</p>
601
<pre class="verbatim"><ol><li>    <span class="i">$SIG</span>{<span class="w">CHLD</span>} = <a class="l_k" href="functions/sub.html">sub</a> <span class="s">{</span> <a class="l_k" href="functions/wait.html">wait</a> <span class="s">}</span><span class="sc">;</span></li><li></li><li>    <span class="i">$SIG</span>{<span class="w">CHLD</span>} = <span class="q">&#39;IGNORE&#39;</span><span class="sc">;</span></li></ol></pre><p>You can also use a double fork. You immediately <code class="inline"><a class="l_k" href="functions/wait.html">wait()</a></code> for your
602
first child, and the init daemon will <code class="inline"><a class="l_k" href="functions/wait.html">wait()</a></code> for your grandchild once
603
it exits.</p>
604
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/unless.html">unless</a> <span class="s">(</span><span class="i">$pid</span> = <a class="l_k" href="functions/fork.html">fork</a><span class="s">)</span> <span class="s">{</span></li><li>        <a class="l_k" href="functions/unless.html">unless</a> <span class="s">(</span><a class="l_k" href="functions/fork.html">fork</a><span class="s">)</span> <span class="s">{</span></li><li>            <a class="l_k" href="functions/exec.html">exec</a> <span class="q">&quot;what you really wanna do&quot;</span><span class="sc">;</span></li><li>            <a class="l_k" href="functions/die.html">die</a> <span class="q">&quot;exec failed!&quot;</span><span class="sc">;</span></li><li>        <span class="s">}</span></li><li>        <a class="l_k" href="functions/exit.html">exit</a> <span class="n">0</span><span class="sc">;</span></li><li>    <span class="s">}</span></li><li>    <a class="l_k" href="functions/waitpid.html">waitpid</a><span class="s">(</span><span class="i">$pid</span><span class="cm">,</span> <span class="n">0</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>See <a href="perlipc.html#Signals">Signals in perlipc</a> for other examples of code to do this.
605 606 607 608 609
Zombies are not an issue with <code class="inline"><a class="l_k" href="functions/system.html">system</a><span class="s">(</span><span class="q">&quot;prog &amp;&quot;</span><span class="s">)</span></code>
.</p>
</li>
</ul>
<a name="How-do-I-trap-control-characters%2fsignals%3f"></a><h2>How do I trap control characters/signals?</h2>
610
<p>You don't actually "trap" a control character. Instead, that character
611
generates a signal which is sent to your terminal's currently
612
foregrounded process group, which you then trap in your process.
613 614 615 616
Signals are documented in <a href="perlipc.html#Signals">Signals in perlipc</a> and the
section on "Signals" in the Camel.</p>
<p>You can set the values of the <code class="inline"><span class="i">%SIG</span></code>
 hash to be the functions you want
617
to handle the signal. After perl catches the signal, it looks in <code class="inline"><span class="i">%SIG</span></code>
618

619 620
for a key with the same name as the signal, then calls the subroutine
value for that key.</p>
621
<pre class="verbatim"><ol><li>    <span class="c"># as an anonymous subroutine</span></li><li></li><li>    <span class="i">$SIG</span>{<span class="w">INT</span>} = <a class="l_k" href="functions/sub.html">sub</a> <span class="s">{</span> <a class="l_k" href="functions/syswrite.html">syswrite</a><span class="s">(</span><span class="w">STDERR</span><span class="cm">,</span> <span class="q">&quot;ouch\n&quot;</span><span class="cm">,</span> <span class="n">5</span> <span class="s">)</span> <span class="s">}</span><span class="sc">;</span></li><li></li><li>    <span class="c"># or a reference to a function</span></li><li></li><li>    <span class="i">$SIG</span>{<span class="w">INT</span>} = \<span class="i">&amp;ouch</span><span class="sc">;</span></li><li></li><li>    <span class="c"># or the name of the function as a string</span></li><li></li><li>    <span class="i">$SIG</span>{<span class="w">INT</span>} = <span class="q">&quot;ouch&quot;</span><span class="sc">;</span></li></ol></pre><p>Perl versions before 5.8 had in its C source code signal handlers which
622
would catch the signal and possibly run a Perl function that you had set
623
in <code class="inline"><span class="i">%SIG</span></code>
624
. This violated the rules of signal handling at that level
625 626 627
causing perl to dump core. Since version 5.8.0, perl looks at <code class="inline"><span class="i">%SIG</span></code>

<b>after</b> the signal has been caught, rather than while it is being caught.
628 629 630
Previous versions of this answer were incorrect.</p>
<a name="How-do-I-modify-the-shadow-password-file-on-a-Unix-system%3f"></a><h2>How do I modify the shadow password file on a Unix system?</h2>
<p>If perl was installed correctly and your shadow library was written
631 632
properly, the <code class="inline"><span class="w">getpw</span>*<span class="s">(</span><span class="s">)</span></code>
 functions described in <a href="perlfunc.html">perlfunc</a> should in
633
theory provide (read-only) access to entries in the shadow password
634 635
file. To change the file, make a new shadow password file (the format
varies from system to system--see <i>passwd(1)</i> for specifics) and use
636
<code class="inline"><span class="i">pwd_mkdb</span><span class="s">(</span><span class="n">8</span><span class="s">)</span></code>
637
 to install it (see <i>pwd_mkdb(8)</i> for more details).</p>
638
<a name="How-do-I-set-the-time-and-date%3f"></a><h2>How do I set the time and date?</h2>
639 640 641
<p>Assuming you're running under sufficient permissions, you should be
able to set the system-wide date and time by running the <code class="inline"><span class="i">date</span><span class="s">(</span><span class="n">1</span><span class="s">)</span></code>

642
program. (There is no way to set the time and date on a per-process
643
basis.)  This mechanism will work for Unix, MS-DOS, Windows, and NT;
644
the VMS equivalent is <code class="inline"><span class="w">set</span> <a class="l_k" href="functions/time.html">time</a></code>
645 646 647
.</p>
<p>However, if all you want to do is change your time zone, you can
probably get away with setting an environment variable:</p>
648
<pre class="verbatim"><ol><li>    <span class="i">$ENV</span>{<span class="w">TZ</span>} = <span class="q">&quot;MST7MDT&quot;</span><span class="sc">;</span>           <span class="c"># Unixish</span></li><li>    <span class="i">$ENV</span>{<span class="q">&#39;SYS$TIMEZONE_DIFFERENTIAL&#39;</span>}=<span class="q">&quot;-5&quot;</span> <span class="c"># vms</span></li><li>    <a class="l_k" href="functions/system.html">system</a><span class="s">(</span><span class="q">&#39;trn&#39;</span><span class="cm">,</span> <span class="q">&#39;comp.lang.perl.misc&#39;</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><a name="How-can-I-sleep()-or-alarm()-for-under-a-second%3f"></a><h2>How can I sleep() or alarm() for under a second?
649 650 651
   </h2>
<p>If you want finer granularity than the 1 second that the <code class="inline"><a class="l_k" href="functions/sleep.html">sleep()</a></code>
function provides, the easiest way is to use the <code class="inline"><a class="l_k" href="functions/select.html">select()</a></code> function as
652 653 654
documented in <a href="functions/select.html">select</a>. Try the <a href="Time/HiRes.html">Time::HiRes</a> and
the <a href="http://search.cpan.org/perldoc/BSD::Itimer">BSD::Itimer</a> modules (available from CPAN, and starting from
Perl 5.8 <a href="Time/HiRes.html">Time::HiRes</a> is part of the standard distribution).</p>
655 656 657
<a name="How-can-I-measure-time-under-a-second%3f"></a><h2>How can I measure time under a second?
   </h2>
<p>(contributed by brian d foy)</p>
658
<p>The <a href="Time/HiRes.html">Time::HiRes</a> module (part of the standard distribution as of
659 660
Perl 5.8) measures time with the <code class="inline"><span class="i">gettimeofday</span><span class="s">(</span><span class="s">)</span></code>
 system call, which
661
returns the time in microseconds since the epoch. If you can't install
662
<a href="Time/HiRes.html">Time::HiRes</a> for older Perls and you are on a Unixish system, you
663 664 665
may be able to call <code class="inline"><span class="i">gettimeofday</span><span class="s">(</span><span class="n">2</span><span class="s">)</span></code>
 directly. See
<a href="functions/syscall.html">syscall</a>.</p>
666
<a name="How-can-I-do-an-atexit()-or-setjmp()%2flongjmp()%3f-(Exception-handling)"></a><h2>How can I do an atexit() or setjmp()/longjmp()? (Exception handling)</h2>
667 668 669 670 671 672 673 674 675
<p>You can use the <code class="inline">END</code>
 block to simulate <code class="inline"><span class="i">atexit</span><span class="s">(</span><span class="s">)</span></code>
. Each package's
<code class="inline">END</code>
 block is called when the program or thread ends. See the <a href="perlmod.html">perlmod</a>
manpage for more details about <code class="inline">END</code>
 blocks.</p>
<p>For example, you can use this to make sure your filter program managed
to finish its output without filling up the disk:</p>
676
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/END.html">END</a> <span class="s">{</span></li><li>        <a class="l_k" href="functions/close.html">close</a><span class="s">(</span><span class="w">STDOUT</span><span class="s">)</span> || <a class="l_k" href="functions/die.html">die</a> <span class="q">&quot;stdout close failed: $!&quot;</span><span class="sc">;</span></li><li>    <span class="s">}</span></li></ol></pre><p>The <code class="inline">END</code>
677 678 679
 block isn't called when untrapped signals kill the program,
though, so if you use <code class="inline">END</code>
 blocks you should also use</p>
680
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/use.html">use</a> <span class="w">sigtrap</span> <span class="q">qw(die normal-signals)</span><span class="sc">;</span></li></ol></pre><p>Perl's exception-handling mechanism is its <code class="inline"><a class="l_k" href="functions/eval.html">eval()</a></code> operator. You
681 682 683 684 685 686 687
can use <code class="inline"><a class="l_k" href="functions/eval.html">eval()</a></code> as <code class="inline"><span class="w">setjmp</span></code>
 and <code class="inline"><a class="l_k" href="functions/die.html">die()</a></code> as <code class="inline"><span class="w">longjmp</span></code>
. For
details of this, see the section on signals, especially the time-out
handler for a blocking <code class="inline"><a class="l_k" href="functions/flock.html">flock()</a></code> in <a href="perlipc.html#Signals">Signals in perlipc</a> or the
section on "Signals" in <i>Programming Perl</i>.</p>
<p>If exception handling is all you're interested in, use one of the
688
many CPAN modules that handle exceptions, such as <a href="http://search.cpan.org/perldoc/Try::Tiny">Try::Tiny</a>.</p>
689 690 691 692 693
<p>If you want the <code class="inline"><span class="i">atexit</span><span class="s">(</span><span class="s">)</span></code>
 syntax (and an <code class="inline"><span class="i">rmexit</span><span class="s">(</span><span class="s">)</span></code>
 as well), try the
<code class="inline"><span class="w">AtExit</span></code>
 module available from CPAN.</p>
694
<a name="Why-doesn't-my-sockets-program-work-under-System-V-(Solaris)%3f-What-does-the-error-message-%22Protocol-not-supported%22-mean%3f"></a><h2>Why doesn't my sockets program work under System V (Solaris)? What does the error message "Protocol not supported" mean?</h2>
695
<p>Some Sys-V based systems, notably Solaris 2.X, redefined some of the
696 697
standard socket constants. Since these were constant across all
architectures, they were often hardwired into perl code. The proper
698
way to deal with this is to "use Socket" to get the correct values.</p>
699
<p>Note that even though SunOS and Solaris are binary compatible, these
700
values are different. Go figure.</p>
701
<a name="How-can-I-call-my-system's-unique-C-functions-from-Perl%3f"></a><h2>How can I call my system's unique C functions from Perl?</h2>
702
<p>In most cases, you write an external module to do it--see the answer
703
to "Where can I learn about linking C with Perl? [h2xs, xsubpp]".
704
However, if the function is a system call, and your system supports
705
<code class="inline"><a class="l_k" href="functions/syscall.html">syscall()</a></code>, you can use the <code class="inline"><a class="l_k" href="functions/syscall.html">syscall</a></code> function (documented in
706 707
<a href="perlfunc.html">perlfunc</a>).</p>
<p>Remember to check the modules that came with your distribution, and
708
CPAN as well--someone may already have written a module to do it. On
709
Windows, try <a href="http://search.cpan.org/perldoc/Win32::API">Win32::API</a>. On Macs, try <a href="http://search.cpan.org/perldoc/Mac::Carbon">Mac::Carbon</a>. If no module
710
has an interface to the C function, you can inline a bit of C in your
711
Perl source with <a href="http://search.cpan.org/perldoc/Inline::C">Inline::C</a>.</p>
712
<a name="Where-do-I-get-the-include-files-to-do-ioctl()-or-syscall()%3f"></a><h2>Where do I get the include files to do ioctl() or syscall()?</h2>
713 714
<p>Historically, these would be generated by the <a href="h2ph.html">h2ph</a> tool, part of the
standard perl distribution. This program converts <code class="inline"><span class="i">cpp</span><span class="s">(</span><span class="n">1</span><span class="s">)</span></code>
715
 directives
716
in C header files to files containing subroutine definitions, like
717
<code class="inline"><span class="i">SYS_getitimer</span><span class="s">(</span><span class="s">)</span></code>
718 719
, which you can use as arguments to your functions.
It doesn't work perfectly, but it usually gets most of the job done.
720
Simple files like <i>errno.h</i>, <i>syscall.h</i>, and <i>socket.h</i> were fine,
721 722
but the hard ones like <i>ioctl.h</i> nearly always need to be hand-edited.
Here's how to install the *.ph files:</p>
723 724 725 726
<pre class="verbatim"><ol><li>    <span class="n">1.</span> <span class="w">Become</span> <span class="w">the</span> <span class="w">super</span>-<span class="w">user</span></li><li>    <span class="n">2.</span> <span class="w">cd</span> /<span class="w">usr</span>/<span class="w">include</span></li><li>    <span class="n">3.</span> <span class="w">h2ph</span> *.<span class="w">h</span> *<span class="q">/*.h</span></li></ol></pre><p>If your system supports dynamic loading, for reasons of portability and
sanity you probably ought to use <a href="h2xs.html">h2xs</a> (also part of the standard perl
distribution). This tool converts C header files to Perl extensions.
See <a href="perlxstut.html">perlxstut</a> for how to get started with <a href="h2xs.html">h2xs</a>.</p>
727
<p>If your system doesn't support dynamic loading, you still probably
728
ought to use <a href="h2xs.html">h2xs</a>. See <a href="perlxstut.html">perlxstut</a> and <a href="ExtUtils/MakeMaker.html">ExtUtils::MakeMaker</a> for
729 730 731 732
more information (in brief, just use <b>make perl</b> instead of a plain
<b>make</b> to rebuild perl with a new static extension).</p>
<a name="Why-do-setuid-perl-scripts-complain-about-kernel-problems%3f"></a><h2>Why do setuid perl scripts complain about kernel problems?</h2>
<p>Some operating systems have bugs in the kernel that make setuid
733
scripts inherently insecure. Perl gives you a number of options
734 735
(described in <a href="perlsec.html">perlsec</a>) to work around such systems.</p>
<a name="How-can-I-open-a-pipe-both-to-and-from-a-command%3f"></a><h2>How can I open a pipe both to and from a command?</h2>
736
<p>The <a href="IPC/Open2.html">IPC::Open2</a> module (part of the standard perl distribution) is
737
an easy-to-use approach that internally uses <code class="inline"><a class="l_k" href="functions/pipe.html">pipe()</a></code>, <code class="inline"><a class="l_k" href="functions/fork.html">fork()</a></code>, and
738 739
<code class="inline"><a class="l_k" href="functions/exec.html">exec()</a></code> to do the job. Make sure you read the deadlock warnings in
its documentation, though (see <a href="IPC/Open2.html">IPC::Open2</a>). See
740 741
<a href="perlipc.html#Bidirectional-Communication-with-Another-Process">Bidirectional Communication with Another Process in perlipc</a> and
<a href="perlipc.html#Bidirectional-Communication-with-Yourself">Bidirectional Communication with Yourself in perlipc</a></p>
742
<p>You may also use the <a href="IPC/Open3.html">IPC::Open3</a> module (part of the standard perl
743
distribution), but be warned that it has a different order of
744
arguments from <a href="IPC/Open2.html">IPC::Open2</a> (see <a href="IPC/Open3.html">IPC::Open3</a>).</p>
745
<a name="Why-can't-I-get-the-output-of-a-command-with-system()%3f"></a><h2>Why can't I get the output of a command with system()?</h2>
746
<p>You're confusing the purpose of <code class="inline"><a class="l_k" href="functions/system.html">system()</a></code> and backticks (``). <code class="inline"><a class="l_k" href="functions/system.html">system()</a></code>
747 748
runs a command and returns exit status information (as a 16 bit value:
the low 7 bits are the signal the process died from, if any, and
749
the high 8 bits are the actual exit value). Backticks (``) run a
750
command and return what it sent to STDOUT.</p>
751
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/my.html">my</a> <span class="i">$exit_status</span>   = <a class="l_k" href="functions/system.html">system</a><span class="s">(</span><span class="q">&quot;mail-users&quot;</span><span class="s">)</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/my.html">my</a> <span class="i">$output_string</span> = <span class="q">`ls`</span><span class="sc">;</span></li></ol></pre><a name="How-can-I-capture-STDERR-from-an-external-command%3f"></a><h2>How can I capture STDERR from an external command?</h2>
752
<p>There are three basic ways of running external commands:</p>
753
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/system.html">system</a> <span class="i">$cmd</span><span class="sc">;</span>        <span class="c"># using system()</span></li><li>    <a class="l_k" href="functions/my.html">my</a> <span class="i">$output</span> = <span class="q">`$cmd`</span><span class="sc">;</span>        <span class="c"># using backticks (``)</span></li><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">$pipe_fh</span><span class="cm">,</span> <span class="q">&quot;$cmd |&quot;</span><span class="s">)</span><span class="sc">;</span>    <span class="c"># using open()</span></li></ol></pre><p>With <code class="inline"><a class="l_k" href="functions/system.html">system()</a></code>, both STDOUT and STDERR will go the same place as the
754 755 756
script's STDOUT and STDERR, unless the <code class="inline"><a class="l_k" href="functions/system.html">system()</a></code> command redirects them.
Backticks and <code class="inline"><a class="l_k" href="functions/open.html">open()</a></code> read <b>only</b> the STDOUT of your command.</p>
<p>You can also use the <code class="inline"><span class="i">open3</span><span class="s">(</span><span class="s">)</span></code>
757
 function from <a href="IPC/Open3.html">IPC::Open3</a>. Benjamin
758
Goldberg provides some sample code:</p>
759
<p>To capture a program's STDOUT, but discard its STDERR:</p>
760 761 762
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/use.html">use</a> <span class="w">IPC::Open3</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/use.html">use</a> <span class="w">File::Spec</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/my.html">my</a> <span class="i">$in</span> = <span class="q">&#39;&#39;</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/open.html">open</a><span class="s">(</span><span class="w">NULL</span><span class="cm">,</span> <span class="q">&quot;&gt;&quot;</span><span class="cm">,</span> <span class="w">File::Spec</span><span class="w">-&gt;devnull</span><span class="s">)</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/my.html">my</a> <span class="i">$pid</span> = <span class="i">open3</span><span class="s">(</span><span class="i">$in</span><span class="cm">,</span> \<span class="i">*PH</span><span class="cm">,</span> <span class="q">&quot;&gt;&amp;NULL&quot;</span><span class="cm">,</span> <span class="q">&quot;cmd&quot;</span><span class="s">)</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/while.html">while</a><span class="s">(</span> <span class="q">&lt;PH&gt;</span> <span class="s">)</span> <span class="s">{</span> <span class="s">}</span></li><li>    <a class="l_k" href="functions/waitpid.html">waitpid</a><span class="s">(</span><span class="i">$pid</span><span class="cm">,</span> <span class="n">0</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>To capture a program's STDERR, but discard its STDOUT:</p>
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/use.html">use</a> <span class="w">IPC::Open3</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/use.html">use</a> <span class="w">File::Spec</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/my.html">my</a> <span class="i">$in</span> = <span class="q">&#39;&#39;</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/open.html">open</a><span class="s">(</span><span class="w">NULL</span><span class="cm">,</span> <span class="q">&quot;&gt;&quot;</span><span class="cm">,</span> <span class="w">File::Spec</span><span class="w">-&gt;devnull</span><span class="s">)</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/my.html">my</a> <span class="i">$pid</span> = <span class="i">open3</span><span class="s">(</span><span class="i">$in</span><span class="cm">,</span> <span class="q">&quot;&gt;&amp;NULL&quot;</span><span class="cm">,</span> \<span class="i">*PH</span><span class="cm">,</span> <span class="q">&quot;cmd&quot;</span><span class="s">)</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/while.html">while</a><span class="s">(</span> <span class="q">&lt;PH&gt;</span> <span class="s">)</span> <span class="s">{</span> <span class="s">}</span></li><li>    <a class="l_k" href="functions/waitpid.html">waitpid</a><span class="s">(</span><span class="i">$pid</span><span class="cm">,</span> <span class="n">0</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>To capture a program's STDERR, and let its STDOUT go to our own STDERR:</p>
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/use.html">use</a> <span class="w">IPC::Open3</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/my.html">my</a> <span class="i">$in</span> = <span class="q">&#39;&#39;</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/my.html">my</a> <span class="i">$pid</span> = <span class="i">open3</span><span class="s">(</span><span class="i">$in</span><span class="cm">,</span> <span class="q">&quot;&gt;&amp;STDERR&quot;</span><span class="cm">,</span> \<span class="i">*PH</span><span class="cm">,</span> <span class="q">&quot;cmd&quot;</span><span class="s">)</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/while.html">while</a><span class="s">(</span> <span class="q">&lt;PH&gt;</span> <span class="s">)</span> <span class="s">{</span> <span class="s">}</span></li><li>    <a class="l_k" href="functions/waitpid.html">waitpid</a><span class="s">(</span><span class="i">$pid</span><span class="cm">,</span> <span class="n">0</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>To read both a command's STDOUT and its STDERR separately, you can
763 764
redirect them to temp files, let the command run, then read the temp
files:</p>
765
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/use.html">use</a> <span class="w">IPC::Open3</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/use.html">use</a> <span class="w">IO::File</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/my.html">my</a> <span class="i">$in</span> = <span class="q">&#39;&#39;</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/local.html">local</a> <span class="i">*CATCHOUT</span> = <span class="w">IO::File</span><span class="w">-&gt;new_tmpfile</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/local.html">local</a> <span class="i">*CATCHERR</span> = <span class="w">IO::File</span><span class="w">-&gt;new_tmpfile</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/my.html">my</a> <span class="i">$pid</span> = <span class="i">open3</span><span class="s">(</span><span class="i">$in</span><span class="cm">,</span> <span class="q">&quot;&gt;&amp;CATCHOUT&quot;</span><span class="cm">,</span> <span class="q">&quot;&gt;&amp;CATCHERR&quot;</span><span class="cm">,</span> <span class="q">&quot;cmd&quot;</span><span class="s">)</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/waitpid.html">waitpid</a><span class="s">(</span><span class="i">$pid</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/seek.html">seek</a> <span class="i">$_</span><span class="cm">,</span> <span class="n">0</span><span class="cm">,</span> <span class="n">0</span> <a class="l_k" href="functions/for.html">for</a> \<span class="i">*CATCHOUT</span><span class="cm">,</span> \<span class="i">*CATCHERR</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/while.html">while</a><span class="s">(</span> <span class="q">&lt;CATCHOUT&gt;</span> <span class="s">)</span> <span class="s">{</span><span class="s">}</span></li><li>    <a class="l_k" href="functions/while.html">while</a><span class="s">(</span> <span class="q">&lt;CATCHERR&gt;</span> <span class="s">)</span> <span class="s">{</span><span class="s">}</span></li></ol></pre><p>But there's no real need for <b>both</b> to be tempfiles... the following
766
should work just as well, without deadlocking:</p>
767
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/use.html">use</a> <span class="w">IPC::Open3</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/my.html">my</a> <span class="i">$in</span> = <span class="q">&#39;&#39;</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/use.html">use</a> <span class="w">IO::File</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/local.html">local</a> <span class="i">*CATCHERR</span> = <span class="w">IO::File</span><span class="w">-&gt;new_tmpfile</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/my.html">my</a> <span class="i">$pid</span> = <span class="i">open3</span><span class="s">(</span><span class="i">$in</span><span class="cm">,</span> \<span class="i">*CATCHOUT</span><span class="cm">,</span> <span class="q">&quot;&gt;&amp;CATCHERR&quot;</span><span class="cm">,</span> <span class="q">&quot;cmd&quot;</span><span class="s">)</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/while.html">while</a><span class="s">(</span> <span class="q">&lt;CATCHOUT&gt;</span> <span class="s">)</span> <span class="s">{</span><span class="s">}</span></li><li>    <a class="l_k" href="functions/waitpid.html">waitpid</a><span class="s">(</span><span class="i">$pid</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/seek.html">seek</a> <span class="w">CATCHERR</span><span class="cm">,</span> <span class="n">0</span><span class="cm">,</span> <span class="n">0</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/while.html">while</a><span class="s">(</span> <span class="q">&lt;CATCHERR&gt;</span> <span class="s">)</span> <span class="s">{</span><span class="s">}</span></li></ol></pre><p>And it'll be faster, too, since we can begin processing the program's
768 769
stdout immediately, rather than waiting for the program to finish.</p>
<p>With any of these, you can change file descriptors before the call:</p>
770 771
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/open.html">open</a><span class="s">(</span><span class="w">STDOUT</span><span class="cm">,</span> <span class="q">&quot;&gt;logfile&quot;</span><span class="s">)</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/system.html">system</a><span class="s">(</span><span class="q">&quot;ls&quot;</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>or you can use Bourne shell file-descriptor redirection:</p>
<pre class="verbatim"><ol><li>    <span class="i">$output</span> = <span class="q">`$cmd 2&gt;some_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">PIPE</span><span class="cm">,</span> <span class="q">&quot;cmd 2&gt;some_file |&quot;</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>You can also use file-descriptor redirection to make STDERR a
772
duplicate of STDOUT:</p>
773
<pre class="verbatim"><ol><li>    <span class="i">$output</span> = <span class="q">`$cmd 2&gt;&amp;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">PIPE</span><span class="cm">,</span> <span class="q">&quot;cmd 2&gt;&amp;1 |&quot;</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>Note that you <i>cannot</i> simply open STDERR to be a dup of STDOUT
774
in your Perl program and avoid calling the shell to do the redirection.
775
This doesn't work:</p>
776 777
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/open.html">open</a><span class="s">(</span><span class="w">STDERR</span><span class="cm">,</span> <span class="q">&quot;&gt;&amp;STDOUT&quot;</span><span class="s">)</span><span class="sc">;</span></li><li>    <span class="i">$alloutput</span> = <span class="q">`cmd args`</span><span class="sc">;</span>  <span class="c"># stderr still escapes</span></li></ol></pre><p>This fails because the <code class="inline"><a class="l_k" href="functions/open.html">open()</a></code> makes STDERR go to where STDOUT was
going at the time of the <code class="inline"><a class="l_k" href="functions/open.html">open()</a></code>. The backticks then make STDOUT go to
778
a string, but don't change STDERR (which still goes to the old
779
STDOUT).</p>
780 781 782 783
<p>Note that you <i>must</i> use Bourne shell (<code class="inline"><span class="i">sh</span><span class="s">(</span><span class="n">1</span><span class="s">)</span></code>
) redirection syntax in
backticks, not <code class="inline"><span class="i">csh</span><span class="s">(</span><span class="n">1</span><span class="s">)</span></code>
!  Details on why Perl's <code class="inline"><a class="l_k" href="functions/system.html">system()</a></code> and backtick
784
and pipe opens all use the Bourne shell are in the
785
<i>versus/csh.whynot</i> article in the "Far More Than You Ever Wanted To
786
Know" collection in <a href="http://www.cpan.org/misc/olddoc/FMTEYEWTK.tgz">http://www.cpan.org/misc/olddoc/FMTEYEWTK.tgz</a> . To
787
capture a command's STDERR and STDOUT together:</p>
788 789 790
<pre class="verbatim"><ol><li>    <span class="i">$output</span> = <span class="q">`cmd 2&gt;&amp;1`</span><span class="sc">;</span>                       <span class="c"># either with backticks</span></li><li>    <span class="i">$pid</span> = <a class="l_k" href="functions/open.html">open</a><span class="s">(</span><span class="w">PH</span><span class="cm">,</span> <span class="q">&quot;cmd 2&gt;&amp;1 |&quot;</span><span class="s">)</span><span class="sc">;</span>              <span class="c"># or with an open pipe</span></li><li>    while <span class="s">(</span><span class="q">&lt;PH&gt;</span><span class="s">)</span> <span class="s">{</span> <span class="s">}</span>                            <span class="c">#    plus a read</span></li></ol></pre><p>To capture a command's STDOUT but discard its STDERR:</p>
<pre class="verbatim"><ol><li>    <span class="i">$output</span> = <span class="q">`cmd 2&gt;/dev/null`</span><span class="sc">;</span>                <span class="c"># either with backticks</span></li><li>    <span class="i">$pid</span> = <a class="l_k" href="functions/open.html">open</a><span class="s">(</span><span class="w">PH</span><span class="cm">,</span> <span class="q">&quot;cmd 2&gt;/dev/null |&quot;</span><span class="s">)</span><span class="sc">;</span>       <span class="c"># or with an open pipe</span></li><li>    while <span class="s">(</span><span class="q">&lt;PH&gt;</span><span class="s">)</span> <span class="s">{</span> <span class="s">}</span>                            <span class="c">#    plus a read</span></li></ol></pre><p>To capture a command's STDERR but discard its STDOUT:</p>
<pre class="verbatim"><ol><li>    <span class="i">$output</span> = <span class="q">`cmd 2&gt;&amp;1 1&gt;/dev/null`</span><span class="sc">;</span>           <span class="c"># either with backticks</span></li><li>    <span class="i">$pid</span> = <a class="l_k" href="functions/open.html">open</a><span class="s">(</span><span class="w">PH</span><span class="cm">,</span> <span class="q">&quot;cmd 2&gt;&amp;1 1&gt;/dev/null |&quot;</span><span class="s">)</span><span class="sc">;</span>  <span class="c"># or with an open pipe</span></li><li>    while <span class="s">(</span><span class="q">&lt;PH&gt;</span><span class="s">)</span> <span class="s">{</span> <span class="s">}</span>                            <span class="c">#    plus a read</span></li></ol></pre><p>To exchange a command's STDOUT and STDERR in order to capture the STDERR
791
but leave its STDOUT to come out our old STDERR:</p>
792
<pre class="verbatim"><ol><li>    <span class="i">$output</span> = <span class="q">`cmd 3&gt;&amp;1 1&gt;&amp;2 2&gt;&amp;3 3&gt;&amp;-`</span><span class="sc">;</span>        <span class="c"># either with backticks</span></li><li>    <span class="i">$pid</span> = <a class="l_k" href="functions/open.html">open</a><span class="s">(</span><span class="w">PH</span><span class="cm">,</span> <span class="q">&quot;cmd 3&gt;&amp;1 1&gt;&amp;2 2&gt;&amp;3 3&gt;&amp;-|&quot;</span><span class="s">)</span><span class="sc">;</span><span class="c"># or with an open pipe</span></li><li>    while <span class="s">(</span><span class="q">&lt;PH&gt;</span><span class="s">)</span> <span class="s">{</span> <span class="s">}</span>                            <span class="c">#    plus a read</span></li></ol></pre><p>To read both a command's STDOUT and its STDERR separately, it's easiest
793 794
to redirect them separately to files, and then read from those files
when the program is done:</p>
795
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/system.html">system</a><span class="s">(</span><span class="q">&quot;program args 1&gt;program.stdout 2&gt;program.stderr&quot;</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>Ordering is important in all these examples. That's because the shell
796
processes file descriptor redirections in strictly left to right order.</p>
797 798
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/system.html">system</a><span class="s">(</span><span class="q">&quot;prog args 1&gt;tmpfile 2&gt;&amp;1&quot;</span><span class="s">)</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/system.html">system</a><span class="s">(</span><span class="q">&quot;prog args 2&gt;&amp;1 1&gt;tmpfile&quot;</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>The first command sends both standard out and standard error to the
temporary file. The second command sends only the old standard output
799
there, and the old standard error shows up on the old standard out.</p>
800 801 802
<a name="Why-doesn't-open()-return-an-error-when-a-pipe-open-fails%3f"></a><h2>Why doesn't open() return an error when a pipe open fails?</h2>
<p>If the second argument to a piped <code class="inline"><a class="l_k" href="functions/open.html">open()</a></code> contains shell
metacharacters, perl <code class="inline"><a class="l_k" href="functions/fork.html">fork()</a></code>s, then <code class="inline"><a class="l_k" href="functions/exec.html">exec()</a></code>s a shell to decode the
803
metacharacters and eventually run the desired program. If the program
804
couldn't be run, it's the shell that gets the message, not Perl. All
805
your Perl program can find out is whether the shell itself could be
806 807 808
successfully started. You can still capture the shell's STDERR and
check it for error messages. See <a href="#How-can-I-capture-STDERR-from-an-external-command%3f">How can I capture STDERR from an external command?</a> elsewhere in this document, or use the
<a href="IPC/Open3.html">IPC::Open3</a> module.</p>
809
<p>If there are no shell metacharacters in the argument of <code class="inline"><a class="l_k" href="functions/open.html">open()</a></code>, Perl
810 811
runs the command directly, without using the shell, and can correctly
report whether the command started.</p>
812
<a name="What's-wrong-with-using-backticks-in-a-void-context%3f"></a><h2>What's wrong with using backticks in a void context?</h2>
813 814 815 816
<p>Strictly speaking, nothing. Stylistically speaking, it's not a good
way to write maintainable code. Perl has several operators for
running external commands. Backticks are one; they collect the output
from the command for use in your program. The <code class="inline"><a class="l_k" href="functions/system.html">system</a></code> function is
817
another; it doesn't do this.</p>
818 819
<p>Writing backticks in your program sends a clear message to the readers
of your code that you wanted to collect the output of the command.
820
Why send a clear message that isn't true?</p>
821
<p>Consider this line:</p>
822
<pre class="verbatim"><ol><li>    <span class="q">`cat /etc/termcap`</span><span class="sc">;</span></li></ol></pre><p>You forgot to check <code class="inline"><span class="i">$?</span></code>
823
 to see whether the program even ran
824 825 826
correctly. Even if you wrote</p>
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/print.html">print</a> <span class="q">`cat /etc/termcap`</span><span class="sc">;</span></li></ol></pre><p>this code could and probably should be written as</p>
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/system.html">system</a><span class="s">(</span><span class="q">&quot;cat /etc/termcap&quot;</span><span class="s">)</span> == <span class="n">0</span></li><li>    <a class="l_k" href="functions/or.html">or</a> <a class="l_k" href="functions/die.html">die</a> <span class="q">&quot;cat program failed!&quot;</span><span class="sc">;</span></li></ol></pre><p>which will echo the cat command's output as it is generated, instead
827 828 829
of waiting until the program has completed to print it out. It also
checks the return value.</p>
<p><code class="inline"><a class="l_k" href="functions/system.html">system</a></code> also provides direct control over whether shell wildcard
830 831
processing may take place, whereas backticks do not.</p>
<a name="How-can-I-call-backticks-without-shell-processing%3f"></a><h2>How can I call backticks without shell processing?</h2>
832
<p>This is a bit tricky. You can't simply write the command
833
like this:</p>
834
<pre class="verbatim"><ol><li>    <span class="i">@ok</span> = <span class="q">`grep @opts &#39;$search_string&#39; @filenames`</span><span class="sc">;</span></li></ol></pre><p>As of Perl 5.8.0, you can use <code class="inline"><a class="l_k" href="functions/open.html">open()</a></code> with multiple arguments.
835
Just like the list forms of <code class="inline"><a class="l_k" href="functions/system.html">system()</a></code> and <code class="inline"><a class="l_k" href="functions/exec.html">exec()</a></code>, no shell
836
escapes happen.</p>
837 838
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/open.html">open</a><span class="s">(</span> <span class="w">GREP</span><span class="cm">,</span> <span class="q">&quot;-|&quot;</span><span class="cm">,</span> <span class="q">&#39;grep&#39;</span><span class="cm">,</span> <span class="i">@opts</span><span class="cm">,</span> <span class="i">$search_string</span><span class="cm">,</span> <span class="i">@filenames</span> <span class="s">)</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/chomp.html">chomp</a><span class="s">(</span><span class="i">@ok</span> = <span class="q">&lt;GREP&gt;</span><span class="s">)</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/close.html">close</a> <span class="w">GREP</span><span class="sc">;</span></li></ol></pre><p>You can also:</p>
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/my.html">my</a> <span class="i">@ok</span> = <span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/if.html">if</a> <span class="s">(</span><a class="l_k" href="functions/open.html">open</a><span class="s">(</span><span class="w">GREP</span><span class="cm">,</span> <span class="q">&quot;-|&quot;</span><span class="s">)</span><span class="s">)</span> <span class="s">{</span></li><li>        <a class="l_k" href="functions/while.html">while</a> <span class="s">(</span><span class="q">&lt;GREP&gt;</span><span class="s">)</span> <span class="s">{</span></li><li>            <a class="l_k" href="functions/chomp.html">chomp</a><span class="sc">;</span></li><li>            <a class="l_k" href="functions/push.html">push</a><span class="s">(</span><span class="i">@ok</span><span class="cm">,</span> <span class="i">$_</span><span class="s">)</span><span class="sc">;</span></li><li>        <span class="s">}</span></li><li>        <a class="l_k" href="functions/close.html">close</a> <span class="w">GREP</span><span class="sc">;</span></li><li>    <span class="s">}</span> <a class="l_k" href="functions/else.html">else</a> <span class="s">{</span></li><li>        <a class="l_k" href="functions/exec.html">exec</a> <span class="q">&#39;grep&#39;</span><span class="cm">,</span> <span class="i">@opts</span><span class="cm">,</span> <span class="i">$search_string</span><span class="cm">,</span> <span class="i">@filenames</span><span class="sc">;</span></li><li>    <span class="s">}</span></li></ol></pre><p>Just as with <code class="inline"><a class="l_k" href="functions/system.html">system()</a></code>, no shell escapes happen when you <code class="inline"><a class="l_k" href="functions/exec.html">exec()</a></code> a
839 840
list. Further examples of this can be found in <a href="perlipc.html#Safe-Pipe-Opens">Safe Pipe Opens in perlipc</a>.</p>
<p>Note that if you're using Windows, no solution to this vexing issue is
841
even possible. Even though Perl emulates <code class="inline"><a class="l_k" href="functions/fork.html">fork()</a></code>, you'll still be
842
stuck, because Windows does not have an argc/argv-style API.</p>
843 844 845
<a name="Why-can't-my-script-read-from-STDIN-after-I-gave-it-EOF-(%5eD-on-Unix%2c-%5eZ-on-MS-DOS)%3f"></a><h2>Why can't my script read from STDIN after I gave it EOF (^D on Unix, ^Z on MS-DOS)?</h2>
<p>This happens only if your perl is compiled to use stdio instead of
perlio, which is the default. Some (maybe all?) stdios set error and
846
eof flags that you may need to clear. The <a href="POSIX.html">POSIX</a> module defines
847
<code class="inline"><span class="i">clearerr</span><span class="s">(</span><span class="s">)</span></code>
848 849
 that you can use. That is the technically correct way to
do it. Here are some less reliable workarounds:</p>
850 851
<dl>
<dt>1</dt><dd>
852
<p>Try keeping around the seekpointer and go there, like this:</p>
853
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/my.html">my</a> <span class="i">$where</span> = <a class="l_k" href="functions/tell.html">tell</a><span class="s">(</span><span class="i">$log_fh</span><span class="s">)</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/seek.html">seek</a><span class="s">(</span><span class="i">$log_fh</span><span class="cm">,</span> <span class="i">$where</span><span class="cm">,</span> <span class="n">0</span><span class="s">)</span><span class="sc">;</span></li></ol></pre></dd>
854 855
<dt>2</dt><dd>
<p>If that doesn't work, try seeking to a different part of the file and
856
then back.</p>
857 858 859
</dd>
<dt>3</dt><dd>
<p>If that doesn't work, try seeking to a different part of
860
the file, reading something, and then seeking back.</p>
861 862 863 864 865
</dd>
<dt>4</dt><dd>
<p>If that doesn't work, give up on your stdio package and use sysread.</p>
</dd>
</dl>
866
<a name="How-can-I-convert-my-shell-script-to-perl%3f"></a><h2>How can I convert my shell script to perl?</h2>
867
<p>Learn Perl and rewrite it. Seriously, there's no simple converter.
868 869
Things that are awkward to do in the shell are easy to do in Perl, and
this very awkwardness is what would make a shell-&gt;perl converter
870
nigh-on impossible to write. By rewriting it, you'll think about what
871
you're really trying to do, and hopefully will escape the shell's
872 873 874
pipeline datastream paradigm, which while convenient for some matters,
causes many inefficiencies.</p>
<a name="Can-I-use-perl-to-run-a-telnet-or-ftp-session%3f"></a><h2>Can I use perl to run a telnet or ftp session?</h2>
875
<p>Try the <a href="Net/FTP.html">Net::FTP</a>, <a href="http://search.cpan.org/perldoc/TCP::Client">TCP::Client</a>, and <a href="http://search.cpan.org/perldoc/Net::Telnet">Net::Telnet</a> modules
876 877
(available from CPAN).
<a href="http://www.cpan.org/scripts/netstuff/telnet.emul.shar">http://www.cpan.org/scripts/netstuff/telnet.emul.shar</a> will also help
878
for emulating the telnet protocol, but <a href="http://search.cpan.org/perldoc/Net::Telnet">Net::Telnet</a> is quite
879 880
probably easier to use.</p>
<p>If all you want to do is pretend to be telnet but don't need
881 882
the initial telnet handshaking, then the standard dual-process
approach will suffice:</p>
883
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/use.html">use</a> <span class="w">IO::Socket</span><span class="sc">;</span>             <span class="c"># new in 5.004</span></li><li>    <a class="l_k" href="functions/my.html">my</a> <span class="i">$handle</span> = <span class="w">IO::Socket::INET</span><span class="w">-&gt;new</span><span class="s">(</span><span class="q">&#39;www.perl.com:80&#39;</span><span class="s">)</span></li><li>        <a class="l_k" href="functions/or.html">or</a> <a class="l_k" href="functions/die.html">die</a> <span class="q">&quot;can&#39;t connect to port 80 on www.perl.com $!&quot;</span><span class="sc">;</span></li><li>    <span class="i">$handle</span><span class="i">-&gt;autoflush</span><span class="s">(</span><span class="n">1</span><span class="s">)</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/if.html">if</a> <span class="s">(</span><a class="l_k" href="functions/fork.html">fork</a><span class="s">(</span><span class="s">)</span><span class="s">)</span> <span class="s">{</span>               <span class="c"># XXX: undef means failure</span></li><li>        <a class="l_k" href="functions/select.html">select</a><span class="s">(</span><span class="i">$handle</span><span class="s">)</span><span class="sc">;</span></li><li>        <a class="l_k" href="functions/print.html">print</a> <a class="l_k" href="functions/while.html">while</a> <span class="q">&lt;STDIN&gt;</span><span class="sc">;</span>    <span class="c"># everything from stdin to socket</span></li><li>    <span class="s">}</span> <a class="l_k" href="functions/else.html">else</a> <span class="s">{</span></li><li>        <a class="l_k" href="functions/print.html">print</a> <a class="l_k" href="functions/while.html">while</a> <span class="q">&lt;$handle&gt;</span><span class="sc">;</span>  <span class="c"># everything from socket to stdout</span></li><li>    <span class="s">}</span></li><li>    <a class="l_k" href="functions/close.html">close</a> <span class="i">$handle</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/exit.html">exit</a><span class="sc">;</span></li></ol></pre><a name="How-can-I-write-expect-in-Perl%3f"></a><h2>How can I write expect in Perl?</h2>
884
<p>Once upon a time, there was a library called <i>chat2.pl</i> (part of the
885 886 887 888
standard perl distribution), which never really got finished. If you
find it somewhere, <i>don't use it</i>. These days, your best bet is to
look at the <a href="http://search.cpan.org/perldoc/Expect">Expect</a> module available from CPAN, which also requires two
other modules from CPAN, <a href="http://search.cpan.org/perldoc/IO::Pty">IO::Pty</a> and <a href="http://search.cpan.org/perldoc/IO::Stty">IO::Stty</a>.</p>
889 890
<a name="Is-there-a-way-to-hide-perl's-command-line-from-programs-such-as-%22ps%22%3f"></a><h2>Is there a way to hide perl's command line from programs such as "ps"?</h2>
<p>First of all note that if you're doing this for security reasons (to
891 892
avoid people seeing passwords, for example) then you should rewrite
your program so that critical information is never given as an
893
argument. Hiding the arguments won't make your program completely
894 895
secure.</p>
<p>To actually alter the visible command line, you can assign to the
896 897
variable $0 as documented in <a href="perlvar.html">perlvar</a>. This won't work on all
operating systems, though. Daemon programs like sendmail place their
898
state there, as in:</p>
899
<pre class="verbatim"><ol><li>    <span class="i">$0</span> = <span class="q">&quot;orcus [accepting connections]&quot;</span><span class="sc">;</span></li></ol></pre><a name="I-%7bchanged-directory%2c-modified-my-environment%7d-in-a-perl-script.-How-come-the-change-disappeared-when-I-exited-the-script%3f-How-do-I-get-my-changes-to-be-visible%3f"></a><h2>I {changed directory, modified my environment} in a perl script. How come the change disappeared when I exited the script? How do I get my changes to be visible?</h2>
900 901
<ul>
<li><a name="Unix"></a><b>Unix</b>
902
<p>In the strictest sense, it can't be done--the script executes as a
903
different process from the shell it was started from. Changes to a
904
process are not reflected in its parent--only in any children
905
created after the change. There is shell magic that may allow you to
906
fake it by <code class="inline"><a class="l_k" href="functions/eval.html">eval()</a></code>ing the script's output in your shell; check out the
907 908 909
comp.unix.questions FAQ for details.</p>
</li>
</ul>
910
<a name="How-do-I-close-a-process's-filehandle-without-waiting-for-it-to-complete%3f"></a><h2>How do I close a process's filehandle without waiting for it to complete?</h2>
911
<p>Assuming your system supports such things, just send an appropriate signal
912
to the process (see <a href="functions/kill.html">kill</a>). It's common to first send a TERM
913 914
signal, wait a little bit, and then send a KILL signal to finish it off.</p>
<a name="How-do-I-fork-a-daemon-process%3f"></a><h2>How do I fork a daemon process?</h2>
915
<p>If by daemon process you mean one that's detached (disassociated from
916
its tty), then the following process is reported to work on most
917
Unixish systems. Non-Unix users should check their Your_OS::Process
918 919 920
module for other solutions.</p>
<ul>
<li>
921 922
<p>Open /dev/tty and use the TIOCNOTTY ioctl on it. See <i>tty(1)</i>
for details. Or better yet, you can just use the <code class="inline"><span class="i">POSIX::setsid</span><span class="s">(</span><span class="s">)</span></code>
923 924

function, so you don't have to worry about process groups.</p>
925 926 927 928 929
</li>
<li>
<p>Change directory to /</p>
</li>
<li>
930
<p>Reopen STDIN, STDOUT, and STDERR so they're not connected to the old
931 932 933 934
tty.</p>
</li>
<li>
<p>Background yourself like this:</p>
935
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/fork.html">fork</a> &amp;&amp; <a class="l_k" href="functions/exit.html">exit</a><span class="sc">;</span></li></ol></pre></li>
936
</ul>
937
<p>The <a href="http://search.cpan.org/perldoc/Proc::Daemon">Proc::Daemon</a> module, available from CPAN, provides a function to
938
perform these actions for you.</p>
939 940 941 942 943 944 945 946
<a name="How-do-I-find-out-if-I'm-running-interactively-or-not%3f"></a><h2>How do I find out if I'm running interactively or not?</h2>
<p>(contributed by brian d foy)</p>
<p>This is a difficult question to answer, and the best answer is
only a guess.</p>
<p>What do you really want to know? If you merely want to know if one of
your filehandles is connected to a terminal, you can try the <code class="inline">-t</code>

file test:</p>
947 948
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/if.html">if</a><span class="s">(</span> -t <span class="w">STDOUT</span> <span class="s">)</span> <span class="s">{</span></li><li>        <a class="l_k" href="functions/print.html">print</a> <span class="q">&quot;I&#39;m connected to a terminal!\n&quot;</span><span class="sc">;</span></li><li>    <span class="s">}</span></li></ol></pre><p>However, you might be out of luck if you expect that means there is a
real person on the other side. With the <a href="http://search.cpan.org/perldoc/Expect">Expect</a> module, another
949 950
program can pretend to be a person. The program might even come close
to passing the Turing test.</p>
951
<p>The <a href="http://search.cpan.org/perldoc/IO::Interactive">IO::Interactive</a> module does the best it can to give you an
952 953 954 955 956
answer. Its <code class="inline"><span class="w">is_interactive</span></code>
 function returns an output filehandle;
that filehandle points to standard output if the module thinks the
session is interactive. Otherwise, the filehandle is a null handle
that simply discards the output:</p>
957
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/use.html">use</a> <span class="w">IO::Interactive</span><span class="sc">;</span></li><li></li><li>    <a class="l_k" href="functions/print.html">print</a> <span class="s">{</span> <span class="w">is_interactive</span> <span class="s">}</span> <span class="q">&quot;I might go to standard output!\n&quot;</span><span class="sc">;</span></li></ol></pre><p>This still doesn't guarantee that a real person is answering your
958 959 960 961 962
prompts or reading your output.</p>
<p>If you want to know how to handle automated testing for your
distribution, you can check the environment. The CPAN
Testers, for instance, set the value of <code class="inline"><span class="w">AUTOMATED_TESTING</span></code>
:</p>
963
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/unless.html">unless</a><span class="s">(</span> <span class="i">$ENV</span>{<span class="w">AUTOMATED_TESTING</span>} <span class="s">)</span> <span class="s">{</span></li><li>        <a class="l_k" href="functions/print.html">print</a> <span class="q">&quot;Hello interactive tester!\n&quot;</span><span class="sc">;</span></li><li>    <span class="s">}</span></li></ol></pre><a name="How-do-I-timeout-a-slow-event%3f"></a><h2>How do I timeout a slow event?</h2>
964 965
<p>Use the <code class="inline"><a class="l_k" href="functions/alarm.html">alarm()</a></code> function, probably in conjunction with a signal
handler, as documented in <a href="perlipc.html#Signals">Signals in perlipc</a> and the section on
966 967
"Signals" in the Camel. You may instead use the more flexible
<a href="http://search.cpan.org/perldoc/Sys::AlarmCall">Sys::AlarmCall</a> module available from CPAN.</p>
968
<p>The <code class="inline"><a class="l_k" href="functions/alarm.html">alarm()</a></code> function is not implemented on all versions of Windows.
969
Check the documentation for your specific version of Perl.</p>
970 971 972
<a name="How-do-I-set-CPU-limits%3f"></a><h2>How do I set CPU limits?
  </h2>
<p>(contributed by Xho)</p>
973 974
<p>Use the <a href="http://search.cpan.org/perldoc/BSD::Resource">BSD::Resource</a> module from CPAN. As an example:</p>
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/use.html">use</a> <span class="w">BSD::Resource</span><span class="sc">;</span></li><li>    <span class="i">setrlimit</span><span class="s">(</span><span class="w">RLIMIT_CPU</span><span class="cm">,</span><span class="n">10</span><span class="cm">,</span><span class="n">20</span><span class="s">)</span> <a class="l_k" href="functions/or.html">or</a> <a class="l_k" href="functions/die.html">die</a> <span class="i">$!</span><span class="sc">;</span></li></ol></pre><p>This sets the soft and hard limits to 10 and 20 seconds, respectively.
975
After 10 seconds of time spent running on the CPU (not "wall" time),
976
the process will be sent a signal (XCPU on some systems) which, if not
977
trapped, will cause the process to terminate. If that signal is
978 979
trapped, then after 10 more seconds (20 seconds in total) the process
will be killed with a non-trappable signal.</p>
980
<p>See the <a href="http://search.cpan.org/perldoc/BSD::Resource">BSD::Resource</a> and your systems documentation for the gory
981
details.</p>
982
<a name="How-do-I-avoid-zombies-on-a-Unix-system%3f"></a><h2>How do I avoid zombies on a Unix system?</h2>
983
<p>Use the reaper code from <a href="perlipc.html#Signals">Signals in perlipc</a> to call <code class="inline"><a class="l_k" href="functions/wait.html">wait()</a></code> when a
984
SIGCHLD is received, or else use the double-fork technique described
985
in <a href="perlfaq8.html#How-do-I-start-a-process-in-the-background%3f">How do I start a process in the background? in perlfaq8</a>.</p>
986
<a name="How-do-I-use-an-SQL-database%3f"></a><h2>How do I use an SQL database?</h2>
987
<p>The <a href="http://search.cpan.org/perldoc/DBI">DBI</a> module provides an abstract interface to most database