File: perlsub.html

package info (click to toggle)
perl-doc-html 5.26.0-4
  • links: PTS, VCS
  • area: main
  • in suites: sid
  • size: 39,400 kB
  • sloc: xml: 36; makefile: 7
file content (1737 lines) | stat: -rw-r--r-- 187,461 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
  <title>perlsub - perldoc.perl.org</title>
  <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
  <meta http-equiv="Content-Language" content="en-gb">
  <link 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">
</head>

<body onLoad="perldoc.startup();" onPageShow="if (event.persisted) perldoc.startup();">
    <div id="page">
      
      <div id="header">
	<div id="homepage_link">
	  <a href="index.html"></a>
	</div>
	<div id="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>
      </div>
      
      <div id="body">
        <div id="left_column">
          <div class="side_group">
            
	    <div class="side_panel doc_panel">
              <p>Manual</p>
              <ul>
                <li><a href="index-overview.html">Overview</a>
                <li><a href="index-tutorials.html">Tutorials</a>
                <li><a href="index-faq.html">FAQs</a>
                <li><a href="index-history.html">History / Changes</a>
                <li><a href="index-licence.html">License</a>
              </ul>
            </div>
            <div class="side_panel doc_panel">
              <p>Reference</p>
              <ul>
                <li><a href="index-language.html">Language</a>
                <li><a href="index-functions.html">Functions</a>
                <li><a href="perlop.html">Operators</a>
                <li><a href="perlvar.html">Special Variables</a>
                <li><a href="index-pragmas.html">Pragmas</a>
                <li><a href="index-utilities.html">Utilities</a>
                <li><a href="index-internals.html">Internals</a>
                <li><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>
            
	      <div class="side_panel doc_panel">
		<p>Tools</p>
		<ul>
		  <li><a href="preferences.html">Preferences</a>
		</ul>
	      </div>
            
          </div>
        </div>
        <div id="centre_column">
          <div id="content_header">
            <div id="title_bar">
              <div id="page_name">
                <h1>perlsub</h1>
              </div>
              <div id="perl_version">
                Perl 5 version 26.0 documentation
              </div>
              <div class="page_links" id="page_links_top">
                <a href="#" onClick="toolbar.goToTop();return false;">Go to top</a>
		
              </div>
	      <div class="page_links" id="page_links_bottom">
		
                  <a href="#" id="page_index_toggle">Show page index</a> &bull;
		
                <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>
            </div>
            <div id="breadcrumbs">
                
    <a href="index.html">Home</a> &gt;
    
      
        <a href="index-language.html">Language reference</a> &gt;
      
    
    perlsub
  

            </div>
          </div>
          <div id="content_body">
	    <!--[if lt IE 7]>
 <div class="noscript">
   <p>
     <strong>It looks like you're using Internet Explorer 6. This is a very old
     browser which does not offer full support for modern websites.</strong>
   </p>
   <p>
     Unfortunately this means that this website will not work on
     your computer.
   </p>
   <p>
     Don't miss out though! To view the site (and get a better experience from
     many other websites), simply upgrade to
     <a href="http://www.microsoft.com/windows/Internet-explorer/default.aspx">Internet
Explorer 8</a>
     or download an alternative browser such as
     <a href="http://www.mozilla.com/en-US/firefox/firefox.html">Firefox</a>,
     <a href="http://www.apple.com/safari/download/">Safari</a>, or
     <a href="http://www.google.co.uk/chrome">Google Chrome</a>.
   </p>
   <p>
     All of these browsers are free. If you're using a PC at work, you may
     need to contact your IT administrator.
   </p>
 </div>
<![endif]-->
	    <noscript>
	      <div class="noscript">
	      <p>
                <strong>Please note: Many features of this site require JavaScript. You appear to have JavaScript disabled,
	        or are running a non-JavaScript capable web browser.</strong>
	      </p>
	      <p>
		To get the best experience, please enable JavaScript or download a modern web browser such as <a href="http://www.microsoft.com/windows/Internet-explorer/default.aspx">Internet Explorer 8</a>, <a href="http://www.mozilla.com/en-US/firefox/firefox.html">Firefox</a>, <a href="http://www.apple.com/safari/download/">Safari</a>, or <a href="http://www.google.co.uk/chrome">Google Chrome</a>.
              </p>
	      </div>
	    </noscript>

	    <div id="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>
  
	    <div id="from_search"></div>
            <h1>perlsub</h1>


  <!--    -->
<ul><li><a href="#NAME">NAME
 </a><li><a href="#SYNOPSIS">SYNOPSIS</a><li><a href="#DESCRIPTION">DESCRIPTION</a><ul><li><a href="#Signatures">Signatures</a><li><a href="#Private-Variables-via-my()">Private Variables via my()
    
 </a><li><a href="#Persistent-Private-Variables">Persistent Private Variables
     </a><li><a href="#Temporary-Values-via-local()">Temporary Values via local()
   
</a><li><a href="#Lvalue-subroutines">Lvalue subroutines
 </a><li><a href="#Lexical-Subroutines">Lexical Subroutines
   </a><li><a href="#Passing-Symbol-Table-Entries-(typeglobs)">Passing Symbol Table Entries (typeglobs)
 </a><li><a href="#When-to-Still-Use-local()">When to Still Use local()
 </a><li><a href="#Pass-by-Reference">Pass by Reference
  </a><li><a href="#Prototypes">Prototypes
 </a><li><a href="#Constant-Functions">Constant Functions
</a><li><a href="#Overriding-Built-in-Functions">Overriding Built-in Functions
   </a><li><a href="#Autoloading">Autoloading
 </a><li><a href="#Subroutine-Attributes">Subroutine Attributes
  </a></ul><li><a href="#SEE-ALSO">SEE ALSO</a></ul><a name="NAME"></a><h1>NAME
 </h1>
<p>perlsub - Perl subroutines</p>
<a name="SYNOPSIS"></a><h1>SYNOPSIS</h1>
<p>To declare subroutines:
 </p>
<pre class="verbatim"><ol><li>    sub <span class="m">NAME</span><span class="sc">;</span>			  <span class="c"># A &quot;forward&quot; declaration.</span></li><li>    sub <span class="m">NAME(PROTO)</span><span class="sc">;</span>		  <span class="c">#  ditto, but with prototypes</span></li><li><a name="NAME"></a>    sub <span class="m">NAME</span> <span class="co">:</span> <span class="w">ATTRS</span><span class="sc">;</span>		  <span class="c">#  with attributes</span></li><li><a name="NAME-1"></a>    sub <span class="m">NAME(PROTO)</span> <span class="co">:</span> <span class="w">ATTRS</span><span class="sc">;</span>	  <span class="c">#  with attributes and prototypes</span></li><li></li><li><a name="NAME-2"></a>    sub <span class="m">NAME</span> <span class="w">BLOCK</span>		  <span class="c"># A declaration and a definition.</span></li><li><a name="NAME-3"></a>    sub <span class="m">NAME(PROTO)</span> <span class="w">BLOCK</span>	  <span class="c">#  ditto, but with prototypes</span></li><li><a name="NAME-4"></a>    sub <span class="m">NAME(SIG)</span> <span class="w">BLOCK</span>           <span class="c">#  with a signature instead</span></li><li><a name="NAME-5"></a>    sub <span class="m">NAME</span> <span class="co">:</span> <span class="w">ATTRS</span> <span class="w">BLOCK</span>	  <span class="c">#  with attributes</span></li><li><a name="NAME-6"></a>    sub <span class="m">NAME(PROTO)</span> <span class="co">:</span> <span class="w">ATTRS</span> <span class="w">BLOCK</span> <span class="c">#  with prototypes and attributes</span></li><li><a name="NAME-7"></a>    sub <span class="m">NAME(SIG)</span> <span class="co">:</span> <span class="w">ATTRS</span> <span class="w">BLOCK</span>   <span class="c">#  with a signature and attributes</span></li></ol></pre><p>To define an anonymous subroutine at runtime:
</p>
<pre class="verbatim"><ol><li><a name="BLOCK"></a>    <span class="i">$subref</span> = sub <span class="m">BLOCK</span><span class="sc">;</span>		 <span class="c"># no proto</span></li><li>    <span class="i">$subref</span> = <span class="i">sub (PROTO)</span> <span class="i">BLOCK</span><span class="sc">;</span>	 <span class="c"># with proto</span></li><li>    <span class="i">$subref</span> = <span class="i">sub (SIG)</span> <span class="i">BLOCK</span><span class="sc">;</span>           <span class="c"># with signature</span></li><li>    <span class="i">$subref</span> = <span class="i">sub </span><span class="co">:</span> <span class="w">ATTRS</span> <span class="w">BLOCK</span><span class="sc">;</span>	 <span class="c"># with attributes</span></li><li>    <span class="i">$subref</span> = <span class="i">sub (PROTO)</span> <span class="co">:</span> <span class="w">ATTRS</span> <span class="w">BLOCK</span><span class="sc">;</span> <span class="c"># with proto and attributes</span></li><li>    <span class="i">$subref</span> = <span class="i">sub (SIG)</span> <span class="co">:</span> <span class="w">ATTRS</span> <span class="w">BLOCK</span><span class="sc">;</span>   <span class="c"># with signature and attributes</span></li></ol></pre><p>To import subroutines:
</p>
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/use.html">use</a> <span class="w">MODULE</span> <span class="q">qw(NAME1 NAME2 NAME3)</span><span class="sc">;</span></li></ol></pre><p>To call subroutines:
 </p>
<pre class="verbatim"><ol><li>    <span class="i">NAME</span><span class="s">(</span><span class="w">LIST</span><span class="s">)</span><span class="sc">;</span>	   <span class="c"># &amp; is optional with parentheses.</span></li><li>    <span class="w">NAME</span> <span class="w">LIST</span><span class="sc">;</span>	   <span class="c"># Parentheses optional if predeclared/imported.</span></li><li>    <span class="i">&amp;NAME</span><span class="s">(</span><span class="w">LIST</span><span class="s">)</span><span class="sc">;</span>   <span class="c"># Circumvent prototypes.</span></li><li>    <span class="i">&amp;NAME</span><span class="sc">;</span>	   <span class="c"># Makes current @_ visible to called subroutine.</span></li></ol></pre><a name="DESCRIPTION"></a><h1>DESCRIPTION</h1>
<p>Like many languages, Perl provides for user-defined subroutines.
These may be located anywhere in the main program, loaded in from
other files via the <code class="inline"><a class="l_k" href="functions/do.html">do</a></code>, <code class="inline"><a class="l_k" href="functions/require.html">require</a></code>, or <code class="inline"><a class="l_k" href="functions/use.html">use</a></code> keywords, or
generated on the fly using <code class="inline"><a class="l_k" href="functions/eval.html">eval</a></code> or anonymous subroutines.
You can even call a function indirectly using a variable containing
its name or a CODE reference.</p>
<p>The Perl model for function call and return values is simple: all
functions are passed as parameters one single flat list of scalars, and
all functions likewise return to their caller one single flat list of
scalars.  Any arrays or hashes in these call and return lists will
collapse, losing their identities--but you may always use
pass-by-reference instead to avoid this.  Both call and return lists may
contain as many or as few scalar elements as you'd like.  (Often a
function without an explicit return statement is called a subroutine, but
there's really no difference from Perl's perspective.)
 </p>
<p>Any arguments passed in show up in the array <code class="inline"><span class="i">@_</span></code>
.
(They may also show up in lexical variables introduced by a signature;
see <a href="#Signatures">Signatures</a> below.)  Therefore, if
you called a function with two arguments, those would be stored in
<code class="inline"><span class="i">$_</span>[<span class="n">0</span>]</code>
 and <code class="inline"><span class="i">$_</span>[<span class="n">1</span>]</code>
.  The array <code class="inline"><span class="i">@_</span></code>
 is a local array, but its
elements are aliases for the actual scalar parameters.  In particular,
if an element <code class="inline"><span class="i">$_</span>[<span class="n">0</span>]</code>
 is updated, the corresponding argument is
updated (or an error occurs if it is not updatable).  If an argument
is an array or hash element which did not exist when the function
was called, that element is created only when (and if) it is modified
or a reference to it is taken.  (Some earlier versions of Perl
created the element whether or not the element was assigned to.)
Assigning to the whole array <code class="inline"><span class="i">@_</span></code>
 removes that aliasing, and does
not update any arguments.
  </p>
<p>A <code class="inline"><a class="l_k" href="functions/return.html">return</a></code> statement may be used to exit a subroutine, optionally
specifying the returned value, which will be evaluated in the
appropriate context (list, scalar, or void) depending on the context of
the subroutine call.  If you specify no return value, the subroutine
returns an empty list in list context, the undefined value in scalar
context, or nothing in void context.  If you return one or more
aggregates (arrays and hashes), these will be flattened together into
one large indistinguishable list.</p>
<p>If no <code class="inline"><a class="l_k" href="functions/return.html">return</a></code> is found and if the last statement is an expression, its
value is returned.  If the last statement is a loop control structure
like a <code class="inline">foreach</code>
 or a <code class="inline">while</code>
, the returned value is unspecified.  The
empty sub returns the empty list.
  </p>
<p>Aside from an experimental facility (see <a href="#Signatures">Signatures</a> below),
Perl does not have named formal parameters.  In practice all you
do is assign to a <code class="inline"><a class="l_k" href="functions/my.html">my()</a></code> list of these.  Variables that aren't
declared to be private are global variables.  For gory details
on creating private variables, see <a href="#Private-Variables-via-my()">Private Variables via my()</a>
and <a href="#Temporary-Values-via-local()">Temporary Values via local()</a>.  To create protected
environments for a set of functions in a separate package (and
probably a separate file), see <a href="perlmod.html#Packages">Packages in perlmod</a>.
 </p>
<p>Example:</p>
<pre class="verbatim"><ol><li><a name="max"></a>    sub <span class="m">max</span> <span class="s">{</span></li><li>	<a class="l_k" href="functions/my.html">my</a> <span class="i">$max</span> = <a class="l_k" href="functions/shift.html">shift</a><span class="s">(</span><span class="i">@_</span><span class="s">)</span><span class="sc">;</span></li><li>	foreach <span class="i">$foo</span> <span class="s">(</span><span class="i">@_</span><span class="s">)</span> <span class="s">{</span></li><li>	    <span class="i">$max</span> = <span class="i">$foo</span> if <span class="i">$max</span> &lt; <span class="i">$foo</span><span class="sc">;</span></li><li>	<span class="s">}</span></li><li>	<a class="l_k" href="functions/return.html">return</a> <span class="i">$max</span><span class="sc">;</span></li><li>    <span class="s">}</span></li><li>    <span class="i">$bestday</span> = <span class="i">max</span><span class="s">(</span><span class="i">$mon</span><span class="cm">,</span><span class="i">$tue</span><span class="cm">,</span><span class="i">$wed</span><span class="cm">,</span><span class="i">$thu</span><span class="cm">,</span><span class="i">$fri</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>Example:</p>
<pre class="verbatim"><ol><li>    <span class="c"># get a line, combining continuation lines</span></li><li>    <span class="c">#  that start with whitespace</span></li><li></li><li><a name="get_line"></a>    sub <span class="m">get_line</span> <span class="s">{</span></li><li>	<span class="i">$thisline</span> = <span class="i">$lookahead</span><span class="sc">;</span>  <span class="c"># global variables!</span></li><li>	<span class="j">LINE:</span> while <span class="s">(</span><a class="l_k" href="functions/defined.html">defined</a><span class="s">(</span><span class="i">$lookahead</span> = <span class="q">&lt;STDIN&gt;</span><span class="s">)</span><span class="s">)</span> <span class="s">{</span></li><li>	    if <span class="s">(</span><span class="i">$lookahead</span> =~ <span class="q">/^[ \t]/</span><span class="s">)</span> <span class="s">{</span></li><li>		<span class="i">$thisline</span> .= <span class="i">$lookahead</span><span class="sc">;</span></li><li>	    <span class="s">}</span></li><li>	    else <span class="s">{</span></li><li>		<a class="l_k" href="functions/last.html">last</a> <span class="j">LINE</span><span class="sc">;</span></li><li>	    <span class="s">}</span></li><li>	<span class="s">}</span></li><li>	<a class="l_k" href="functions/return.html">return</a> <span class="i">$thisline</span><span class="sc">;</span></li><li>    <span class="s">}</span></li><li></li><li>    <span class="i">$lookahead</span> = <span class="q">&lt;STDIN&gt;</span><span class="sc">;</span>	<span class="c"># get first line</span></li><li>    while <span class="s">(</span><a class="l_k" href="functions/defined.html">defined</a><span class="s">(</span><span class="i">$line</span> = <span class="i">get_line</span><span class="s">(</span><span class="s">)</span><span class="s">)</span><span class="s">)</span> <span class="s">{</span></li><li>	...</li><li>    <span class="s">}</span></li></ol></pre><p>Assigning to a list of private variables to name your arguments:</p>
<pre class="verbatim"><ol><li><a name="maybeset"></a>    sub <span class="m">maybeset</span> <span class="s">{</span></li><li>	<a class="l_k" href="functions/my.html">my</a><span class="s">(</span><span class="i">$key</span><span class="cm">,</span> <span class="i">$value</span><span class="s">)</span> = <span class="i">@_</span><span class="sc">;</span></li><li>	<span class="i">$Foo</span>{<span class="i">$key</span>} = <span class="i">$value</span> unless <span class="i">$Foo</span>{<span class="i">$key</span>}<span class="sc">;</span></li><li>    <span class="s">}</span></li></ol></pre><p>Because the assignment copies the values, this also has the effect
of turning call-by-reference into call-by-value.  Otherwise a
function is free to do in-place modifications of <code class="inline"><span class="i">@_</span></code>
 and change
its caller's values.
 </p>
<pre class="verbatim"><ol><li>    <span class="i">upcase_in</span><span class="s">(</span><span class="i">$v1</span><span class="cm">,</span> <span class="i">$v2</span><span class="s">)</span><span class="sc">;</span>  <span class="c"># this changes $v1 and $v2</span></li><li><a name="upcase_in"></a>    sub <span class="m">upcase_in</span> <span class="s">{</span></li><li>	for <span class="s">(</span><span class="i">@_</span><span class="s">)</span> <span class="s">{</span> <span class="q">tr/a-z/A-Z/</span> <span class="s">}</span></li><li>    <span class="s">}</span></li></ol></pre><p>You aren't allowed to modify constants in this way, of course.  If an
argument were actually literal and you tried to change it, you'd take a
(presumably fatal) exception.   For example, this won't work:
 </p>
<pre class="verbatim"><ol><li>    <span class="i">upcase_in</span><span class="s">(</span><span class="q">&quot;frederick&quot;</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>It would be much safer if the <code class="inline"><span class="i">upcase_in</span><span class="s">(</span><span class="s">)</span></code>
 function
were written to return a copy of its parameters instead
of changing them in place:</p>
<pre class="verbatim"><ol><li>    <span class="s">(</span><span class="i">$v3</span><span class="cm">,</span> <span class="i">$v4</span><span class="s">)</span> = <span class="i">upcase</span><span class="s">(</span><span class="i">$v1</span><span class="cm">,</span> <span class="i">$v2</span><span class="s">)</span><span class="sc">;</span>  <span class="c"># this doesn&#39;t change $v1 and $v2</span></li><li><a name="upcase"></a>    sub <span class="m">upcase</span> <span class="s">{</span></li><li>	<a class="l_k" href="functions/return.html">return</a> unless <a class="l_k" href="functions/defined.html">defined</a> <a class="l_k" href="functions/wantarray.html">wantarray</a><span class="sc">;</span>  <span class="c"># void context, do nothing</span></li><li>	<a class="l_k" href="functions/my.html">my</a> <span class="i">@parms</span> = <span class="i">@_</span><span class="sc">;</span></li><li>	for <span class="s">(</span><span class="i">@parms</span><span class="s">)</span> <span class="s">{</span> <span class="q">tr/a-z/A-Z/</span> <span class="s">}</span></li><li>  	<a class="l_k" href="functions/return.html">return</a> <a class="l_k" href="functions/wantarray.html">wantarray</a> ? <span class="i">@parms</span> <span class="co">:</span> <span class="i">$parms</span>[<span class="n">0</span>]<span class="sc">;</span></li><li>    <span class="s">}</span></li></ol></pre><p>Notice how this (unprototyped) function doesn't care whether it was
passed real scalars or arrays.  Perl sees all arguments as one big,
long, flat parameter list in <code class="inline"><span class="i">@_</span></code>
.  This is one area where
Perl's simple argument-passing style shines.  The <code class="inline"><span class="i">upcase</span><span class="s">(</span><span class="s">)</span></code>

function would work perfectly well without changing the <code class="inline"><span class="i">upcase</span><span class="s">(</span><span class="s">)</span></code>

definition even if we fed it things like this:</p>
<pre class="verbatim"><ol><li>    <span class="i">@newlist</span>   = <span class="i">upcase</span><span class="s">(</span><span class="i">@list1</span><span class="cm">,</span> <span class="i">@list2</span><span class="s">)</span><span class="sc">;</span></li><li>    <span class="i">@newlist</span>   = <span class="i">upcase</span><span class="s">(</span> <a class="l_k" href="functions/split.html">split</a> <span class="q">/:/</span><span class="cm">,</span> <span class="i">$var</span> <span class="s">)</span><span class="sc">;</span></li></ol></pre><p>Do not, however, be tempted to do this:</p>
<pre class="verbatim"><ol><li>    <span class="s">(</span><span class="i">@a</span><span class="cm">,</span> <span class="i">@b</span><span class="s">)</span>   = <span class="i">upcase</span><span class="s">(</span><span class="i">@list1</span><span class="cm">,</span> <span class="i">@list2</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>Like the flattened incoming parameter list, the return list is also
flattened on return.  So all you have managed to do here is stored
everything in <code class="inline"><span class="i">@a</span></code>
 and made <code class="inline"><span class="i">@b</span></code>
 empty.  See 
<a href="#Pass-by-Reference">Pass by Reference</a> for alternatives.</p>
<p>A subroutine may be called using an explicit <code class="inline"><span class="i">&amp;</span></code>
 prefix.  The
<code class="inline"><span class="i">&amp;</span></code>
 is optional in modern Perl, as are parentheses if the
subroutine has been predeclared.  The <code class="inline"><span class="i">&amp;</span></code>
 is <i>not</i> optional
when just naming the subroutine, such as when it's used as
an argument to defined() or undef().  Nor is it optional when you
want to do an indirect subroutine call with a subroutine name or
reference using the <code class="inline"><span class="i">&amp;$subref</span><span class="s">(</span><span class="s">)</span></code>
 or <code class="inline"><span class="i">&amp;</span>{<span class="i">$subref</span>}<span class="s">(</span><span class="s">)</span></code>
 constructs,
although the <code class="inline"><span class="i">$subref</span>-&gt;<span class="s">(</span><span class="s">)</span></code>
 notation solves that problem.
See <a href="perlref.html">perlref</a> for more about all that.
</p>
<p>Subroutines may be called recursively.  If a subroutine is called
using the <code class="inline"><span class="i">&amp;</span></code>
 form, the argument list is optional, and if omitted,
no <code class="inline"><span class="i">@_</span></code>
 array is set up for the subroutine: the <code class="inline"><span class="i">@_</span></code>
 array at the
time of the call is visible to subroutine instead.  This is an
efficiency mechanism that new users may wish to avoid.
</p>
<pre class="verbatim"><ol><li>    <span class="i">&amp;foo</span><span class="s">(</span><span class="n">1</span><span class="cm">,</span><span class="n">2</span><span class="cm">,</span><span class="n">3</span><span class="s">)</span><span class="sc">;</span>	<span class="c"># pass three arguments</span></li><li>    <span class="i">foo</span><span class="s">(</span><span class="n">1</span><span class="cm">,</span><span class="n">2</span><span class="cm">,</span><span class="n">3</span><span class="s">)</span><span class="sc">;</span>		<span class="c"># the same</span></li><li></li><li>    <span class="i">foo</span><span class="s">(</span><span class="s">)</span><span class="sc">;</span>		<span class="c"># pass a null list</span></li><li>    <span class="i">&amp;foo</span><span class="s">(</span><span class="s">)</span><span class="sc">;</span>		<span class="c"># the same</span></li><li></li><li>    <span class="i">&amp;foo</span><span class="sc">;</span>		<span class="c"># foo() get current args, like foo(@_) !!</span></li><li>    <span class="w">foo</span><span class="sc">;</span>		<span class="c"># like foo() IFF sub foo predeclared, else &quot;foo&quot;</span></li></ol></pre><p>Not only does the <code class="inline"><span class="i">&amp;</span></code>
 form make the argument list optional, it also
disables any prototype checking on arguments you do provide.  This
is partly for historical reasons, and partly for having a convenient way
to cheat if you know what you're doing.  See <a href="#Prototypes">Prototypes</a> below.
</p>
<p>Since Perl 5.16.0, the <code class="inline"><a class="l_k" href="functions/__SUB__.html">__SUB__</a></code> token is available under <code class="inline"><a class="l_k" href="functions/use.html">use</a> <span class="w">feature</span>
<span class="q">&#39;current_sub&#39;</span></code>
 and <code class="inline"><a class="l_k" href="functions/use.html">use</a> <span class="v">5.16.0</span></code>
.  It will evaluate to a reference to the
currently-running sub, which allows for recursive calls without knowing
your subroutine's name.</p>
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/use.html">use</a> <span class="v">5.16.0</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/my.html">my</a> <span class="i">$factorial</span> = <a class="l_k" href="functions/sub.html">sub</a> <span class="s">{</span></li><li>      <a class="l_k" href="functions/my.html">my</a> <span class="s">(</span><span class="i">$x</span><span class="s">)</span> = <span class="i">@_</span><span class="sc">;</span></li><li>      <a class="l_k" href="functions/return.html">return</a> <span class="n">1</span> <a class="l_k" href="functions/if.html">if</a> <span class="i">$x</span> == <span class="n">1</span><span class="sc">;</span></li><li>      <a class="l_k" href="functions/return.html">return</a><span class="s">(</span><span class="i">$x</span> * <span class="w">__SUB__</span>-&gt;<span class="s">(</span> <span class="i">$x</span> - <span class="n">1</span> <span class="s">)</span> <span class="s">)</span><span class="sc">;</span></li><li>    <span class="s">}</span><span class="sc">;</span></li></ol></pre><p>The behavior of <code class="inline"><a class="l_k" href="functions/__SUB__.html">__SUB__</a></code> within a regex code block (such as <code class="inline"><span class="q">/(?{...})/</span></code>
)
is subject to change.</p>
<p>Subroutines whose names are in all upper case are reserved to the Perl
core, as are modules whose names are in all lower case.  A subroutine in
all capitals is a loosely-held convention meaning it will be called
indirectly by the run-time system itself, usually due to a triggered event.
Subroutines whose name start with a left parenthesis are also reserved the 
same way.  The following is a list of some subroutines that currently do 
special, pre-defined things.</p>
<ul>
<li><a name="documented-later-in-this-document"></a><b>documented later in this document</b>
<p><code class="inline">AUTOLOAD</code>
</p>
</li>
<li><a name="documented-in-the-perlmod-manpage"></a><b>documented in <a href="perlmod.html">perlmod</a></b>
<p><code class="inline"><span class="w">CLONE</span></code>
, <code class="inline"><span class="w">CLONE_SKIP</span></code>
</p>
</li>
<li><a name="documented-in-the-perlobj-manpage"></a><b>documented in <a href="perlobj.html">perlobj</a></b>
<p><code class="inline">DESTROY</code>
, <code class="inline"><span class="w">DOES</span></code>
</p>
</li>
<li><a name="documented-in-the-perltie-manpage"></a><b>documented in <a href="perltie.html">perltie</a></b>
<p><code class="inline"><span class="w">BINMODE</span></code>
, <code class="inline"><span class="w">CLEAR</span></code>
, <code class="inline"><span class="w">CLOSE</span></code>
, <code class="inline"><span class="w">DELETE</span></code>
, <code class="inline">DESTROY</code>
, <code class="inline"><span class="w">EOF</span></code>
, <code class="inline"><span class="w">EXISTS</span></code>
, 
<code class="inline"><span class="w">EXTEND</span></code>
, <code class="inline"><span class="w">FETCH</span></code>
, <code class="inline"><span class="w">FETCHSIZE</span></code>
, <code class="inline"><span class="w">FILENO</span></code>
, <code class="inline"><span class="w">FIRSTKEY</span></code>
, <code class="inline"><span class="w">GETC</span></code>
, 
<code class="inline"><span class="w">NEXTKEY</span></code>
, <code class="inline"><span class="w">OPEN</span></code>
, <code class="inline"><span class="w">POP</span></code>
, <code class="inline"><span class="w">PRINT</span></code>
, <code class="inline"><span class="w">PRINTF</span></code>
, <code class="inline"><span class="w">PUSH</span></code>
, <code class="inline"><span class="w">READ</span></code>
, 
<code class="inline"><span class="w">READLINE</span></code>
, <code class="inline"><span class="w">SCALAR</span></code>
, <code class="inline"><span class="w">SEEK</span></code>
, <code class="inline"><span class="w">SHIFT</span></code>
, <code class="inline"><span class="w">SPLICE</span></code>
, <code class="inline"><span class="w">STORE</span></code>
, 
<code class="inline"><span class="w">STORESIZE</span></code>
, <code class="inline"><span class="w">TELL</span></code>
, <code class="inline"><span class="w">TIEARRAY</span></code>
, <code class="inline"><span class="w">TIEHANDLE</span></code>
, <code class="inline"><span class="w">TIEHASH</span></code>
, 
<code class="inline"><span class="w">TIESCALAR</span></code>
, <code class="inline"><span class="w">UNSHIFT</span></code>
, <code class="inline"><span class="w">UNTIE</span></code>
, <code class="inline"><span class="w">WRITE</span></code>
</p>
</li>
<li><a name="documented-in-the-PerlIO%3a%3avia-manpage"></a><b>documented in <a href="PerlIO/via.html">PerlIO::via</a></b>
<p><code class="inline"><span class="w">BINMODE</span></code>
, <code class="inline"><span class="w">CLEARERR</span></code>
, <code class="inline"><span class="w">CLOSE</span></code>
, <code class="inline"><span class="w">EOF</span></code>
, <code class="inline"><span class="w">ERROR</span></code>
, <code class="inline"><span class="w">FDOPEN</span></code>
, <code class="inline"><span class="w">FILENO</span></code>
, 
<code class="inline"><span class="w">FILL</span></code>
, <code class="inline"><span class="w">FLUSH</span></code>
, <code class="inline"><span class="w">OPEN</span></code>
, <code class="inline"><span class="w">POPPED</span></code>
, <code class="inline"><span class="w">PUSHED</span></code>
, <code class="inline"><span class="w">READ</span></code>
, <code class="inline"><span class="w">SEEK</span></code>
, 
<code class="inline"><span class="w">SETLINEBUF</span></code>
, <code class="inline"><span class="w">SYSOPEN</span></code>
, <code class="inline"><span class="w">TELL</span></code>
, <code class="inline"><span class="w">UNREAD</span></code>
, <code class="inline"><span class="w">UTF8</span></code>
, <code class="inline"><span class="w">WRITE</span></code>
</p>
</li>
<li><a name="documented-in-the-perlfunc-manpage"></a><b>documented in <a href="perlfunc.html">perlfunc</a></b>
<p><a href="functions/use.html">use</a>, <a href="functions/use.html">use</a>,
<a href="functions/require.html">require</a></p>
</li>
<li><a name="documented-in-the-UNIVERSAL-manpage"></a><b>documented in <a href="UNIVERSAL.html">UNIVERSAL</a></b>
<p><code class="inline"><span class="w">VERSION</span></code>
</p>
</li>
<li><a name="documented-in-the-perldebguts-manpage"></a><b>documented in <a href="perldebguts.html">perldebguts</a></b>
<p><code class="inline"><span class="w">DB::DB</span></code>
, <code class="inline"><span class="w">DB::sub</span></code>
, <code class="inline"><span class="w">DB::lsub</span></code>
, <code class="inline"><span class="w">DB::goto</span></code>
, <code class="inline"><span class="w">DB::postponed</span></code>
</p>
</li>
<li><a name="undocumented%2c-used-internally-by-the-the-overload-manpage-feature"></a><b>undocumented, used internally by the <a href="overload.html">overload</a> feature</b>
<p>any starting with <code class="inline">(</code></p>
</li>
</ul>
<p>The <code class="inline">BEGIN</code>
, <code class="inline">UNITCHECK</code>
, <code class="inline">CHECK</code>
, <code class="inline">INIT</code>
 and <code class="inline">END</code>
 subroutines
are not so much subroutines as named special code blocks, of which you
can have more than one in a package, and which you can <b>not</b> call
explicitly.  See <a href="perlmod.html#BEGIN%2c-UNITCHECK%2c-CHECK%2c-INIT-and-END">BEGIN, UNITCHECK, CHECK, INIT and END in perlmod</a></p>
<a name="Signatures"></a><h2>Signatures</h2>
<p><b>WARNING</b>: Subroutine signatures are experimental.  The feature may be
modified or removed in future versions of Perl.</p>
<p>Perl has an experimental facility to allow a subroutine's formal
parameters to be introduced by special syntax, separate from the
procedural code of the subroutine body.  The formal parameter list
is known as a <i>signature</i>.  The facility must be enabled first by a
pragmatic declaration, <code class="inline"><a class="l_k" href="functions/use.html">use</a> <span class="w">feature</span> <span class="q">&#39;signatures&#39;</span></code>
, and it will produce
a warning unless the "experimental::signatures" warnings category is
disabled.</p>
<p>The signature is part of a subroutine's body.  Normally the body of a
subroutine is simply a braced block of code.  When using a signature,
the signature is a parenthesised list that goes immediately after
the subroutine name (or, for anonymous subroutines, immediately after
the <code class="inline"><a class="l_k" href="functions/sub.html">sub</a></code> keyword).  The signature declares lexical variables that are
in scope for the block.  When the subroutine is called, the signature
takes control first.  It populates the signature variables from the
list of arguments that were passed.  If the argument list doesn't meet
the requirements of the signature, then it will throw an exception.
When the signature processing is complete, control passes to the block.</p>
<p>Positional parameters are handled by simply naming scalar variables in
the signature.  For example,</p>
<pre class="verbatim"><ol><li><a name="foo"></a>    sub <span class="m">foo ($left, $right)</span> <span class="s">{</span></li><li>	<a class="l_k" href="functions/return.html">return</a> <span class="i">$left</span> + <span class="i">$right</span><span class="sc">;</span></li><li>    <span class="s">}</span></li></ol></pre><p>takes two positional parameters, which must be filled at runtime by
two arguments.  By default the parameters are mandatory, and it is
not permitted to pass more arguments than expected.  So the above is
equivalent to</p>
<pre class="verbatim"><ol><li><a name="foo"></a>    sub <span class="m">foo</span> <span class="s">{</span></li><li>	<a class="l_k" href="functions/die.html">die</a> <span class="q">&quot;Too many arguments for subroutine&quot;</span> <a class="l_k" href="functions/unless.html">unless</a> <span class="i">@_</span> &lt;= <span class="n">2</span><span class="sc">;</span></li><li>	<a class="l_k" href="functions/die.html">die</a> <span class="q">&quot;Too few arguments for subroutine&quot;</span> <a class="l_k" href="functions/unless.html">unless</a> <span class="i">@_</span> &gt;= <span class="n">2</span><span class="sc">;</span></li><li>	<a class="l_k" href="functions/my.html">my</a> <span class="i">$left</span> = <span class="i">$_</span>[<span class="n">0</span>]<span class="sc">;</span></li><li>	<a class="l_k" href="functions/my.html">my</a> <span class="i">$right</span> = <span class="i">$_</span>[<span class="n">1</span>]<span class="sc">;</span></li><li>	<a class="l_k" href="functions/return.html">return</a> <span class="i">$left</span> + <span class="i">$right</span><span class="sc">;</span></li><li>    <span class="s">}</span></li></ol></pre><p>An argument can be ignored by omitting the main part of the name from
a parameter declaration, leaving just a bare <code class="inline"><span class="i">$</span></code>
 sigil.  For example,</p>
<pre class="verbatim"><ol><li><a name="foo"></a>    sub <span class="m">foo ($first, $, $third)</span> <span class="s">{</span></li><li>	<a class="l_k" href="functions/return.html">return</a> <span class="q">&quot;first=$first, third=$third&quot;</span><span class="sc">;</span></li><li>    <span class="s">}</span></li></ol></pre><p>Although the ignored argument doesn't go into a variable, it is still
mandatory for the caller to pass it.</p>
<p>A positional parameter is made optional by giving a default value,
separated from the parameter name by <code class="inline">=</code>
:</p>
<pre class="verbatim"><ol><li><a name="foo"></a>    sub <span class="m">foo ($left, $right = 0)</span> <span class="s">{</span></li><li>	<a class="l_k" href="functions/return.html">return</a> <span class="i">$left</span> + <span class="i">$right</span><span class="sc">;</span></li><li>    <span class="s">}</span></li></ol></pre><p>The above subroutine may be called with either one or two arguments.
The default value expression is evaluated when the subroutine is called,
so it may provide different default values for different calls.  It is
only evaluated if the argument was actually omitted from the call.
For example,</p>
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/my.html">my</a> <span class="i">$auto_id</span> = <span class="n">0</span><span class="sc">;</span></li><li><a name="foo"></a>    sub <span class="m">foo ($thing, $id = $auto_id++)</span> <span class="s">{</span></li><li>	<a class="l_k" href="functions/print.html">print</a> <span class="q">&quot;$thing has ID $id&quot;</span><span class="sc">;</span></li><li>    <span class="s">}</span></li></ol></pre><p>automatically assigns distinct sequential IDs to things for which no
ID was supplied by the caller.  A default value expression may also
refer to parameters earlier in the signature, making the default for
one parameter vary according to the earlier parameters.  For example,</p>
<pre class="verbatim"><ol><li><a name="foo"></a>    sub <span class="m">foo ($first_name, $surname, $nickname = $first_name)</span> <span class="s">{</span></li><li>	<a class="l_k" href="functions/print.html">print</a> <span class="q">&quot;$first_name $surname is known as \&quot;$nickname\&quot;&quot;</span><span class="sc">;</span></li><li>    <span class="s">}</span></li></ol></pre><p>An optional parameter can be nameless just like a mandatory parameter.
For example,</p>
<pre class="verbatim"><ol><li><a name="foo"></a>    sub <span class="m">foo ($thing, $ = 1)</span> <span class="s">{</span></li><li>	<a class="l_k" href="functions/print.html">print</a> <span class="i">$thing</span><span class="sc">;</span></li><li>    <span class="s">}</span></li></ol></pre><p>The parameter's default value will still be evaluated if the corresponding
argument isn't supplied, even though the value won't be stored anywhere.
This is in case evaluating it has important side effects.  However, it
will be evaluated in void context, so if it doesn't have side effects
and is not trivial it will generate a warning if the "void" warning
category is enabled.  If a nameless optional parameter's default value
is not important, it may be omitted just as the parameter's name was:</p>
<pre class="verbatim"><ol><li><a name="foo"></a>    sub <span class="m">foo ($thing, $=)</span> <span class="s">{</span></li><li>	<a class="l_k" href="functions/print.html">print</a> <span class="i">$thing</span><span class="sc">;</span></li><li>    <span class="s">}</span></li></ol></pre><p>Optional positional parameters must come after all mandatory positional
parameters.  (If there are no mandatory positional parameters then an
optional positional parameters can be the first thing in the signature.)
If there are multiple optional positional parameters and not enough
arguments are supplied to fill them all, they will be filled from left
to right.</p>
<p>After positional parameters, additional arguments may be captured in a
slurpy parameter.  The simplest form of this is just an array variable:</p>
<pre class="verbatim"><ol><li><a name="foo"></a>    sub <span class="m">foo ($filter, @inputs)</span> <span class="s">{</span></li><li>	<a class="l_k" href="functions/print.html">print</a> <span class="i">$filter</span>-&gt;<span class="s">(</span><span class="i">$_</span><span class="s">)</span> <a class="l_k" href="functions/foreach.html">foreach</a> <span class="i">@inputs</span><span class="sc">;</span></li><li>    <span class="s">}</span></li></ol></pre><p>With a slurpy parameter in the signature, there is no upper limit on how
many arguments may be passed.  A slurpy array parameter may be nameless
just like a positional parameter, in which case its only effect is to
turn off the argument limit that would otherwise apply:</p>
<pre class="verbatim"><ol><li><a name="foo"></a>    sub <span class="m">foo ($thing, @)</span> <span class="s">{</span></li><li>	<a class="l_k" href="functions/print.html">print</a> <span class="i">$thing</span><span class="sc">;</span></li><li>    <span class="s">}</span></li></ol></pre><p>A slurpy parameter may instead be a hash, in which case the arguments
available to it are interpreted as alternating keys and values.
There must be as many keys as values: if there is an odd argument then
an exception will be thrown.  Keys will be stringified, and if there are
duplicates then the later instance takes precedence over the earlier,
as with standard hash construction.</p>
<pre class="verbatim"><ol><li><a name="foo"></a>    sub <span class="m">foo ($filter, %inputs)</span> <span class="s">{</span></li><li>	<a class="l_k" href="functions/print.html">print</a> <span class="i">$filter</span>-&gt;<span class="s">(</span><span class="i">$_</span><span class="cm">,</span> <span class="i">$inputs</span>{<span class="i">$_</span>}<span class="s">)</span> <a class="l_k" href="functions/foreach.html">foreach</a> <a class="l_k" href="functions/sort.html">sort</a> <a class="l_k" href="functions/keys.html">keys</a> <span class="i">%inputs</span><span class="sc">;</span></li><li>    <span class="s">}</span></li></ol></pre><p>A slurpy hash parameter may be nameless just like other kinds of
parameter.  It still insists that the number of arguments available to
it be even, even though they're not being put into a variable.</p>
<pre class="verbatim"><ol><li><a name="foo"></a>    sub <span class="m">foo ($thing, %)</span> <span class="s">{</span></li><li>	<a class="l_k" href="functions/print.html">print</a> <span class="i">$thing</span><span class="sc">;</span></li><li>    <span class="s">}</span></li></ol></pre><p>A slurpy parameter, either array or hash, must be the last thing in the
signature.  It may follow mandatory and optional positional parameters;
it may also be the only thing in the signature.  Slurpy parameters cannot
have default values: if no arguments are supplied for them then you get
an empty array or empty hash.</p>
<p>A signature may be entirely empty, in which case all it does is check
that the caller passed no arguments:</p>
<pre class="verbatim"><ol><li><a name="foo"></a>    sub <span class="m">foo ()</span> <span class="s">{</span></li><li>	<a class="l_k" href="functions/return.html">return</a> <span class="n">123</span><span class="sc">;</span></li><li>    <span class="s">}</span></li></ol></pre><p>When using a signature, the arguments are still available in the special
array variable <code class="inline"><span class="i">@_</span></code>
, in addition to the lexical variables of the
signature.  There is a difference between the two ways of accessing the
arguments: <code class="inline"><span class="i">@_</span></code>
 <i>aliases</i> the arguments, but the signature variables
get <i>copies</i> of the arguments.  So writing to a signature variable
only changes that variable, and has no effect on the caller's variables,
but writing to an element of <code class="inline"><span class="i">@_</span></code>
 modifies whatever the caller used to
supply that argument.</p>
<p>There is a potential syntactic ambiguity between signatures and prototypes
(see <a href="#Prototypes">Prototypes</a>), because both start with an opening parenthesis and
both can appear in some of the same places, such as just after the name
in a subroutine declaration.  For historical reasons, when signatures
are not enabled, any opening parenthesis in such a context will trigger
very forgiving prototype parsing.  Most signatures will be interpreted
as prototypes in those circumstances, but won't be valid prototypes.
(A valid prototype cannot contain any alphabetic character.)  This will
lead to somewhat confusing error messages.</p>
<p>To avoid ambiguity, when signatures are enabled the special syntax
for prototypes is disabled.  There is no attempt to guess whether a
parenthesised group was intended to be a prototype or a signature.
To give a subroutine a prototype under these circumstances, use a
<a href="attributes.html#Built-in-Attributes">prototype attribute</a>.  For example,</p>
<pre class="verbatim"><ol><li><a name="foo"></a>    sub <span class="m">foo</span> <span class="co">:</span><span class="q">prototype($)</span> <span class="s">{</span> <span class="i">$_</span>[<span class="n">0</span>] <span class="s">}</span></li></ol></pre><p>It is entirely possible for a subroutine to have both a prototype and
a signature.  They do different jobs: the prototype affects compilation
of calls to the subroutine, and the signature puts argument values into
lexical variables at runtime.  You can therefore write</p>
<pre class="verbatim"><ol><li><a name="foo"></a>    sub <span class="m">foo ($left, $right)</span> <span class="co">:</span> <span class="q">prototype($$)</span> <span class="s">{</span></li><li>	<a class="l_k" href="functions/return.html">return</a> <span class="i">$left</span> + <span class="i">$right</span><span class="sc">;</span></li><li>    <span class="s">}</span></li></ol></pre><p>The prototype attribute, and any other attributes, come after 
the signature.</p>
<a name="Private-Variables-via-my()"></a><h2>Private Variables via my()
    
 </h2>
<p>Synopsis:</p>
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/my.html">my</a> <span class="i">$foo</span><span class="sc">;</span>	    	<span class="c"># declare $foo lexically local</span></li><li>    <a class="l_k" href="functions/my.html">my</a> <span class="s">(</span><span class="i">@wid</span><span class="cm">,</span> <span class="i">%get</span><span class="s">)</span><span class="sc">;</span> 	<span class="c"># declare list of variables local</span></li><li>    <a class="l_k" href="functions/my.html">my</a> <span class="i">$foo</span> = <span class="q">&quot;flurp&quot;</span><span class="sc">;</span>	<span class="c"># declare $foo lexical, and init it</span></li><li>    <a class="l_k" href="functions/my.html">my</a> <span class="i">@oof</span> = <span class="i">@bar</span><span class="sc">;</span>	<span class="c"># declare @oof lexical, and init it</span></li><li>    <a class="l_k" href="functions/my.html">my</a> <span class="i">$x</span> <span class="co">:</span> <span class="w">Foo</span> = <span class="i">$y</span><span class="sc">;</span>	<span class="c"># similar, with an attribute applied</span></li></ol></pre><p><b>WARNING</b>: The use of attribute lists on <code class="inline"><a class="l_k" href="functions/my.html">my</a></code> declarations is still
evolving.  The current semantics and interface are subject to change.
See <a href="attributes.html">attributes</a> and <a href="Attribute/Handlers.html">Attribute::Handlers</a>.</p>
<p>The <code class="inline"><a class="l_k" href="functions/my.html">my</a></code> operator declares the listed variables to be lexically
confined to the enclosing block, conditional
(<code class="inline">if</code>
/<code class="inline">unless</code>
/<code class="inline">elsif</code>
/<code class="inline">else</code>
), loop
(<code class="inline">for</code>
/<code class="inline">foreach</code>
/<code class="inline">while</code>
/<code class="inline">until</code>
/<code class="inline"><a class="l_k" href="functions/continue.html">continue</a></code>), subroutine, <code class="inline"><a class="l_k" href="functions/eval.html">eval</a></code>,
or <code class="inline"><a class="l_k" href="functions/do.html">do</a></code>/<code class="inline"><a class="l_k" href="functions/require.html">require</a></code>/<code class="inline"><a class="l_k" href="functions/use.html">use</a></code>'d file.  If more than one value is listed, the
list must be placed in parentheses.  All listed elements must be
legal lvalues.  Only alphanumeric identifiers may be lexically
scoped--magical built-ins like <code class="inline"><span class="i">$/</span></code>
 must currently be <code class="inline"><a class="l_k" href="functions/local.html">local</a></code>ized
with <code class="inline"><a class="l_k" href="functions/local.html">local</a></code> instead.</p>
<p>Unlike dynamic variables created by the <code class="inline"><a class="l_k" href="functions/local.html">local</a></code> operator, lexical
variables declared with <code class="inline"><a class="l_k" href="functions/my.html">my</a></code> are totally hidden from the outside
world, including any called subroutines.  This is true if it's the
same subroutine called from itself or elsewhere--every call gets
its own copy.
</p>
<p>This doesn't mean that a <code class="inline"><a class="l_k" href="functions/my.html">my</a></code> variable declared in a statically
enclosing lexical scope would be invisible.  Only dynamic scopes
are cut off.   For example, the <code class="inline"><span class="i">bumpx</span><span class="s">(</span><span class="s">)</span></code>
 function below has access
to the lexical $x variable because both the <code class="inline"><a class="l_k" href="functions/my.html">my</a></code> and the <code class="inline"><a class="l_k" href="functions/sub.html">sub</a></code>
occurred at the same scope, presumably file scope.</p>
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/my.html">my</a> <span class="i">$x</span> = <span class="n">10</span><span class="sc">;</span></li><li><a name="bumpx"></a>    sub <span class="m">bumpx</span> <span class="s">{</span> <span class="i">$x</span>++ <span class="s">}</span></li></ol></pre><p>An <code class="inline"><a class="l_k" href="functions/eval.html">eval()</a></code>, however, can see lexical variables of the scope it is
being evaluated in, so long as the names aren't hidden by declarations within
the <code class="inline"><a class="l_k" href="functions/eval.html">eval()</a></code> itself.  See <a href="perlref.html">perlref</a>.
</p>
<p>The parameter list to my() may be assigned to if desired, which allows you
to initialize your variables.  (If no initializer is given for a
particular variable, it is created with the undefined value.)  Commonly
this is used to name input parameters to a subroutine.  Examples:</p>
<pre class="verbatim"><ol><li>    $arg = "fred";	  # "global" variable</li><li>    $n = cube_root(27);</li><li>    print "$arg thinks the root is $n\n";</li><li> fred thinks the root is 3</li><li></li><li>    sub cube_root {</li><li>	my $arg = shift;  # name doesn't matter</li><li>	$arg **= 1/3;</li><li>	return $arg;</li><li>    }</li></ol></pre><p>The <code class="inline"><a class="l_k" href="functions/my.html">my</a></code> is simply a modifier on something you might assign to.  So when
you do assign to variables in its argument list, <code class="inline"><a class="l_k" href="functions/my.html">my</a></code> doesn't
change whether those variables are viewed as a scalar or an array.  So</p>
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/my.html">my</a> <span class="s">(</span><span class="i">$foo</span><span class="s">)</span> = <span class="q">&lt;STDIN&gt;</span><span class="sc">;</span>		<span class="c"># WRONG?</span></li><li>    <a class="l_k" href="functions/my.html">my</a> <span class="i">@FOO</span> = <span class="q">&lt;STDIN&gt;</span><span class="sc">;</span></li></ol></pre><p>both supply a list context to the right-hand side, while</p>
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/my.html">my</a> <span class="i">$foo</span> = <span class="q">&lt;STDIN&gt;</span><span class="sc">;</span></li></ol></pre><p>supplies a scalar context.  But the following declares only one variable:</p>
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/my.html">my</a> <span class="i">$foo</span><span class="cm">,</span> <span class="i">$bar</span> = <span class="n">1</span><span class="sc">;</span>			<span class="c"># WRONG</span></li></ol></pre><p>That has the same effect as</p>
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/my.html">my</a> <span class="i">$foo</span><span class="sc">;</span></li><li>    <span class="i">$bar</span> = <span class="n">1</span><span class="sc">;</span></li></ol></pre><p>The declared variable is not introduced (is not visible) until after
the current statement.  Thus,</p>
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/my.html">my</a> <span class="i">$x</span> = <span class="i">$x</span><span class="sc">;</span></li></ol></pre><p>can be used to initialize a new $x with the value of the old $x, and
the expression</p>
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/my.html">my</a> <span class="i">$x</span> = <span class="n">123</span> and <span class="i">$x</span> == <span class="n">123</span></li></ol></pre><p>is false unless the old $x happened to have the value <code class="inline"><span class="n">123</span></code>
.</p>
<p>Lexical scopes of control structures are not bounded precisely by the
braces that delimit their controlled blocks; control expressions are
part of that scope, too.  Thus in the loop</p>
<pre class="verbatim"><ol><li>    while <span class="s">(</span><a class="l_k" href="functions/my.html">my</a> <span class="i">$line</span> = &lt;&gt;<span class="s">)</span> <span class="s">{</span></li><li>        <span class="i">$line</span> = <a class="l_k" href="functions/lc.html">lc</a> <span class="i">$line</span><span class="sc">;</span></li><li>    <span class="s">}</span> <a class="l_k" href="functions/continue.html">continue</a> <span class="s">{</span></li><li>        <a class="l_k" href="functions/print.html">print</a> <span class="i">$line</span><span class="sc">;</span></li><li>    <span class="s">}</span></li></ol></pre><p>the scope of $line extends from its declaration throughout the rest of
the loop construct (including the <code class="inline"><a class="l_k" href="functions/continue.html">continue</a></code> clause), but not beyond
it.  Similarly, in the conditional</p>
<pre class="verbatim"><ol><li>    if <span class="s">(</span><span class="s">(</span><a class="l_k" href="functions/my.html">my</a> <span class="i">$answer</span> = <span class="q">&lt;STDIN&gt;</span><span class="s">)</span> =~ <span class="q">/^yes$/i</span><span class="s">)</span> <span class="s">{</span></li><li>        <span class="i">user_agrees</span><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li>    <span class="s">}</span> elsif <span class="s">(</span><span class="i">$answer</span> =~ <span class="q">/^no$/i</span><span class="s">)</span> <span class="s">{</span></li><li>        <span class="i">user_disagrees</span><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li>    <span class="s">}</span> else <span class="s">{</span></li><li>	<a class="l_k" href="functions/chomp.html">chomp</a> <span class="i">$answer</span><span class="sc">;</span></li><li>        <a class="l_k" href="functions/die.html">die</a> <span class="q">&quot;&#39;$answer&#39; is neither &#39;yes&#39; nor &#39;no&#39;&quot;</span><span class="sc">;</span></li><li>    <span class="s">}</span></li></ol></pre><p>the scope of $answer extends from its declaration through the rest
of that conditional, including any <code class="inline">elsif</code>
 and <code class="inline">else</code>
 clauses, 
but not beyond it.  See <a href="perlsyn.html#Simple-Statements">Simple Statements in perlsyn</a> for information
on the scope of variables in statements with modifiers.</p>
<p>The <code class="inline">foreach</code>
 loop defaults to scoping its index variable dynamically
in the manner of <code class="inline"><a class="l_k" href="functions/local.html">local</a></code>.  However, if the index variable is
prefixed with the keyword <code class="inline"><a class="l_k" href="functions/my.html">my</a></code>, or if there is already a lexical
by that name in scope, then a new lexical is created instead.  Thus
in the loop
 </p>
<pre class="verbatim"><ol><li>    for <a class="l_k" href="functions/my.html">my</a> <span class="i">$i</span> <span class="s">(</span><span class="n">1</span><span class="cm">,</span> <span class="n">2</span><span class="cm">,</span> <span class="n">3</span><span class="s">)</span> <span class="s">{</span></li><li>        <span class="i">some_function</span><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li>    <span class="s">}</span></li></ol></pre><p>the scope of $i extends to the end of the loop, but not beyond it,
rendering the value of $i inaccessible within <code class="inline"><span class="i">some_function</span><span class="s">(</span><span class="s">)</span></code>
.
 </p>
<p>Some users may wish to encourage the use of lexically scoped variables.
As an aid to catching implicit uses to package variables,
which are always global, if you say</p>
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/use.html">use</a> <span class="w">strict</span> <span class="q">&#39;vars&#39;</span><span class="sc">;</span></li></ol></pre><p>then any variable mentioned from there to the end of the enclosing
block must either refer to a lexical variable, be predeclared via
<code class="inline"><a class="l_k" href="functions/our.html">our</a></code> or <code class="inline"><a class="l_k" href="functions/use.html">use</a> <span class="w">vars</span></code>
, or else must be fully qualified with the package name.
A compilation error results otherwise.  An inner block may countermand
this with <code class="inline"><a class="l_k" href="functions/no.html">no</a> <span class="w">strict</span> <span class="q">&#39;vars&#39;</span></code>
.</p>
<p>A <code class="inline"><a class="l_k" href="functions/my.html">my</a></code> has both a compile-time and a run-time effect.  At compile
time, the compiler takes notice of it.  The principal usefulness
of this is to quiet <code class="inline"><a class="l_k" href="functions/use.html">use</a> <span class="w">strict</span> <span class="q">&#39;vars&#39;</span></code>
, but it is also essential
for generation of closures as detailed in <a href="perlref.html">perlref</a>.  Actual
initialization is delayed until run time, though, so it gets executed
at the appropriate time, such as each time through a loop, for
example.</p>
<p>Variables declared with <code class="inline"><a class="l_k" href="functions/my.html">my</a></code> are not part of any package and are therefore
never fully qualified with the package name.  In particular, you're not
allowed to try to make a package variable (or other global) lexical:</p>
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/my.html">my</a> <span class="i">$pack::var</span><span class="sc">;</span>	<span class="c"># ERROR!  Illegal syntax</span></li></ol></pre><p>In fact, a dynamic variable (also known as package or global variables)
are still accessible using the fully qualified <code class="inline"><span class="w">::</span></code>
 notation even while a
lexical of the same name is also visible:</p>
<pre class="verbatim"><ol><li><a name="package-main"></a>    package <span class="i">main</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/local.html">local</a> <span class="i">$x</span> = <span class="n">10</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/my.html">my</a>    <span class="i">$x</span> = <span class="n">20</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/print.html">print</a> <span class="q">&quot;$x and $::x\n&quot;</span><span class="sc">;</span></li></ol></pre><p>That will print out <code class="inline"><span class="n">20</span></code>
 and <code class="inline"><span class="n">10</span></code>
.</p>
<p>You may declare <code class="inline"><a class="l_k" href="functions/my.html">my</a></code> variables at the outermost scope of a file
to hide any such identifiers from the world outside that file.  This
is similar in spirit to C's static variables when they are used at
the file level.  To do this with a subroutine requires the use of
a closure (an anonymous function that accesses enclosing lexicals).
If you want to create a private subroutine that cannot be called
from outside that block, it can declare a lexical variable containing
an anonymous sub reference:</p>
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/my.html">my</a> <span class="i">$secret_version</span> = <span class="q">&#39;1.001-beta&#39;</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/my.html">my</a> <span class="i">$secret_sub</span> = <a class="l_k" href="functions/sub.html">sub</a> <span class="s">{</span> <a class="l_k" href="functions/print.html">print</a> <span class="i">$secret_version</span> <span class="s">}</span><span class="sc">;</span></li><li>    <span class="i">&amp;$secret_sub</span><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>As long as the reference is never returned by any function within the
module, no outside module can see the subroutine, because its name is not in
any package's symbol table.  Remember that it's not <i>REALLY</i> called
<code class="inline"><span class="i">$some_pack::secret_version</span></code>
 or anything; it's just $secret_version,
unqualified and unqualifiable.</p>
<p>This does not work with object methods, however; all object methods
have to be in the symbol table of some package to be found.  See
<a href="perlref.html#Function-Templates">Function Templates in perlref</a> for something of a work-around to
this.</p>
<a name="Persistent-Private-Variables"></a><h2>Persistent Private Variables
     </h2>
<p>There are two ways to build persistent private variables in Perl 5.10.
First, you can simply use the <code class="inline"><a class="l_k" href="functions/state.html">state</a></code> feature.  Or, you can use closures,
if you want to stay compatible with releases older than 5.10.</p>
<a name="Persistent-variables-via-state()"></a><h3>Persistent variables via state()</h3>
<p>Beginning with Perl 5.10.0, you can declare variables with the <code class="inline"><a class="l_k" href="functions/state.html">state</a></code>
keyword in place of <code class="inline"><a class="l_k" href="functions/my.html">my</a></code>.  For that to work, though, you must have
enabled that feature beforehand, either by using the <code class="inline"><span class="w">feature</span></code>
 pragma, or
by using <code class="inline">-<span class="w">E</span></code>
 on one-liners (see <a href="feature.html">feature</a>).  Beginning with Perl 5.16,
the <code class="inline"><span class="w">CORE::state</span></code>
 form does not require the
<code class="inline"><span class="w">feature</span></code>
 pragma.</p>
<p>The <code class="inline"><a class="l_k" href="functions/state.html">state</a></code> keyword creates a lexical variable (following the same scoping
rules as <code class="inline"><a class="l_k" href="functions/my.html">my</a></code>) that persists from one subroutine call to the next.  If a
state variable resides inside an anonymous subroutine, then each copy of
the subroutine has its own copy of the state variable.  However, the value
of the state variable will still persist between calls to the same copy of
the anonymous subroutine.  (Don't forget that <code class="inline"><a class="l_k" href="functions/sub.html">sub</a> <span class="s">{</span> ... <span class="s">}</span></code>
 creates a new
subroutine each time it is executed.)</p>
<p>For example, the following code maintains a private counter, incremented
each time the gimme_another() function is called:</p>
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/use.html">use</a> <span class="w">feature</span> <span class="q">'state'</span><span class="sc">;</span></li><li><a name="gimme_another"></a>    sub <span class="m">gimme_another</span> <span class="s">{</span> <span class="w">state</span> <span class="i">$x</span><span class="sc">;</span> <a class="l_k" href="functions/return.html">return</a> ++<span class="i">$x</span> <span class="s">}</span></li></ol></pre><p>And this example uses anonymous subroutines to create separate counters:</p>
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/use.html">use</a> <span class="w">feature</span> <span class="q">&#39;state&#39;</span><span class="sc">;</span></li><li><a name="create_counter"></a>    sub <span class="m">create_counter</span> <span class="s">{</span></li><li>	<a class="l_k" href="functions/return.html">return</a> <a class="l_k" href="functions/sub.html">sub</a> <span class="s">{</span> <span class="w">state</span> <span class="i">$x</span><span class="sc">;</span> <a class="l_k" href="functions/return.html">return</a> ++<span class="i">$x</span> <span class="s">}</span></li><li>    <span class="s">}</span></li></ol></pre><p>Also, since <code class="inline"><span class="i">$x</span></code>
 is lexical, it can't be reached or modified by any Perl
code outside.</p>
<p>When combined with variable declaration, simple scalar assignment to <code class="inline"><a class="l_k" href="functions/state.html">state</a></code>
variables (as in <code class="inline"><span class="w">state</span> <span class="i">$x</span> = <span class="n">42</span></code>
) is executed only the first time.  When such
statements are evaluated subsequent times, the assignment is ignored.  The
behavior of this sort of assignment to non-scalar variables is undefined.</p>
<a name="Persistent-variables-with-closures"></a><h3>Persistent variables with closures</h3>
<p>Just because a lexical variable is lexically (also called statically)
scoped to its enclosing block, <code class="inline"><a class="l_k" href="functions/eval.html">eval</a></code>, or <code class="inline"><a class="l_k" href="functions/do.html">do</a></code> FILE, this doesn't mean that
within a function it works like a C static.  It normally works more
like a C auto, but with implicit garbage collection.</p>
<p>Unlike local variables in C or C++, Perl's lexical variables don't
necessarily get recycled just because their scope has exited.
If something more permanent is still aware of the lexical, it will
stick around.  So long as something else references a lexical, that
lexical won't be freed--which is as it should be.  You wouldn't want
memory being free until you were done using it, or kept around once you
were done.  Automatic garbage collection takes care of this for you.</p>
<p>This means that you can pass back or save away references to lexical
variables, whereas to return a pointer to a C auto is a grave error.
It also gives us a way to simulate C's function statics.  Here's a
mechanism for giving a function private variables with both lexical
scoping and a static lifetime.  If you do want to create something like
C's static variables, just enclose the whole function in an extra block,
and put the static variable outside the function but in the block.</p>
<pre class="verbatim"><ol><li>    <span class="s">{</span></li><li>	<a class="l_k" href="functions/my.html">my</a> <span class="i">$secret_val</span> = <span class="n">0</span><span class="sc">;</span></li><li><a name="gimme_another"></a>	sub <span class="m">gimme_another</span> <span class="s">{</span></li><li>	    <a class="l_k" href="functions/return.html">return</a> ++<span class="i">$secret_val</span><span class="sc">;</span></li><li>	<span class="s">}</span></li><li>    <span class="s">}</span></li><li>    <span class="c"># $secret_val now becomes unreachable by the outside</span></li><li>    <span class="c"># world, but retains its value between calls to gimme_another</span></li></ol></pre><p>If this function is being sourced in from a separate file
via <code class="inline"><a class="l_k" href="functions/require.html">require</a></code> or <code class="inline"><a class="l_k" href="functions/use.html">use</a></code>, then this is probably just fine.  If it's
all in the main program, you'll need to arrange for the <code class="inline"><a class="l_k" href="functions/my.html">my</a></code>
to be executed early, either by putting the whole block above
your main program, or more likely, placing merely a <code class="inline">BEGIN</code>

code block around it to make sure it gets executed before your program
starts to run:</p>
<pre class="verbatim"><ol><li>    BEGIN <span class="s">{</span></li><li>	<a class="l_k" href="functions/my.html">my</a> <span class="i">$secret_val</span> = <span class="n">0</span><span class="sc">;</span></li><li><a name="gimme_another"></a>	sub <span class="m">gimme_another</span> <span class="s">{</span></li><li>	    <a class="l_k" href="functions/return.html">return</a> ++<span class="i">$secret_val</span><span class="sc">;</span></li><li>	<span class="s">}</span></li><li>    <span class="s">}</span></li></ol></pre><p>See <a href="perlmod.html#BEGIN%2c-UNITCHECK%2c-CHECK%2c-INIT-and-END">BEGIN, UNITCHECK, CHECK, INIT and END in perlmod</a> about the
special triggered code blocks, <code class="inline">BEGIN</code>
, <code class="inline">UNITCHECK</code>
, <code class="inline">CHECK</code>
,
<code class="inline">INIT</code>
 and <code class="inline">END</code>
.</p>
<p>If declared at the outermost scope (the file scope), then lexicals
work somewhat like C's file statics.  They are available to all
functions in that same file declared below them, but are inaccessible
from outside that file.  This strategy is sometimes used in modules
to create private variables that the whole module can see.</p>
<a name="Temporary-Values-via-local()"></a><h2>Temporary Values via local()
   
</h2>
<p><b>WARNING</b>: In general, you should be using <code class="inline"><a class="l_k" href="functions/my.html">my</a></code> instead of <code class="inline"><a class="l_k" href="functions/local.html">local</a></code>, because
it's faster and safer.  Exceptions to this include the global punctuation
variables, global filehandles and formats, and direct manipulation of the
Perl symbol table itself.  <code class="inline"><a class="l_k" href="functions/local.html">local</a></code> is mostly used when the current value
of a variable must be visible to called subroutines.</p>
<p>Synopsis:</p>
<pre class="verbatim"><ol><li>    <span class="c"># localization of values</span></li><li></li><li>    <a class="l_k" href="functions/local.html">local</a> <span class="i">$foo</span><span class="sc">;</span>		       <span class="c"># make $foo dynamically local</span></li><li>    <a class="l_k" href="functions/local.html">local</a> <span class="s">(</span><span class="i">@wid</span><span class="cm">,</span> <span class="i">%get</span><span class="s">)</span><span class="sc">;</span>	       <span class="c"># make list of variables local</span></li><li>    <a class="l_k" href="functions/local.html">local</a> <span class="i">$foo</span> = <span class="q">&quot;flurp&quot;</span><span class="sc">;</span>      <span class="c"># make $foo dynamic, and init it</span></li><li>    <a class="l_k" href="functions/local.html">local</a> <span class="i">@oof</span> = <span class="i">@bar</span><span class="sc">;</span>	       <span class="c"># make @oof dynamic, and init it</span></li><li></li><li>    <a class="l_k" href="functions/local.html">local</a> <span class="i">$hash</span>{<span class="w">key</span>} = <span class="q">&quot;val&quot;</span><span class="sc">;</span>  <span class="c"># sets a local value for this hash entry</span></li><li>    <a class="l_k" href="functions/delete.html">delete</a> <a class="l_k" href="functions/local.html">local</a> <span class="i">$hash</span>{<span class="w">key</span>}<span class="sc">;</span>   <span class="c"># delete this entry for the current block</span></li><li>    <a class="l_k" href="functions/local.html">local</a> <span class="s">(</span><span class="i">$cond</span> ? <span class="i">$v1</span> <span class="co">:</span> <span class="i">$v2</span><span class="s">)</span><span class="sc">;</span> <span class="c"># several types of lvalues support</span></li><li>			       <span class="c"># localization</span></li><li></li><li>    <span class="c"># localization of symbols</span></li><li></li><li>    <a class="l_k" href="functions/local.html">local</a> <span class="i">*FH</span><span class="sc">;</span>		       <span class="c"># localize $FH, @FH, %FH, &amp;FH  ...</span></li><li>    <a class="l_k" href="functions/local.html">local</a> <span class="i">*merlyn</span> = <span class="i">*randal</span><span class="sc">;</span>   <span class="c"># now $merlyn is really $randal, plus</span></li><li>                               <span class="c">#     @merlyn is really @randal, etc</span></li><li>    <a class="l_k" href="functions/local.html">local</a> <span class="i">*merlyn</span> = <span class="q">&#39;randal&#39;</span><span class="sc">;</span>  <span class="c"># SAME THING: promote &#39;randal&#39; to *randal</span></li><li>    <a class="l_k" href="functions/local.html">local</a> <span class="i">*merlyn</span> = \<span class="i">$randal</span><span class="sc">;</span>  <span class="c"># just alias $merlyn, not @merlyn etc</span></li></ol></pre><p>A <code class="inline"><a class="l_k" href="functions/local.html">local</a></code> modifies its listed variables to be "local" to the
enclosing block, <code class="inline"><a class="l_k" href="functions/eval.html">eval</a></code>, or <code class="inline"><a class="l_k" href="functions/do.html">do</a> <span class="w">FILE</span></code>
--and to <i>any subroutine
called from within that block</i>.  A <code class="inline"><a class="l_k" href="functions/local.html">local</a></code> just gives temporary
values to global (meaning package) variables.  It does <i>not</i> create
a local variable.  This is known as dynamic scoping.  Lexical scoping
is done with <code class="inline"><a class="l_k" href="functions/my.html">my</a></code>, which works more like C's auto declarations.</p>
<p>Some types of lvalues can be localized as well: hash and array elements
and slices, conditionals (provided that their result is always
localizable), and symbolic references.  As for simple variables, this
creates new, dynamically scoped values.</p>
<p>If more than one variable or expression is given to <code class="inline"><a class="l_k" href="functions/local.html">local</a></code>, they must be
placed in parentheses.  This operator works
by saving the current values of those variables in its argument list on a
hidden stack and restoring them upon exiting the block, subroutine, or
eval.  This means that called subroutines can also reference the local
variable, but not the global one.  The argument list may be assigned to if
desired, which allows you to initialize your local variables.  (If no
initializer is given for a particular variable, it is created with an
undefined value.)</p>
<p>Because <code class="inline"><a class="l_k" href="functions/local.html">local</a></code> is a run-time operator, it gets executed each time
through a loop.  Consequently, it's more efficient to localize your
variables outside the loop.</p>
<a name="Grammatical-note-on-local()"></a><h3>Grammatical note on local()
</h3>
<p>A <code class="inline"><a class="l_k" href="functions/local.html">local</a></code> is simply a modifier on an lvalue expression.  When you assign to
a <code class="inline"><a class="l_k" href="functions/local.html">local</a></code>ized variable, the <code class="inline"><a class="l_k" href="functions/local.html">local</a></code> doesn't change whether its list is viewed
as a scalar or an array.  So</p>
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/local.html">local</a><span class="s">(</span><span class="i">$foo</span><span class="s">)</span> = <span class="q">&lt;STDIN&gt;</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/local.html">local</a> <span class="i">@FOO</span> = <span class="q">&lt;STDIN&gt;</span><span class="sc">;</span></li></ol></pre><p>both supply a list context to the right-hand side, while</p>
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/local.html">local</a> <span class="i">$foo</span> = <span class="q">&lt;STDIN&gt;</span><span class="sc">;</span></li></ol></pre><p>supplies a scalar context.</p>
<a name="Localization-of-special-variables"></a><h3>Localization of special variables
</h3>
<p>If you localize a special variable, you'll be giving a new value to it,
but its magic won't go away.  That means that all side-effects related
to this magic still work with the localized value.</p>
<p>This feature allows code like this to work :</p>
<pre class="verbatim"><ol><li>    <span class="c"># Read the whole contents of FILE in $slurp</span></li><li>    <span class="s">{</span> <a class="l_k" href="functions/local.html">local</a> <span class="i">$/</span> = <a class="l_k" href="functions/undef.html">undef</a><span class="sc">;</span> <span class="i">$slurp</span> = <span class="q">&lt;FILE&gt;</span><span class="sc">;</span> <span class="s">}</span></li></ol></pre><p>Note, however, that this restricts localization of some values ; for
example, the following statement dies, as of perl 5.10.0, with an error
<i>Modification of a read-only value attempted</i>, because the $1 variable is
magical and read-only :</p>
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/local.html">local</a> <span class="i">$1</span> = <span class="n">2</span><span class="sc">;</span></li></ol></pre><p>One exception is the default scalar variable: starting with perl 5.14
<code class="inline"><a class="l_k" href="functions/local.html">local($_)</a></code> will always strip all magic from $_, to make it possible
to safely reuse $_ in a subroutine.</p>
<p><b>WARNING</b>: Localization of tied arrays and hashes does not currently
work as described.
This will be fixed in a future release of Perl; in the meantime, avoid
code that relies on any particular behavior of localising tied arrays
or hashes (localising individual elements is still okay).
See <a href="perl58delta.html#Localising-Tied-Arrays-and-Hashes-Is-Broken">Localising Tied Arrays and Hashes Is Broken in perl58delta</a> for more
details.
</p>
<a name="Localization-of-globs"></a><h3>Localization of globs
 </h3>
<p>The construct</p>
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/local.html">local</a> <span class="i">*name</span><span class="sc">;</span></li></ol></pre><p>creates a whole new symbol table entry for the glob <code class="inline"><span class="w">name</span></code>
 in the
current package.  That means that all variables in its glob slot ($name,
@name, %name, &amp;name, and the <code class="inline"><span class="w">name</span></code>
 filehandle) are dynamically reset.</p>
<p>This implies, among other things, that any magic eventually carried by
those variables is locally lost.  In other words, saying <code class="inline"><a class="l_k" href="functions/local.html">local</a> <span class="i">*/</span></code>

will not have any effect on the internal value of the input record
separator.</p>
<a name="Localization-of-elements-of-composite-types"></a><h3>Localization of elements of composite types
  </h3>
<p>It's also worth taking a moment to explain what happens when you
<code class="inline"><a class="l_k" href="functions/local.html">local</a></code>ize a member of a composite type (i.e. an array or hash element).
In this case, the element is <code class="inline"><a class="l_k" href="functions/local.html">local</a></code>ized <i>by name</i>.  This means that
when the scope of the <code class="inline"><a class="l_k" href="functions/local.html">local()</a></code> ends, the saved value will be
restored to the hash element whose key was named in the <code class="inline"><a class="l_k" href="functions/local.html">local()</a></code>, or
the array element whose index was named in the <code class="inline"><a class="l_k" href="functions/local.html">local()</a></code>.  If that
element was deleted while the <code class="inline"><a class="l_k" href="functions/local.html">local()</a></code> was in effect (e.g. by a
<code class="inline"><a class="l_k" href="functions/delete.html">delete()</a></code> from a hash or a <code class="inline"><a class="l_k" href="functions/shift.html">shift()</a></code> of an array), it will spring
back into existence, possibly extending an array and filling in the
skipped elements with <code class="inline"><a class="l_k" href="functions/undef.html">undef</a></code>.  For instance, if you say</p>
<pre class="verbatim"><ol><li>    <span class="i">%hash</span> = <span class="s">(</span> <span class="q">&#39;This&#39;</span> <span class="cm">=&gt;</span> <span class="q">&#39;is&#39;</span><span class="cm">,</span> <span class="q">&#39;a&#39;</span> <span class="cm">=&gt;</span> <span class="q">&#39;test&#39;</span> <span class="s">)</span><span class="sc">;</span></li><li>    <span class="i">@ary</span>  = <span class="s">(</span> <span class="n">0</span>..<span class="n">5</span> <span class="s">)</span><span class="sc">;</span></li><li>    <span class="s">{</span></li><li>         <a class="l_k" href="functions/local.html">local</a><span class="s">(</span><span class="i">$ary</span>[<span class="n">5</span>]<span class="s">)</span> = <span class="n">6</span><span class="sc">;</span></li><li>         <a class="l_k" href="functions/local.html">local</a><span class="s">(</span><span class="i">$hash</span>{<span class="q">&#39;a&#39;</span>}<span class="s">)</span> = <span class="q">&#39;drill&#39;</span><span class="sc">;</span></li><li>         while <span class="s">(</span><a class="l_k" href="functions/my.html">my</a> <span class="i">$e</span> = <a class="l_k" href="functions/pop.html">pop</a><span class="s">(</span><span class="i">@ary</span><span class="s">)</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;$e . . .\n&quot;</span><span class="sc">;</span></li><li>             <a class="l_k" href="functions/last.html">last</a> unless <span class="i">$e</span> &gt; <span class="n">3</span><span class="sc">;</span></li><li>         <span class="s">}</span></li><li>         if <span class="s">(</span><span class="i">@ary</span><span class="s">)</span> <span class="s">{</span></li><li>             <span class="i">$hash</span>{<span class="q">&#39;only a&#39;</span>} = <span class="q">&#39;test&#39;</span><span class="sc">;</span></li><li>             <a class="l_k" href="functions/delete.html">delete</a> <span class="i">$hash</span>{<span class="q">&#39;a&#39;</span>}<span class="sc">;</span></li><li>         <span class="s">}</span></li><li>    <span class="s">}</span></li><li>    <a class="l_k" href="functions/print.html">print</a> <a class="l_k" href="functions/join.html">join</a><span class="s">(</span><span class="q">&#39; &#39;</span><span class="cm">,</span> <a class="l_k" href="functions/map.html">map</a> <span class="s">{</span> <span class="q">&quot;$_ $hash{$_}&quot;</span> <span class="s">}</span> <a class="l_k" href="functions/sort.html">sort</a> <a class="l_k" href="functions/keys.html">keys</a> <span class="i">%hash</span><span class="s">)</span><span class="cm">,</span><span class="q">&quot;.\n&quot;</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/print.html">print</a> <span class="q">&quot;The array has &quot;</span><span class="cm">,</span><a class="l_k" href="functions/scalar.html">scalar</a><span class="s">(</span><span class="i">@ary</span><span class="s">)</span><span class="cm">,</span><span class="q">&quot; elements: &quot;</span><span class="cm">,</span></li><li>          <a class="l_k" href="functions/join.html">join</a><span class="s">(</span><span class="q">&#39;, &#39;</span><span class="cm">,</span> <a class="l_k" href="functions/map.html">map</a> <span class="s">{</span> <a class="l_k" href="functions/defined.html">defined</a> <span class="i">$_</span> ? <span class="i">$_</span> <span class="co">:</span> <span class="q">&#39;undef&#39;</span> <span class="s">}</span> <span class="i">@ary</span><span class="s">)</span><span class="cm">,</span><span class="q">&quot;\n&quot;</span><span class="sc">;</span></li></ol></pre><p>Perl will print</p>
<pre class="verbatim"><ol><li>    6 . . .</li><li>    4 . . .</li><li>    3 . . .</li><li>    This is a test only a test.</li><li>    The array has 6 elements: 0, 1, 2, undef, undef, 5</li></ol></pre><p>The behavior of local() on non-existent members of composite
types is subject to change in future.</p>
<a name="Localized-deletion-of-elements-of-composite-types"></a><h3>Localized deletion of elements of composite types
   </h3>
<p>You can use the <code class="inline"><a class="l_k" href="functions/delete.html">delete</a> <a class="l_k" href="functions/local.html">local</a> <span class="i">$array</span>[<span class="i">$idx</span>]</code>
 and <code class="inline"><a class="l_k" href="functions/delete.html">delete</a> <a class="l_k" href="functions/local.html">local</a> <span class="i">$hash</span>{<span class="w">key</span>}</code>

constructs to delete a composite type entry for the current block and restore
it when it ends.  They return the array/hash value before the localization,
which means that they are respectively equivalent to</p>
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/do.html">do</a> <span class="s">{</span></li><li>        <a class="l_k" href="functions/my.html">my</a> <span class="i">$val</span> = <span class="i">$array</span>[<span class="i">$idx</span>]<span class="sc">;</span></li><li>        <a class="l_k" href="functions/local.html">local</a>  <span class="i">$array</span>[<span class="i">$idx</span>]<span class="sc">;</span></li><li>        <a class="l_k" href="functions/delete.html">delete</a> <span class="i">$array</span>[<span class="i">$idx</span>]<span class="sc">;</span></li><li>        <span class="i">$val</span></li><li>    <span class="s">}</span></li></ol></pre><p>and</p>
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/do.html">do</a> <span class="s">{</span></li><li>        <a class="l_k" href="functions/my.html">my</a> <span class="i">$val</span> = <span class="i">$hash</span>{<span class="w">key</span>}<span class="sc">;</span></li><li>        <a class="l_k" href="functions/local.html">local</a>  <span class="i">$hash</span>{<span class="w">key</span>}<span class="sc">;</span></li><li>        <a class="l_k" href="functions/delete.html">delete</a> <span class="i">$hash</span>{<span class="w">key</span>}<span class="sc">;</span></li><li>        <span class="i">$val</span></li><li>    <span class="s">}</span></li></ol></pre><p>except that for those the <code class="inline"><a class="l_k" href="functions/local.html">local</a></code> is
scoped to the <code class="inline"><a class="l_k" href="functions/do.html">do</a></code> block.  Slices are
also accepted.</p>
<pre class="verbatim"><ol><li>    my %hash = (</li><li>     a =&gt; [ 7, 8, 9 ],</li><li>     b =&gt; 1,</li><li>    )</li><li></li><li>    {</li><li>     my $a = delete local $hash{a};</li><li>     # $a is [ 7, 8, 9 ]</li><li>     # %hash is (b =&gt; 1)</li><li></li><li>     {</li><li>      my @nums = delete local @$a[0, 2]</li><li>      # @nums is (7, 9)</li><li>      # $a is [ undef, 8 ]</li><li></li><li>      $a[0] = 999; # will be erased when the scope ends</li><li>     }</li><li>     # $a is back to [ 7, 8, 9 ]</li><li></li><li>    }</li><li>    # %hash is back to its original state</li></ol></pre><a name="Lvalue-subroutines"></a><h2>Lvalue subroutines
 </h2>
<p>It is possible to return a modifiable value from a subroutine.
To do this, you have to declare the subroutine to return an lvalue.</p>
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/my.html">my</a> <span class="i">$val</span><span class="sc">;</span></li><li><a name="canmod"></a>    sub <span class="m">canmod</span> <span class="co">:</span> <span class="w">lvalue</span> <span class="s">{</span></li><li>	<span class="i">$val</span><span class="sc">;</span>  <span class="c"># or:  return $val;</span></li><li>    <span class="s">}</span></li><li><a name="nomod"></a>    sub <span class="m">nomod</span> <span class="s">{</span></li><li>	<span class="i">$val</span><span class="sc">;</span></li><li>    <span class="s">}</span></li><li></li><li>    <span class="i">canmod</span><span class="s">(</span><span class="s">)</span> = <span class="n">5</span><span class="sc">;</span>   <span class="c"># assigns to $val</span></li><li>    <span class="i">nomod</span><span class="s">(</span><span class="s">)</span>  = <span class="n">5</span><span class="sc">;</span>   <span class="c"># ERROR</span></li></ol></pre><p>The scalar/list context for the subroutine and for the right-hand
side of assignment is determined as if the subroutine call is replaced
by a scalar.  For example, consider:</p>
<pre class="verbatim"><ol><li>    <span class="i">data</span><span class="s">(</span><span class="n">2</span><span class="cm">,</span><span class="n">3</span><span class="s">)</span> = <span class="i">get_data</span><span class="s">(</span><span class="n">3</span><span class="cm">,</span><span class="n">4</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>Both subroutines here are called in a scalar context, while in:</p>
<pre class="verbatim"><ol><li>    <span class="s">(</span><span class="i">data</span><span class="s">(</span><span class="n">2</span><span class="cm">,</span><span class="n">3</span><span class="s">)</span><span class="s">)</span> = <span class="i">get_data</span><span class="s">(</span><span class="n">3</span><span class="cm">,</span><span class="n">4</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>and in:</p>
<pre class="verbatim"><ol><li>    <span class="s">(</span><span class="i">data</span><span class="s">(</span><span class="n">2</span><span class="s">)</span><span class="cm">,</span><span class="i">data</span><span class="s">(</span><span class="n">3</span><span class="s">)</span><span class="s">)</span> = <span class="i">get_data</span><span class="s">(</span><span class="n">3</span><span class="cm">,</span><span class="n">4</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>all the subroutines are called in a list context.</p>
<p>Lvalue subroutines are convenient, but you have to keep in mind that,
when used with objects, they may violate encapsulation.  A normal
mutator can check the supplied argument before setting the attribute
it is protecting, an lvalue subroutine cannot.  If you require any
special processing when storing and retrieving the values, consider
using the CPAN module Sentinel or something similar.</p>
<a name="Lexical-Subroutines"></a><h2>Lexical Subroutines
   </h2>
<p>Beginning with Perl 5.18, you can declare a private subroutine with <code class="inline"><a class="l_k" href="functions/my.html">my</a></code>
or <code class="inline"><a class="l_k" href="functions/state.html">state</a></code>.  As with state variables, the <code class="inline"><a class="l_k" href="functions/state.html">state</a></code> keyword is only
available under <code class="inline"><a class="l_k" href="functions/use.html">use</a> <span class="w">feature</span> <span class="q">'state'</span></code>
 or <code class="inline"><a class="l_k" href="functions/use.html">use</a> <span class="n">5.010</span></code>
 or higher.</p>
<p>Prior to Perl 5.26, lexical subroutines were deemed experimental and were
available only under the <code class="inline"><a class="l_k" href="functions/use.html">use</a> <span class="w">feature</span> <span class="q">&#39;lexical_subs&#39;</span></code>
 pragma.  They also
produced a warning unless the "experimental::lexical_subs" warnings
category was disabled.</p>
<p>These subroutines are only visible within the block in which they are
declared, and only after that declaration:</p>
<pre class="verbatim"><ol><li>    <span class="c"># Include these two lines if your code is intended to run under Perl</span></li><li>    <span class="c"># versions earlier than 5.26.</span></li><li>    <a class="l_k" href="functions/no.html">no</a> <span class="w">warnings</span> <span class="q">&quot;experimental::lexical_subs&quot;</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/use.html">use</a> <span class="w">feature</span> <span class="q">&#39;lexical_subs&#39;</span><span class="sc">;</span></li><li></li><li>    <span class="i">foo</span><span class="s">(</span><span class="s">)</span><span class="sc">;</span>		<span class="c"># calls the package/global subroutine</span></li><li><a name="foo"></a>    <span class="w">state</span> sub <span class="m">foo</span> <span class="s">{</span></li><li>	<span class="i">foo</span><span class="s">(</span><span class="s">)</span><span class="sc">;</span>		<span class="c"># also calls the package subroutine</span></li><li>    <span class="s">}</span></li><li>    <span class="i">foo</span><span class="s">(</span><span class="s">)</span><span class="sc">;</span>		<span class="c"># calls &quot;state&quot; sub</span></li><li>    <a class="l_k" href="functions/my.html">my</a> <span class="i">$ref</span> = \<span class="i">&amp;foo</span><span class="sc">;</span>	<span class="c"># take a reference to &quot;state&quot; sub</span></li><li></li><li><a name="bar"></a>    <a class="l_k" href="functions/my.html">my</a> sub <span class="m">bar</span> <span class="s">{</span> ... <span class="s">}</span></li><li>    <span class="i">bar</span><span class="s">(</span><span class="s">)</span><span class="sc">;</span>		<span class="c"># calls &quot;my&quot; sub</span></li></ol></pre><p>To use a lexical subroutine from inside the subroutine itself, you must
predeclare it.  The <code class="inline"><a name="foo"></a>sub <span class="m">foo</span> <span class="s">{</span>...<span class="s">}</span></code>
 subroutine definition syntax respects
any previous <code class="inline"><a class="l_k" href="functions/my.html">my</a> <a class="l_k" href="functions/sub.html">sub</a><span class="sc">;</span></code>
 or <code class="inline"><span class="w">state</span> <a class="l_k" href="functions/sub.html">sub</a><span class="sc">;</span></code>
 declaration.</p>
<pre class="verbatim"><ol><li><a name="baz"></a>    <a class="l_k" href="functions/my.html">my</a> sub <span class="m">baz</span><span class="sc">;</span>		<span class="c"># predeclaration</span></li><li><a name="baz-1"></a>    sub <span class="m">baz</span> <span class="s">{</span>		<span class="c"># define the &quot;my&quot; sub</span></li><li>	<span class="i">baz</span><span class="s">(</span><span class="s">)</span><span class="sc">;</span>		<span class="c"># recursive call</span></li><li>    <span class="s">}</span></li></ol></pre><a name="state-sub-vs-my-sub"></a><h3><code class="inline"><span class="w">state</span> <a class="l_k" href="functions/sub.html">sub</a></code>
 vs <code class="inline"><a class="l_k" href="functions/my.html">my</a> <a class="l_k" href="functions/sub.html">sub</a></code>
</h3>
<p>What is the difference between "state" subs and "my" subs?  Each time that
execution enters a block when "my" subs are declared, a new copy of each
sub is created.  "State" subroutines persist from one execution of the
containing block to the next.</p>
<p>So, in general, "state" subroutines are faster.  But "my" subs are
necessary if you want to create closures:</p>
<pre class="verbatim"><ol><li><a name="whatever"></a>    sub <span class="m">whatever</span> <span class="s">{</span></li><li>	<a class="l_k" href="functions/my.html">my</a> <span class="i">$x</span> = <a class="l_k" href="functions/shift.html">shift</a><span class="sc">;</span></li><li><a name="inner"></a>	<a class="l_k" href="functions/my.html">my</a> sub <span class="m">inner</span> <span class="s">{</span></li><li>	    ... <a class="l_k" href="functions/do.html">do</a> <span class="w">something</span> <span class="w">with</span> <span class="i">$x</span> ...</li><li>	<span class="s">}</span></li><li>	<span class="i">inner</span><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li>    <span class="s">}</span></li></ol></pre><p>In this example, a new <code class="inline"><span class="i">$x</span></code>
 is created when <code class="inline"><span class="w">whatever</span></code>
 is called, and
also a new <code class="inline"><span class="w">inner</span></code>
, which can see the new <code class="inline"><span class="i">$x</span></code>
.  A "state" sub will only
see the <code class="inline"><span class="i">$x</span></code>
 from the first call to <code class="inline"><span class="w">whatever</span></code>
.</p>
<a name="our-subroutines"></a><h3><code class="inline"><a class="l_k" href="functions/our.html">our</a></code> subroutines</h3>
<p>Like <code class="inline"><a class="l_k" href="functions/our.html">our</a> <span class="i">$variable</span></code>
, <code class="inline"><a class="l_k" href="functions/our.html">our</a> <a class="l_k" href="functions/sub.html">sub</a></code>
 creates a lexical alias to the package
subroutine of the same name.</p>
<p>The two main uses for this are to switch back to using the package sub
inside an inner scope:</p>
<pre class="verbatim"><ol><li><a name="foo"></a>    sub <span class="m">foo</span> <span class="s">{</span> ... <span class="s">}</span></li><li></li><li><a name="bar"></a>    sub <span class="m">bar</span> <span class="s">{</span></li><li><a name="foo-1"></a>	<a class="l_k" href="functions/my.html">my</a> sub <span class="m">foo</span> <span class="s">{</span> ... <span class="s">}</span></li><li>	<span class="s">{</span></li><li>	    <span class="c"># need to use the outer foo here</span></li><li><a name="foo-2"></a>	    <a class="l_k" href="functions/our.html">our</a> sub <span class="m">foo</span><span class="sc">;</span></li><li>	    <span class="i">foo</span><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li>	<span class="s">}</span></li><li>    <span class="s">}</span></li></ol></pre><p>and to make a subroutine visible to other packages in the same scope:</p>
<pre class="verbatim"><ol><li><a name="package-MySneakyModule"></a>    package <span class="i">MySneakyModule</span><span class="sc">;</span></li><li></li><li><a name="do_something"></a>    <a class="l_k" href="functions/our.html">our</a> sub <span class="m">do_something</span> <span class="s">{</span> ... <span class="s">}</span></li><li></li><li><a name="do_something_with_caller"></a>    sub <span class="m">do_something_with_caller</span> <span class="s">{</span></li><li><a name="package-DB"></a>	package <span class="i">DB</span><span class="sc">;</span></li><li>	<span class="s">(</span><span class="s">)</span> = <a class="l_k" href="functions/caller.html">caller</a> <span class="n">1</span><span class="sc">;</span>		<span class="c"># sets @DB::args</span></li><li>	<span class="i">do_something</span><span class="s">(</span><span class="i">@args</span><span class="s">)</span><span class="sc">;</span>	<span class="c"># uses MySneakyModule::do_something</span></li><li><a name="package-MySneakyModule-1"></a>    <span class="s">}</span></li></ol></pre><a name="Passing-Symbol-Table-Entries-(typeglobs)"></a><h2>Passing Symbol Table Entries (typeglobs)
 </h2>
<p><b>WARNING</b>: The mechanism described in this section was originally
the only way to simulate pass-by-reference in older versions of
Perl.  While it still works fine in modern versions, the new reference
mechanism is generally easier to work with.  See below.</p>
<p>Sometimes you don't want to pass the value of an array to a subroutine
but rather the name of it, so that the subroutine can modify the global
copy of it rather than working with a local copy.  In perl you can
refer to all objects of a particular name by prefixing the name
with a star: <code class="inline"><span class="i">*foo</span></code>
.  This is often known as a "typeglob", because the
star on the front can be thought of as a wildcard match for all the
funny prefix characters on variables and subroutines and such.</p>
<p>When evaluated, the typeglob produces a scalar value that represents
all the objects of that name, including any filehandle, format, or
subroutine.  When assigned to, it causes the name mentioned to refer to
whatever <code class="inline"><span class="i">*</span></code>
 value was assigned to it.  Example:</p>
<pre class="verbatim"><ol><li><a name="doubleary"></a>    sub <span class="m">doubleary</span> <span class="s">{</span></li><li>	<a class="l_k" href="functions/local.html">local</a><span class="s">(</span><span class="i">*someary</span><span class="s">)</span> = <span class="i">@_</span><span class="sc">;</span></li><li>	foreach <span class="i">$elem</span> <span class="s">(</span><span class="i">@someary</span><span class="s">)</span> <span class="s">{</span></li><li>	    <span class="i">$elem</span> *= <span class="n">2</span><span class="sc">;</span></li><li>	<span class="s">}</span></li><li>    <span class="s">}</span></li><li>    <span class="i">doubleary</span><span class="s">(</span><span class="i">*foo</span><span class="s">)</span><span class="sc">;</span></li><li>    <span class="i">doubleary</span><span class="s">(</span><span class="i">*bar</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>Scalars are already passed by reference, so you can modify
scalar arguments without using this mechanism by referring explicitly
to <code class="inline"><span class="i">$_</span>[<span class="n">0</span>]</code>
 etc.  You can modify all the elements of an array by passing
all the elements as scalars, but you have to use the <code class="inline"><span class="i">*</span></code>
 mechanism (or
the equivalent reference mechanism) to <code class="inline"><a class="l_k" href="functions/push.html">push</a></code>, <code class="inline"><a class="l_k" href="functions/pop.html">pop</a></code>, or change the size of
an array.  It will certainly be faster to pass the typeglob (or reference).</p>
<p>Even if you don't want to modify an array, this mechanism is useful for
passing multiple arrays in a single LIST, because normally the LIST
mechanism will merge all the array values so that you can't extract out
the individual arrays.  For more on typeglobs, see
<a href="perldata.html#Typeglobs-and-Filehandles">Typeglobs and Filehandles in perldata</a>.</p>
<a name="When-to-Still-Use-local()"></a><h2>When to Still Use local()
 </h2>
<p>Despite the existence of <code class="inline"><a class="l_k" href="functions/my.html">my</a></code>, there are still three places where the
<code class="inline"><a class="l_k" href="functions/local.html">local</a></code> operator still shines.  In fact, in these three places, you
<i>must</i> use <code class="inline"><a class="l_k" href="functions/local.html">local</a></code> instead of <code class="inline"><a class="l_k" href="functions/my.html">my</a></code>.</p>
<dl>
<dt>1.</dt><dd>
<p>You need to give a global variable a temporary value, especially $_.</p>
<p>The global variables, like <code class="inline"><span class="i">@ARGV</span></code>
 or the punctuation variables, must be 
<code class="inline"><a class="l_k" href="functions/local.html">local</a></code>ized with <code class="inline"><a class="l_k" href="functions/local.html">local()</a></code>.  This block reads in <i>/etc/motd</i>, and splits
it up into chunks separated by lines of equal signs, which are placed
in <code class="inline"><span class="i">@Fields</span></code>
.</p>
<pre class="verbatim"><ol><li>    <span class="s">{</span></li><li>	<a class="l_k" href="functions/local.html">local</a> <span class="i">@ARGV</span> = <span class="s">(</span><span class="q">&quot;/etc/motd&quot;</span><span class="s">)</span><span class="sc">;</span></li><li>        <a class="l_k" href="functions/local.html">local</a> <span class="i">$/</span> = <a class="l_k" href="functions/undef.html">undef</a><span class="sc">;</span></li><li>        <a class="l_k" href="functions/local.html">local</a> <span class="i">$_</span> = &lt;&gt;<span class="sc">;</span>	</li><li>	<span class="i">@Fields</span> = <a class="l_k" href="functions/split.html">split</a> <span class="q">/^\s*=+\s*$/</span><span class="sc">;</span></li><li>    <span class="s">}</span></li></ol></pre><p>It particular, it's important to <code class="inline"><a class="l_k" href="functions/local.html">local</a></code>ize $_ in any routine that assigns
to it.  Look out for implicit assignments in <code class="inline">while</code>
 conditionals.</p>
</dd>
<dt>2.</dt><dd>
<p>You need to create a local file or directory handle or a local function.</p>
<p>A function that needs a filehandle of its own must use
<code class="inline"><a class="l_k" href="functions/local.html">local()</a></code> on a complete typeglob.   This can be used to create new symbol
table entries:</p>
<pre class="verbatim"><ol><li><a name="ioqueue"></a>    sub <span class="m">ioqueue</span> <span class="s">{</span></li><li>        <a class="l_k" href="functions/local.html">local</a>  <span class="s">(</span><span class="i">*READER</span><span class="cm">,</span> <span class="i">*WRITER</span><span class="s">)</span><span class="sc">;</span>    <span class="c"># not my!</span></li><li>        <a class="l_k" href="functions/pipe.html">pipe</a>    <span class="s">(</span><span class="w">READER</span><span class="cm">,</span>  <span class="w">WRITER</span><span class="s">)</span>     or <a class="l_k" href="functions/die.html">die</a> <span class="q">&quot;pipe: $!&quot;</span><span class="sc">;</span></li><li>        <a class="l_k" href="functions/return.html">return</a> <span class="s">(</span><span class="i">*READER</span><span class="cm">,</span> <span class="i">*WRITER</span><span class="s">)</span><span class="sc">;</span></li><li>    <span class="s">}</span></li><li>    <span class="s">(</span><span class="i">$head</span><span class="cm">,</span> <span class="i">$tail</span><span class="s">)</span> = <span class="i">ioqueue</span><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>See the Symbol module for a way to create anonymous symbol table
entries.</p>
<p>Because assignment of a reference to a typeglob creates an alias, this
can be used to create what is effectively a local function, or at least,
a local alias.</p>
<pre class="verbatim"><ol><li>    <span class="s">{</span></li><li>        <a class="l_k" href="functions/local.html">local</a> <span class="i">*grow</span> = \<span class="i">&amp;shrink</span><span class="sc">;</span> <span class="c"># only until this block exits</span></li><li>        <span class="i">grow</span><span class="s">(</span><span class="s">)</span><span class="sc">;</span>                <span class="c"># really calls shrink()</span></li><li>	<span class="i">move</span><span class="s">(</span><span class="s">)</span><span class="sc">;</span>		       <span class="c"># if move() grow()s, it shrink()s too</span></li><li>    <span class="s">}</span></li><li>    <span class="i">grow</span><span class="s">(</span><span class="s">)</span><span class="sc">;</span>		       <span class="c"># get the real grow() again</span></li></ol></pre><p>See <a href="perlref.html#Function-Templates">Function Templates in perlref</a> for more about manipulating
functions by name in this way.</p>
</dd>
<dt>3.</dt><dd>
<p>You want to temporarily change just one element of an array or hash.</p>
<p>You can <code class="inline"><a class="l_k" href="functions/local.html">local</a></code>ize just one element of an aggregate.  Usually this
is done on dynamics:</p>
<pre class="verbatim"><ol><li>    <span class="s">{</span></li><li>	<a class="l_k" href="functions/local.html">local</a> <span class="i">$SIG</span>{<span class="w">INT</span>} = <span class="q">&#39;IGNORE&#39;</span><span class="sc">;</span></li><li>	<span class="i">funct</span><span class="s">(</span><span class="s">)</span><span class="sc">;</span>			    <span class="c"># uninterruptible</span></li><li>    <span class="s">}</span> </li><li>    <span class="c"># interruptibility automatically restored here</span></li></ol></pre><p>But it also works on lexically declared aggregates.</p>
</dd>
</dl>
<a name="Pass-by-Reference"></a><h2>Pass by Reference
  </h2>
<p>If you want to pass more than one array or hash into a function--or
return them from it--and have them maintain their integrity, then
you're going to have to use an explicit pass-by-reference.  Before you
do that, you need to understand references as detailed in <a href="perlref.html">perlref</a>.
This section may not make much sense to you otherwise.</p>
<p>Here are a few simple examples.  First, let's pass in several arrays
to a function and have it <code class="inline"><a class="l_k" href="functions/pop.html">pop</a></code> all of then, returning a new list
of all their former last elements:</p>
<pre class="verbatim"><ol><li>    <span class="i">@tailings</span> = <span class="w">popmany</span> <span class="s">(</span> \<span class="i">@a</span><span class="cm">,</span> \<span class="i">@b</span><span class="cm">,</span> \<span class="i">@c</span><span class="cm">,</span> \<span class="i">@d</span> <span class="s">)</span><span class="sc">;</span></li><li></li><li><a name="popmany"></a>    sub <span class="m">popmany</span> <span class="s">{</span></li><li>	<a class="l_k" href="functions/my.html">my</a> <span class="i">$aref</span><span class="sc">;</span></li><li>	<a class="l_k" href="functions/my.html">my</a> <span class="i">@retlist</span><span class="sc">;</span></li><li>	<a class="l_k" href="functions/foreach.html">foreach</a> <span class="i">$aref</span> <span class="s">(</span> <span class="i">@_</span> <span class="s">)</span> <span class="s">{</span></li><li>	    <a class="l_k" href="functions/push.html">push</a> <span class="i">@retlist</span><span class="cm">,</span> <a class="l_k" href="functions/pop.html">pop</a> <span class="i">@$aref</span><span class="sc">;</span></li><li>	<span class="s">}</span></li><li>	<a class="l_k" href="functions/return.html">return</a> <span class="i">@retlist</span><span class="sc">;</span></li><li>    <span class="s">}</span></li></ol></pre><p>Here's how you might write a function that returns a
list of keys occurring in all the hashes passed to it:</p>
<pre class="verbatim"><ol><li>    <span class="i">@common</span> = <span class="i">inter</span><span class="s">(</span> \<span class="i">%foo</span><span class="cm">,</span> \<span class="i">%bar</span><span class="cm">,</span> \<span class="i">%joe</span> <span class="s">)</span><span class="sc">;</span></li><li><a name="inter"></a>    sub <span class="m">inter</span> <span class="s">{</span></li><li>	<a class="l_k" href="functions/my.html">my</a> <span class="s">(</span><span class="i">$k</span><span class="cm">,</span> <span class="i">$href</span><span class="cm">,</span> <span class="i">%seen</span><span class="s">)</span><span class="sc">;</span> <span class="c"># locals</span></li><li>	foreach <span class="i">$href</span> <span class="s">(</span><span class="i">@_</span><span class="s">)</span> <span class="s">{</span></li><li>	    while <span class="s">(</span> <span class="i">$k</span> = <a class="l_k" href="functions/each.html">each</a> <span class="i">%$href</span> <span class="s">)</span> <span class="s">{</span></li><li>		<span class="i">$seen</span>{<span class="i">$k</span>}++<span class="sc">;</span></li><li>	    <span class="s">}</span></li><li>	<span class="s">}</span></li><li>	<a class="l_k" href="functions/return.html">return</a> <a class="l_k" href="functions/grep.html">grep</a> <span class="s">{</span> <span class="i">$seen</span>{<span class="i">$_</span>} == <span class="i">@_</span> <span class="s">}</span> <a class="l_k" href="functions/keys.html">keys</a> <span class="i">%seen</span><span class="sc">;</span></li><li>    <span class="s">}</span></li></ol></pre><p>So far, we're using just the normal list return mechanism.
What happens if you want to pass or return a hash?  Well,
if you're using only one of them, or you don't mind them
concatenating, then the normal calling convention is ok, although
a little expensive.</p>
<p>Where people get into trouble is here:</p>
<pre class="verbatim"><ol><li>    <span class="s">(</span><span class="i">@a</span><span class="cm">,</span> <span class="i">@b</span><span class="s">)</span> = <span class="i">func</span><span class="s">(</span><span class="i">@c</span><span class="cm">,</span> <span class="i">@d</span><span class="s">)</span><span class="sc">;</span></li><li>or</li><li>    <span class="s">(</span><span class="i">%a</span><span class="cm">,</span> <span class="i">%b</span><span class="s">)</span> = <span class="i">func</span><span class="s">(</span><span class="i">%c</span><span class="cm">,</span> <span class="i">%d</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>That syntax simply won't work.  It sets just <code class="inline"><span class="i">@a</span></code>
 or <code class="inline"><span class="i">%a</span></code>
 and
clears the <code class="inline"><span class="i">@b</span></code>
 or <code class="inline"><span class="i">%b</span></code>
.  Plus the function didn't get passed
into two separate arrays or hashes: it got one long list in <code class="inline"><span class="i">@_</span></code>
,
as always.</p>
<p>If you can arrange for everyone to deal with this through references, it's
cleaner code, although not so nice to look at.  Here's a function that
takes two array references as arguments, returning the two array elements
in order of how many elements they have in them:</p>
<pre class="verbatim"><ol><li>    <span class="s">(</span><span class="i">$aref</span><span class="cm">,</span> <span class="i">$bref</span><span class="s">)</span> = <span class="i">func</span><span class="s">(</span>\<span class="i">@c</span><span class="cm">,</span> \<span class="i">@d</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;@$aref has more than @$bref\n&quot;</span><span class="sc">;</span></li><li><a name="func"></a>    sub <span class="m">func</span> <span class="s">{</span></li><li>	<a class="l_k" href="functions/my.html">my</a> <span class="s">(</span><span class="i">$cref</span><span class="cm">,</span> <span class="i">$dref</span><span class="s">)</span> = <span class="i">@_</span><span class="sc">;</span></li><li>	if <span class="s">(</span><span class="i">@$cref</span> &gt; <span class="i">@$dref</span><span class="s">)</span> <span class="s">{</span></li><li>	    <a class="l_k" href="functions/return.html">return</a> <span class="s">(</span><span class="i">$cref</span><span class="cm">,</span> <span class="i">$dref</span><span class="s">)</span><span class="sc">;</span></li><li>	<span class="s">}</span> else <span class="s">{</span></li><li>	    <a class="l_k" href="functions/return.html">return</a> <span class="s">(</span><span class="i">$dref</span><span class="cm">,</span> <span class="i">$cref</span><span class="s">)</span><span class="sc">;</span></li><li>	<span class="s">}</span></li><li>    <span class="s">}</span></li></ol></pre><p>It turns out that you can actually do this also:</p>
<pre class="verbatim"><ol><li>    <span class="s">(</span><span class="i">*a</span><span class="cm">,</span> <span class="i">*b</span><span class="s">)</span> = <span class="i">func</span><span class="s">(</span>\<span class="i">@c</span><span class="cm">,</span> \<span class="i">@d</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;@a has more than @b\n&quot;</span><span class="sc">;</span></li><li><a name="func"></a>    sub <span class="m">func</span> <span class="s">{</span></li><li>	<a class="l_k" href="functions/local.html">local</a> <span class="s">(</span><span class="i">*c</span><span class="cm">,</span> <span class="i">*d</span><span class="s">)</span> = <span class="i">@_</span><span class="sc">;</span></li><li>	if <span class="s">(</span><span class="i">@c</span> &gt; <span class="i">@d</span><span class="s">)</span> <span class="s">{</span></li><li>	    <a class="l_k" href="functions/return.html">return</a> <span class="s">(</span>\<span class="i">@c</span><span class="cm">,</span> \<span class="i">@d</span><span class="s">)</span><span class="sc">;</span></li><li>	<span class="s">}</span> else <span class="s">{</span></li><li>	    <a class="l_k" href="functions/return.html">return</a> <span class="s">(</span>\<span class="i">@d</span><span class="cm">,</span> \<span class="i">@c</span><span class="s">)</span><span class="sc">;</span></li><li>	<span class="s">}</span></li><li>    <span class="s">}</span></li></ol></pre><p>Here we're using the typeglobs to do symbol table aliasing.  It's
a tad subtle, though, and also won't work if you're using <code class="inline"><a class="l_k" href="functions/my.html">my</a></code>
variables, because only globals (even in disguise as <code class="inline"><a class="l_k" href="functions/local.html">local</a></code>s)
are in the symbol table.</p>
<p>If you're passing around filehandles, you could usually just use the bare
typeglob, like <code class="inline"><span class="i">*STDOUT</span></code>
, but typeglobs references work, too.
For example:</p>
<pre class="verbatim"><ol><li>    <span class="i">splutter</span><span class="s">(</span>\<span class="i">*STDOUT</span><span class="s">)</span><span class="sc">;</span></li><li><a name="splutter"></a>    sub <span class="m">splutter</span> <span class="s">{</span></li><li>	<a class="l_k" href="functions/my.html">my</a> <span class="i">$fh</span> = <a class="l_k" href="functions/shift.html">shift</a><span class="sc">;</span></li><li>	<a class="l_k" href="functions/print.html">print</a> <span class="i">$fh</span> <span class="q">&quot;her um well a hmmm\n&quot;</span><span class="sc">;</span></li><li>    <span class="s">}</span></li><li></li><li>    <span class="i">$rec</span> = <span class="i">get_rec</span><span class="s">(</span>\<span class="i">*STDIN</span><span class="s">)</span><span class="sc">;</span></li><li><a name="get_rec"></a>    sub <span class="m">get_rec</span> <span class="s">{</span></li><li>	<a class="l_k" href="functions/my.html">my</a> <span class="i">$fh</span> = <a class="l_k" href="functions/shift.html">shift</a><span class="sc">;</span></li><li>	<a class="l_k" href="functions/return.html">return</a> <a class="l_k" href="functions/scalar.html">scalar</a> <span class="q">&lt;$fh&gt;</span><span class="sc">;</span></li><li>    <span class="s">}</span></li></ol></pre><p>If you're planning on generating new filehandles, you could do this.
Notice to pass back just the bare *FH, not its reference.</p>
<pre class="verbatim"><ol><li><a name="openit"></a>    sub <span class="m">openit</span> <span class="s">{</span></li><li>	<a class="l_k" href="functions/my.html">my</a> <span class="i">$path</span> = <a class="l_k" href="functions/shift.html">shift</a><span class="sc">;</span></li><li>	<a class="l_k" href="functions/local.html">local</a> <span class="i">*FH</span><span class="sc">;</span></li><li>	<a class="l_k" href="functions/return.html">return</a> <a class="l_k" href="functions/open.html">open</a> <span class="s">(</span><span class="w">FH</span><span class="cm">,</span> <span class="i">$path</span><span class="s">)</span> ? <span class="i">*FH</span> <span class="co">:</span> <a class="l_k" href="functions/undef.html">undef</a><span class="sc">;</span></li><li>    <span class="s">}</span></li></ol></pre><a name="Prototypes"></a><h2>Prototypes
 </h2>
<p>Perl supports a very limited kind of compile-time argument checking
using function prototyping.  This can be declared in either the PROTO
section or with a <a href="attributes.html#Built-in-Attributes">prototype attribute</a>.
If you declare either of</p>
<pre class="verbatim"><ol><li><a name="mypush"></a>    sub <span class="m">mypush (\@@)</span></li><li><a name="mypush-1"></a>    sub <span class="m">mypush</span> <span class="co">:</span><span class="q">prototype(\@@)</span></li></ol></pre><p>then <code class="inline"><span class="i">mypush</span><span class="s">(</span><span class="s">)</span></code>
 takes arguments exactly like <code class="inline"><a class="l_k" href="functions/push.html">push()</a></code> does.</p>
<p>If subroutine signatures are enabled (see <a href="#Signatures">Signatures</a>), then
the shorter PROTO syntax is unavailable, because it would clash with
signatures.  In that case, a prototype can only be declared in the form
of an attribute.</p>
<p>The
function declaration must be visible at compile time.  The prototype
affects only interpretation of new-style calls to the function,
where new-style is defined as not using the <code class="inline"><span class="i">&amp;</span></code>
 character.  In
other words, if you call it like a built-in function, then it behaves
like a built-in function.  If you call it like an old-fashioned
subroutine, then it behaves like an old-fashioned subroutine.  It
naturally falls out from this rule that prototypes have no influence
on subroutine references like <code class="inline">\<span class="i">&amp;foo</span></code>
 or on indirect subroutine
calls like <code class="inline"><span class="i">&amp;</span>{<span class="i">$subref</span>}</code>
 or <code class="inline"><span class="i">$subref</span>-&gt;<span class="s">(</span><span class="s">)</span></code>
.</p>
<p>Method calls are not influenced by prototypes either, because the
function to be called is indeterminate at compile time, since
the exact code called depends on inheritance.</p>
<p>Because the intent of this feature is primarily to let you define
subroutines that work like built-in functions, here are prototypes
for some other functions that parse almost exactly like the
corresponding built-in.</p>
<pre class="verbatim"><ol><li>   <span class="w">Declared</span> <span class="w">as</span>		   <span class="w">Called</span> <span class="w">as</span></li><li></li><li><a name="mylink"></a>   sub <span class="m">mylink ($$)</span>	   <span class="i">mylink</span> <span class="i">$old</span><span class="cm">,</span> <span class="i">$new</span></li><li><a name="myvec"></a>   sub <span class="m">myvec ($$$)</span>	   <span class="i">myvec</span> <span class="i">$var</span><span class="cm">,</span> <span class="i">$offset</span><span class="cm">,</span> <span class="n">1</span></li><li><a name="myindex"></a>   sub <span class="m">myindex ($$;$)</span>	   <span class="i">myindex</span> <span class="i">&amp;getstring</span><span class="cm">,</span> <span class="q">&quot;substr&quot;</span></li><li><a name="mysyswrite"></a>   sub <span class="m">mysyswrite ($$$;$)</span>  <span class="i">mysyswrite</span> <span class="i">$buf</span><span class="cm">,</span> <span class="n">0</span><span class="cm">,</span> <a class="l_k" href="functions/length.html">length</a><span class="s">(</span><span class="i">$buf</span><span class="s">)</span> - <span class="i">$off</span><span class="cm">,</span> <span class="i">$off</span></li><li><a name="myreverse"></a>   sub <span class="m">myreverse (@)</span>	   <span class="i">myreverse</span> <span class="i">$a</span><span class="cm">,</span> <span class="i">$b</span><span class="cm">,</span> <span class="i">$c</span></li><li><a name="myjoin"></a>   sub <span class="m">myjoin ($@)</span>	   <span class="i">myjoin</span> <span class="q">&quot;:&quot;</span><span class="cm">,</span> <span class="i">$a</span><span class="cm">,</span> <span class="i">$b</span><span class="cm">,</span> <span class="i">$c</span></li><li><a name="mypop"></a>   sub <span class="m">mypop (\@)</span>	   <span class="i">mypop</span> <span class="i">@array</span></li><li><a name="mysplice"></a>   sub <span class="m">mysplice (\@$$@)</span>	   <span class="i">mysplice</span> <span class="i">@array</span><span class="cm">,</span> <span class="n">0</span><span class="cm">,</span> <span class="n">2</span><span class="cm">,</span> <span class="i">@pushme</span></li><li><a name="mykeys"></a>   sub <span class="m">mykeys (\[%@])</span>	   <span class="i">mykeys</span> <span class="i">%</span>{<span class="i">$hashref</span>}</li><li><a name="myopen"></a>   sub <span class="m">myopen (*;$)</span>	   <span class="i">myopen</span> <span class="w">HANDLE</span><span class="cm">,</span> <span class="i">$name</span></li><li><a name="mypipe"></a>   sub <span class="m">mypipe (**)</span>	   <span class="i">mypipe</span> <span class="w">READHANDLE</span><span class="cm">,</span> <span class="w">WRITEHANDLE</span></li><li><a name="mygrep"></a>   sub <span class="m">mygrep (&amp;@)</span>	   <span class="i">mygrep</span> <span class="s">{</span> <span class="q">/foo/</span> <span class="s">}</span> <span class="i">$a</span><span class="cm">,</span> <span class="i">$b</span><span class="cm">,</span> <span class="i">$c</span></li><li><a name="myrand"></a>   sub <span class="m">myrand (;$)</span>	   <span class="i">myrand</span> <span class="n">42</span></li><li><a name="mytime"></a>   sub <span class="m">mytime ()</span>	   <span class="i">mytime</span></li></ol></pre><p>Any backslashed prototype character represents an actual argument
that must start with that character (optionally preceded by <code class="inline"><a class="l_k" href="functions/my.html">my</a></code>,
<code class="inline"><a class="l_k" href="functions/our.html">our</a></code> or <code class="inline"><a class="l_k" href="functions/local.html">local</a></code>), with the exception of <code class="inline"><span class="i">$</span></code>
, which will
accept any scalar lvalue expression, such as <code class="inline"><span class="i">$foo</span> = <span class="n">7</span></code>
 or
<code class="inline"><span class="i">my_function</span><span class="s">(</span><span class="s">)</span>-&gt;[<span class="n">0</span>]</code>
.  The value passed as part of <code class="inline"><span class="i">@_</span></code>
 will be a
reference to the actual argument given in the subroutine call,
obtained by applying <code class="inline">\</code>
 to that argument.</p>
<p>You can use the <code class="inline">\<span class="s">[</span><span class="s">]</span></code>
 backslash group notation to specify more than one
allowed argument type.  For example:</p>
<pre class="verbatim"><ol><li><a name="myref"></a>    sub <span class="m">myref (\[$@%&amp;*])</span></li></ol></pre><p>will allow calling myref() as</p>
<pre class="verbatim"><ol><li>    myref $var</li><li>    myref @array</li><li>    myref %hash</li><li>    myref &amp;sub</li><li>    myref *glob</li></ol></pre><p>and the first argument of myref() will be a reference to
a scalar, an array, a hash, a code, or a glob.</p>
<p>Unbackslashed prototype characters have special meanings.  Any
unbackslashed <code class="inline"><span class="i">@</span></code>
 or <code class="inline"><span class="i">%</span></code>
 eats all remaining arguments, and forces
list context.  An argument represented by <code class="inline"><span class="i">$</span></code>
 forces scalar context.  An
<code class="inline"><span class="i">&amp;</span></code>
 requires an anonymous subroutine, which, if passed as the first
argument, does not require the <code class="inline"><a class="l_k" href="functions/sub.html">sub</a></code> keyword or a subsequent comma.</p>
<p>A <code class="inline"><span class="i">*</span></code>
 allows the subroutine to accept a bareword, constant, scalar expression,
typeglob, or a reference to a typeglob in that slot.  The value will be
available to the subroutine either as a simple scalar, or (in the latter
two cases) as a reference to the typeglob.  If you wish to always convert
such arguments to a typeglob reference, use Symbol::qualify_to_ref() as
follows:</p>
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/use.html">use</a> <span class="w">Symbol</span> <span class="q">&#39;qualify_to_ref&#39;</span><span class="sc">;</span></li><li></li><li><a name="foo"></a>    sub <span class="m">foo (*)</span> <span class="s">{</span></li><li>	<a class="l_k" href="functions/my.html">my</a> <span class="i">$fh</span> = <span class="i">qualify_to_ref</span><span class="s">(</span><a class="l_k" href="functions/shift.html">shift</a><span class="cm">,</span> <a class="l_k" href="functions/caller.html">caller</a><span class="s">)</span><span class="sc">;</span></li><li>	...</li><li>    <span class="s">}</span></li></ol></pre><p>The <code class="inline">+</code>
 prototype is a special alternative to <code class="inline"><span class="i">$</span></code>
 that will act like
<code class="inline">\<span class="s">[</span><span class="i">@%</span><span class="s">]</span></code>
 when given a literal array or hash variable, but will otherwise
force scalar context on the argument.  This is useful for functions which
should accept either a literal array or an array reference as the argument:</p>
<pre class="verbatim"><ol><li><a name="mypush"></a>    sub <span class="m">mypush (+@)</span> <span class="s">{</span></li><li>        <a class="l_k" href="functions/my.html">my</a> <span class="i">$aref</span> = <a class="l_k" href="functions/shift.html">shift</a><span class="sc">;</span></li><li>        <a class="l_k" href="functions/die.html">die</a> <span class="q">&quot;Not an array or arrayref&quot;</span> unless <a class="l_k" href="functions/ref.html">ref</a> <span class="i">$aref</span> eq <span class="q">&#39;ARRAY&#39;</span><span class="sc">;</span></li><li>        <a class="l_k" href="functions/push.html">push</a> <span class="i">@$aref</span><span class="cm">,</span> <span class="i">@_</span><span class="sc">;</span></li><li>    <span class="s">}</span></li></ol></pre><p>When using the <code class="inline">+</code>
 prototype, your function must check that the argument
is of an acceptable type.</p>
<p>A semicolon (<code class="inline"><span class="sc">;</span></code>
) separates mandatory arguments from optional arguments.
It is redundant before <code class="inline"><span class="i">@</span></code>
 or <code class="inline"><span class="i">%</span></code>
, which gobble up everything else.</p>
<p>As the last character of a prototype, or just before a semicolon, a <code class="inline"><span class="i">@</span></code>

or a <code class="inline"><span class="i">%</span></code>
, you can use <code class="inline"><span class="w">_</span></code>
 in place of <code class="inline"><span class="i">$</span></code>
: if this argument is not
provided, <code class="inline"><span class="i">$_</span></code>
 will be used instead.</p>
<p>Note how the last three examples in the table above are treated
specially by the parser.  <code class="inline"><span class="i">mygrep</span><span class="s">(</span><span class="s">)</span></code>
 is parsed as a true list
operator, <code class="inline"><span class="i">myrand</span><span class="s">(</span><span class="s">)</span></code>
 is parsed as a true unary operator with unary
precedence the same as <code class="inline"><a class="l_k" href="functions/rand.html">rand()</a></code>, and <code class="inline"><span class="i">mytime</span><span class="s">(</span><span class="s">)</span></code>
 is truly without
arguments, just like <code class="inline"><a class="l_k" href="functions/time.html">time()</a></code>.  That is, if you say</p>
<pre class="verbatim"><ol><li>    <span class="w">mytime</span> +<span class="n">2</span><span class="sc">;</span></li></ol></pre><p>you'll get <code class="inline"><span class="i">mytime</span><span class="s">(</span><span class="s">)</span> + <span class="n">2</span></code>
, not <code class="inline"><span class="i">mytime</span><span class="s">(</span><span class="n">2</span><span class="s">)</span></code>
, which is how it would be parsed
without a prototype.  If you want to force a unary function to have the
same precedence as a list operator, add <code class="inline"><span class="sc">;</span></code>
 to the end of the prototype:</p>
<pre class="verbatim"><ol><li>    sub <span class="m">mygetprotobynumber($;)</span><span class="sc">;</span></li><li>    <span class="i">mygetprotobynumber</span> <span class="i">$a</span> &gt; <span class="i">$b</span><span class="sc">;</span> <span class="c"># parsed as mygetprotobynumber($a &gt; $b)</span></li></ol></pre><p>The interesting thing about <code class="inline"><span class="i">&amp;</span></code>
 is that you can generate new syntax with it,
provided it's in the initial position:
</p>
<pre class="verbatim"><ol><li><a name="try"></a>    sub <span class="m">try (&amp;@)</span> <span class="s">{</span></li><li>	<a class="l_k" href="functions/my.html">my</a><span class="s">(</span><span class="i">$try</span><span class="cm">,</span><span class="i">$catch</span><span class="s">)</span> = <span class="i">@_</span><span class="sc">;</span></li><li>	<a class="l_k" href="functions/eval.html">eval</a> <span class="s">{</span> <span class="i">&amp;$try</span> <span class="s">}</span><span class="sc">;</span></li><li>	if <span class="s">(</span><span class="i">$@</span><span class="s">)</span> <span class="s">{</span></li><li>	    <a class="l_k" href="functions/local.html">local</a> <span class="i">$_</span> = <span class="i">$@</span><span class="sc">;</span></li><li>	    <span class="i">&amp;$catch</span><span class="sc">;</span></li><li>	<span class="s">}</span></li><li>    <span class="s">}</span></li><li><a name="catch"></a>    sub <span class="m">catch (&amp;)</span> <span class="s">{</span> <span class="i">$_</span>[<span class="n">0</span>] <span class="s">}</span></li><li></li><li>    <span class="i">try</span> <span class="s">{</span></li><li>	<a class="l_k" href="functions/die.html">die</a> <span class="q">&quot;phooey&quot;</span><span class="sc">;</span></li><li>    <span class="s">}</span> <span class="i">catch</span> <span class="s">{</span></li><li>	<span class="q">/phooey/</span> and <a class="l_k" href="functions/print.html">print</a> <span class="q">&quot;unphooey\n&quot;</span><span class="sc">;</span></li><li>    <span class="s">}</span><span class="sc">;</span></li></ol></pre><p>That prints <code class="inline"><span class="q">&quot;unphooey&quot;</span></code>
.  (Yes, there are still unresolved
issues having to do with visibility of <code class="inline"><span class="i">@_</span></code>
.  I'm ignoring that
question for the moment.  (But note that if we make <code class="inline"><span class="i">@_</span></code>
 lexically
scoped, those anonymous subroutines can act like closures... (Gee,
is this sounding a little Lispish?  (Never mind.))))</p>
<p>And here's a reimplementation of the Perl <code class="inline"><a class="l_k" href="functions/grep.html">grep</a></code> operator:
</p>
<pre class="verbatim"><ol><li><a name="mygrep"></a>    sub <span class="m">mygrep (&amp;@)</span> <span class="s">{</span></li><li>	<a class="l_k" href="functions/my.html">my</a> <span class="i">$code</span> = <a class="l_k" href="functions/shift.html">shift</a><span class="sc">;</span></li><li>	<a class="l_k" href="functions/my.html">my</a> <span class="i">@result</span><span class="sc">;</span></li><li>	foreach <span class="i">$_</span> <span class="s">(</span><span class="i">@_</span><span class="s">)</span> <span class="s">{</span></li><li>	    <a class="l_k" href="functions/push.html">push</a><span class="s">(</span><span class="i">@result</span><span class="cm">,</span> <span class="i">$_</span><span class="s">)</span> if <span class="i">&amp;$code</span><span class="sc">;</span></li><li>	<span class="s">}</span></li><li>	<span class="i">@result</span><span class="sc">;</span></li><li>    <span class="s">}</span></li></ol></pre><p>Some folks would prefer full alphanumeric prototypes.  Alphanumerics have
been intentionally left out of prototypes for the express purpose of
someday in the future adding named, formal parameters.  The current
mechanism's main goal is to let module writers provide better diagnostics
for module users.  Larry feels the notation quite understandable to Perl
programmers, and that it will not intrude greatly upon the meat of the
module, nor make it harder to read.  The line noise is visually
encapsulated into a small pill that's easy to swallow.</p>
<p>If you try to use an alphanumeric sequence in a prototype you will
generate an optional warning - "Illegal character in prototype...".
Unfortunately earlier versions of Perl allowed the prototype to be
used as long as its prefix was a valid prototype.  The warning may be
upgraded to a fatal error in a future version of Perl once the
majority of offending code is fixed.</p>
<p>It's probably best to prototype new functions, not retrofit prototyping
into older ones.  That's because you must be especially careful about
silent impositions of differing list versus scalar contexts.  For example,
if you decide that a function should take just one parameter, like this:</p>
<pre class="verbatim"><ol><li><a name="func"></a>    sub <span class="m">func ($)</span> <span class="s">{</span></li><li>	<a class="l_k" href="functions/my.html">my</a> <span class="i">$n</span> = <a class="l_k" href="functions/shift.html">shift</a><span class="sc">;</span></li><li>	<a class="l_k" href="functions/print.html">print</a> <span class="q">&quot;you gave me $n\n&quot;</span><span class="sc">;</span></li><li>    <span class="s">}</span></li></ol></pre><p>and someone has been calling it with an array or expression
returning a list:</p>
<pre class="verbatim"><ol><li>    <span class="i">func</span><span class="s">(</span><span class="i">@foo</span><span class="s">)</span><span class="sc">;</span></li><li>    <span class="i">func</span><span class="s">(</span> <span class="i">$text</span> =~ <span class="q">/\w+/g</span> <span class="s">)</span><span class="sc">;</span></li></ol></pre><p>Then you've just supplied an automatic <code class="inline"><a class="l_k" href="functions/scalar.html">scalar</a></code> in front of their
argument, which can be more than a bit surprising.  The old <code class="inline"><span class="i">@foo</span></code>

which used to hold one thing doesn't get passed in.  Instead,
<code class="inline"><span class="i">func</span><span class="s">(</span><span class="s">)</span></code>
 now gets passed in a <code class="inline"><span class="n">1</span></code>
; that is, the number of elements
in <code class="inline"><span class="i">@foo</span></code>
.  And the <code class="inline"><a class="l_k" href="functions/m.html">m//g</a></code> gets called in scalar context so instead of a
list of words it returns a boolean result and advances <code class="inline"><a class="l_k" href="functions/pos.html">pos($text)</a></code>.  Ouch!</p>
<p>If a sub has both a PROTO and a BLOCK, the prototype is not applied
until after the BLOCK is completely defined.  This means that a recursive
function with a prototype has to be predeclared for the prototype to take
effect, like so:</p>
<pre class="verbatim"><ol><li>	sub <span class="m">foo($$)</span><span class="sc">;</span></li><li><a name="foo"></a>	sub <span class="m">foo($$)</span> <span class="s">{</span></li><li>		<span class="i">foo</span> <span class="n">1</span><span class="cm">,</span> <span class="n">2</span><span class="sc">;</span></li><li>	<span class="s">}</span></li></ol></pre><p>This is all very powerful, of course, and should be used only in moderation
to make the world a better place.</p>
<a name="Constant-Functions"></a><h2>Constant Functions
</h2>
<p>Functions with a prototype of <code class="inline"><span class="s">(</span><span class="s">)</span></code>
 are potential candidates for
inlining.  If the result after optimization and constant folding
is either a constant or a lexically-scoped scalar which has no other
references, then it will be used in place of function calls made
without <code class="inline"><span class="i">&amp;</span></code>
.  Calls made using <code class="inline"><span class="i">&amp;</span></code>
 are never inlined.  (See
<i>constant.pm</i> for an easy way to declare most constants.)</p>
<p>The following functions would all be inlined:</p>
<pre class="verbatim"><ol><li><a name="pi"></a>    sub <span class="m">pi ()</span>		<span class="s">{</span> <span class="n">3.14159</span> <span class="s">}</span>		<span class="c"># Not exact, but close.</span></li><li><a name="PI-1"></a>    sub <span class="m">PI ()</span>		<span class="s">{</span> <span class="n">4</span> * <a class="l_k" href="functions/atan2.html">atan2</a> <span class="n">1</span><span class="cm">,</span> <span class="n">1</span> <span class="s">}</span>	<span class="c"># As good as it gets,</span></li><li>						<span class="c"># and it&#39;s inlined, too!</span></li><li><a name="ST_DEV"></a>    sub <span class="m">ST_DEV ()</span>	<span class="s">{</span> <span class="n">0</span> <span class="s">}</span></li><li><a name="ST_INO"></a>    sub <span class="m">ST_INO ()</span>	<span class="s">{</span> <span class="n">1</span> <span class="s">}</span></li><li></li><li><a name="FLAG_FOO"></a>    sub <span class="m">FLAG_FOO ()</span>	<span class="s">{</span> <span class="n">1</span> &lt;&lt; <span class="n">8</span> <span class="s">}</span></li><li><a name="FLAG_BAR"></a>    sub <span class="m">FLAG_BAR ()</span>	<span class="s">{</span> <span class="n">1</span> &lt;&lt; <span class="n">9</span> <span class="s">}</span></li><li><a name="FLAG_MASK"></a>    sub <span class="m">FLAG_MASK ()</span>	<span class="s">{</span> <span class="i">FLAG_FOO</span> | <span class="i">FLAG_BAR</span> <span class="s">}</span></li><li></li><li><a name="OPT_BAZ"></a>    sub <span class="m">OPT_BAZ ()</span>	<span class="s">{</span> <a class="l_k" href="functions/not.html">not</a> <span class="s">(</span><span class="n">0x1B58</span> &amp; <span class="i">FLAG_MASK</span><span class="s">)</span> <span class="s">}</span></li><li></li><li><a name="N"></a>    sub <span class="m">N ()</span> <span class="s">{</span> <a class="l_k" href="functions/int.html">int</a><span class="s">(</span><span class="i">OPT_BAZ</span><span class="s">)</span> / <span class="n">3</span> <span class="s">}</span></li><li></li><li><a name="FOO_SET"></a>    sub <span class="m">FOO_SET ()</span> <span class="s">{</span> <span class="n">1</span> <a class="l_k" href="functions/if.html">if</a> <span class="i">FLAG_MASK</span> &amp; <span class="i">FLAG_FOO</span> <span class="s">}</span></li><li><a name="FOO_SET2"></a>    sub <span class="m">FOO_SET2 ()</span> <span class="s">{</span> <a class="l_k" href="functions/if.html">if</a> <span class="s">(</span><span class="i">FLAG_MASK</span> &amp; <span class="i">FLAG_FOO</span><span class="s">)</span> <span class="s">{</span> <span class="n">1</span> <span class="s">}</span> <span class="s">}</span></li></ol></pre><p>(Be aware that the last example was not always inlined in Perl 5.20 and
earlier, which did not behave consistently with subroutines containing
inner scopes.)  You can countermand inlining by using an explicit
<code class="inline"><a class="l_k" href="functions/return.html">return</a></code>:</p>
<pre class="verbatim"><ol><li><a name="baz_val"></a>    sub <span class="m">baz_val ()</span> <span class="s">{</span></li><li>	<a class="l_k" href="functions/if.html">if</a> <span class="s">(</span><span class="w">OPT_BAZ</span><span class="s">)</span> <span class="s">{</span></li><li>	    <a class="l_k" href="functions/return.html">return</a> <span class="n">23</span><span class="sc">;</span></li><li>	<span class="s">}</span></li><li>	<a class="l_k" href="functions/else.html">else</a> <span class="s">{</span></li><li>	    <a class="l_k" href="functions/return.html">return</a> <span class="n">42</span><span class="sc">;</span></li><li>	<span class="s">}</span></li><li>    <span class="s">}</span></li><li><a name="bonk_val"></a>    sub <span class="m">bonk_val ()</span> <span class="s">{</span> <a class="l_k" href="functions/return.html">return</a> <span class="n">12345</span> <span class="s">}</span></li></ol></pre><p>As alluded to earlier you can also declare inlined subs dynamically at
BEGIN time if their body consists of a lexically-scoped scalar which
has no other references.  Only the first example here will be inlined:</p>
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/BEGIN.html">BEGIN</a> <span class="s">{</span></li><li>        <a class="l_k" href="functions/my.html">my</a> <span class="i">$var</span> = <span class="n">1</span><span class="sc">;</span></li><li>        <a class="l_k" href="functions/no.html">no</a> <span class="w">strict</span> <span class="q">&#39;refs&#39;</span><span class="sc">;</span></li><li>        <span class="i">*INLINED</span> = <span class="i">sub ()</span> <span class="s">{</span> <span class="i">$var</span> <span class="s">}</span><span class="sc">;</span></li><li>    <span class="s">}</span></li><li></li><li>    <a class="l_k" href="functions/BEGIN.html">BEGIN</a> <span class="s">{</span></li><li>        <a class="l_k" href="functions/my.html">my</a> <span class="i">$var</span> = <span class="n">1</span><span class="sc">;</span></li><li>        <a class="l_k" href="functions/my.html">my</a> <span class="i">$ref</span> = \<span class="i">$var</span><span class="sc">;</span></li><li>        <a class="l_k" href="functions/no.html">no</a> <span class="w">strict</span> <span class="q">&#39;refs&#39;</span><span class="sc">;</span></li><li>        <span class="i">*NOT_INLINED</span> = <span class="i">sub ()</span> <span class="s">{</span> <span class="i">$var</span> <span class="s">}</span><span class="sc">;</span></li><li>    <span class="s">}</span></li></ol></pre><p>A not so obvious caveat with this (see [RT #79908]) is that the
variable will be immediately inlined, and will stop behaving like a
normal lexical variable, e.g. this will print <code class="inline"><span class="n">79907</span></code>
, not <code class="inline"><span class="n">79908</span></code>
:</p>
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/BEGIN.html">BEGIN</a> <span class="s">{</span></li><li>        <a class="l_k" href="functions/my.html">my</a> <span class="i">$x</span> = <span class="n">79907</span><span class="sc">;</span></li><li>        <span class="i">*RT_79908</span> = <span class="i">sub ()</span> <span class="s">{</span> <span class="i">$x</span> <span class="s">}</span><span class="sc">;</span></li><li>        <span class="i">$x</span>++<span class="sc">;</span></li><li>    <span class="s">}</span></li><li>    <a class="l_k" href="functions/print.html">print</a> <span class="i">RT_79908</span><span class="s">(</span><span class="s">)</span><span class="sc">;</span> <span class="c"># prints 79907</span></li></ol></pre><p>As of Perl 5.22, this buggy behavior, while preserved for backward
compatibility, is detected and emits a deprecation warning.  If you want
the subroutine to be inlined (with no warning), make sure the variable is
not used in a context where it could be modified aside from where it is
declared.</p>
<pre class="verbatim"><ol><li>    <span class="c"># Fine, no warning</span></li><li>    <a class="l_k" href="functions/BEGIN.html">BEGIN</a> <span class="s">{</span></li><li>        <a class="l_k" href="functions/my.html">my</a> <span class="i">$x</span> = <span class="n">54321</span><span class="sc">;</span></li><li>        <span class="i">*INLINED</span> = <span class="i">sub ()</span> <span class="s">{</span> <span class="i">$x</span> <span class="s">}</span><span class="sc">;</span></li><li>    <span class="s">}</span></li><li>    <span class="c"># Warns.  Future Perl versions will stop inlining it.</span></li><li>    <a class="l_k" href="functions/BEGIN.html">BEGIN</a> <span class="s">{</span></li><li>        <a class="l_k" href="functions/my.html">my</a> <span class="i">$x</span><span class="sc">;</span></li><li>        <span class="i">$x</span> = <span class="n">54321</span><span class="sc">;</span></li><li>        <span class="i">*ALSO_INLINED</span> = <span class="i">sub ()</span> <span class="s">{</span> <span class="i">$x</span> <span class="s">}</span><span class="sc">;</span></li><li>    <span class="s">}</span></li></ol></pre><p>Perl 5.22 also introduces the experimental "const" attribute as an
alternative.  (Disable the "experimental::const_attr" warnings if you want
to use it.)  When applied to an anonymous subroutine, it forces the sub to
be called when the <code class="inline"><a class="l_k" href="functions/sub.html">sub</a></code> expression is evaluated.  The return value is
captured and turned into a constant subroutine:</p>
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/my.html">my</a> <span class="i">$x</span> = <span class="n">54321</span><span class="sc">;</span></li><li>    <span class="i">*INLINED</span> = <span class="i">sub </span><span class="co">:</span> <span class="w">const</span> <span class="s">{</span> <span class="i">$x</span> <span class="s">}</span><span class="sc">;</span></li><li>    <span class="i">$x</span>++<span class="sc">;</span></li></ol></pre><p>The return value of <code class="inline"><span class="w">INLINED</span></code>
 in this example will always be 54321,
regardless of later modifications to $x.  You can also put any arbitrary
code inside the sub, at it will be executed immediately and its return
value captured the same way.</p>
<p>If you really want a subroutine with a <code class="inline"><span class="s">(</span><span class="s">)</span></code>
 prototype that returns a
lexical variable you can easily force it to not be inlined by adding
an explicit <code class="inline"><a class="l_k" href="functions/return.html">return</a></code>:</p>
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/BEGIN.html">BEGIN</a> <span class="s">{</span></li><li>        <a class="l_k" href="functions/my.html">my</a> <span class="i">$x</span> = <span class="n">79907</span><span class="sc">;</span></li><li>        <span class="i">*RT_79908</span> = <span class="i">sub ()</span> <span class="s">{</span> <a class="l_k" href="functions/return.html">return</a> <span class="i">$x</span> <span class="s">}</span><span class="sc">;</span></li><li>        <span class="i">$x</span>++<span class="sc">;</span></li><li>    <span class="s">}</span></li><li>    <a class="l_k" href="functions/print.html">print</a> <span class="i">RT_79908</span><span class="s">(</span><span class="s">)</span><span class="sc">;</span> <span class="c"># prints 79908</span></li></ol></pre><p>The easiest way to tell if a subroutine was inlined is by using
<a href="B/Deparse.html">B::Deparse</a>.  Consider this example of two subroutines returning
<code class="inline"><span class="n">1</span></code>
, one with a <code class="inline"><span class="s">(</span><span class="s">)</span></code>
 prototype causing it to be inlined, and one
without (with deparse output truncated for clarity):</p>
<pre class="verbatim"><ol><li> <span class="i">$ perl</span> -<span class="w">MO</span>=<span class="w">Deparse</span> -<a class="l_k" href="functions/le.html">le</a> <span class="q">&#39;sub ONE { 1 } if (ONE) { print ONE if ONE }&#39;</span></li><li><a name="ONE"></a> sub <span class="m">ONE</span> <span class="s">{</span></li><li>     <span class="n">1</span><span class="sc">;</span></li><li> <span class="s">}</span></li><li> <a class="l_k" href="functions/if.html">if</a> <span class="s">(</span><span class="i">ONE</span> <span class="s">)</span> <span class="s">{</span></li><li>     <a class="l_k" href="functions/print.html">print</a> <span class="i">ONE</span><span class="s">(</span><span class="s">)</span> <a class="l_k" href="functions/if.html">if</a> <span class="i">ONE</span> <span class="sc">;</span></li><li> <span class="s">}</span></li><li> <span class="i">$ perl</span> -<span class="w">MO</span>=<span class="w">Deparse</span> -<a class="l_k" href="functions/le.html">le</a> <span class="q">&#39;sub ONE () { 1 } if (ONE) { print ONE if ONE }&#39;</span></li><li><a name="ONE-1"></a> sub <span class="m">ONE ()</span> <span class="s">{</span> <span class="n">1</span> <span class="s">}</span></li><li> <a class="l_k" href="functions/do.html">do</a> <span class="s">{</span></li><li>     <a class="l_k" href="functions/print.html">print</a> <span class="n">1</span></li><li> <span class="s">}</span><span class="sc">;</span></li></ol></pre><p>If you redefine a subroutine that was eligible for inlining, you'll
get a warning by default.  You can use this warning to tell whether or
not a particular subroutine is considered inlinable, since it's
different than the warning for overriding non-inlined subroutines:</p>
<pre class="verbatim"><ol><li>    <span class="i">$ perl</span> -<span class="w">e</span> <span class="q">&#39;sub one () {1} sub one () {2}&#39;</span></li><li>    <span class="w">Constant</span> <span class="w">subroutine</span> <span class="w">one</span> <span class="w">redefined</span> <span class="w">at</span> -e <span class="w">line</span> <span class="n">1.</span></li><li>    <span class="i">$ perl</span> -<span class="w">we</span> <span class="q">&#39;sub one {1} sub one {2}&#39;</span></li><li>    <span class="w">Subroutine</span> <span class="w">one</span> <span class="w">redefined</span> <span class="w">at</span> -e <span class="w">line</span> <span class="n">1.</span></li></ol></pre><p>The warning is considered severe enough not to be affected by the
<b>-w</b> switch (or its absence) because previously compiled invocations
of the function will still be using the old value of the function.  If
you need to be able to redefine the subroutine, you need to ensure
that it isn't inlined, either by dropping the <code class="inline"><span class="s">(</span><span class="s">)</span></code>
 prototype (which
changes calling semantics, so beware) or by thwarting the inlining
mechanism in some other way, e.g. by adding an explicit <code class="inline"><a class="l_k" href="functions/return.html">return</a></code>, as
mentioned above:</p>
<pre class="verbatim"><ol><li><a name="not_inlined"></a>    sub <span class="m">not_inlined ()</span> <span class="s">{</span> <a class="l_k" href="functions/return.html">return</a> <span class="n">23</span> <span class="s">}</span></li></ol></pre><a name="Overriding-Built-in-Functions"></a><h2>Overriding Built-in Functions
   </h2>
<p>Many built-in functions may be overridden, though this should be tried
only occasionally and for good reason.  Typically this might be
done by a package attempting to emulate missing built-in functionality
on a non-Unix system.</p>
<p>Overriding may be done only by importing the name from a module at
compile time--ordinary predeclaration isn't good enough.  However, the
<code class="inline"><a class="l_k" href="functions/use.html">use</a> <span class="w">subs</span></code>
 pragma lets you, in effect, predeclare subs
via the import syntax, and these names may then override built-in ones:</p>
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/use.html">use</a> <span class="w">subs</span> <span class="q">&#39;chdir&#39;</span><span class="cm">,</span> <span class="q">&#39;chroot&#39;</span><span class="cm">,</span> <span class="q">&#39;chmod&#39;</span><span class="cm">,</span> <span class="q">&#39;chown&#39;</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/chdir.html">chdir</a> <span class="i">$somewhere</span><span class="sc">;</span></li><li><a name="chdir"></a>    sub <span class="m">chdir</span> <span class="s">{</span> ... <span class="s">}</span></li></ol></pre><p>To unambiguously refer to the built-in form, precede the
built-in name with the special package qualifier <code class="inline"><span class="w">CORE::</span></code>
.  For example,
saying <code class="inline"><span class="i">CORE::open</span><span class="s">(</span><span class="s">)</span></code>
 always refers to the built-in <code class="inline"><a class="l_k" href="functions/open.html">open()</a></code>, even
if the current package has imported some other subroutine called
<code class="inline"><span class="i">&amp;open</span><span class="s">(</span><span class="s">)</span></code>
 from elsewhere.  Even though it looks like a regular
function call, it isn't: the CORE:: prefix in that case is part of Perl's
syntax, and works for any keyword, regardless of what is in the CORE
package.  Taking a reference to it, that is, <code class="inline">\<span class="i">&amp;CORE::open</span></code>
, only works
for some keywords.  See <a href="CORE.html">CORE</a>.</p>
<p>Library modules should not in general export built-in names like <code class="inline"><a class="l_k" href="functions/open.html">open</a></code>
or <code class="inline"><a class="l_k" href="functions/chdir.html">chdir</a></code> as part of their default <code class="inline"><span class="i">@EXPORT</span></code>
 list, because these may
sneak into someone else's namespace and change the semantics unexpectedly.
Instead, if the module adds that name to <code class="inline"><span class="i">@EXPORT_OK</span></code>
, then it's
possible for a user to import the name explicitly, but not implicitly.
That is, they could say</p>
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/use.html">use</a> <span class="w">Module</span> <span class="q">&#39;open&#39;</span><span class="sc">;</span></li></ol></pre><p>and it would import the <code class="inline"><a class="l_k" href="functions/open.html">open</a></code> override.  But if they said</p>
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/use.html">use</a> <span class="w">Module</span><span class="sc">;</span></li></ol></pre><p>they would get the default imports without overrides.</p>
<p>The foregoing mechanism for overriding built-in is restricted, quite
deliberately, to the package that requests the import.  There is a second
method that is sometimes applicable when you wish to override a built-in
everywhere, without regard to namespace boundaries.  This is achieved by
importing a sub into the special namespace <code class="inline"><span class="w">CORE::GLOBAL::</span></code>
.  Here is an
example that quite brazenly replaces the <code class="inline"><a class="l_k" href="functions/glob.html">glob</a></code> operator with something
that understands regular expressions.</p>
<pre class="verbatim"><ol><li><a name="package-REGlob"></a>    package <span class="i">REGlob</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/require.html">require</a> <span class="w">Exporter</span><span class="sc">;</span></li><li>    <span class="i">@ISA</span> = <span class="q">&#39;Exporter&#39;</span><span class="sc">;</span></li><li>    <span class="i">@EXPORT_OK</span> = <span class="q">&#39;glob&#39;</span><span class="sc">;</span></li><li></li><li><a name="import"></a>    sub <span class="m">import</span> <span class="s">{</span></li><li>	<a class="l_k" href="functions/my.html">my</a> <span class="i">$pkg</span> = <a class="l_k" href="functions/shift.html">shift</a><span class="sc">;</span></li><li>	<a class="l_k" href="functions/return.html">return</a> unless <span class="i">@_</span><span class="sc">;</span></li><li>	<a class="l_k" href="functions/my.html">my</a> <span class="i">$sym</span> = <a class="l_k" href="functions/shift.html">shift</a><span class="sc">;</span></li><li>	<a class="l_k" href="functions/my.html">my</a> <span class="i">$where</span> = <span class="s">(</span><span class="i">$sym</span> =~ <span class="q">s/^GLOBAL_//</span> ? <span class="q">&#39;CORE::GLOBAL&#39;</span> <span class="co">:</span> <a class="l_k" href="functions/caller.html">caller</a><span class="s">(</span><span class="n">0</span><span class="s">)</span><span class="s">)</span><span class="sc">;</span></li><li>	<span class="i">$pkg</span><span class="i">-&gt;export</span><span class="s">(</span><span class="i">$where</span><span class="cm">,</span> <span class="i">$sym</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></li><li><a name="glob"></a>    sub <span class="m">glob</span> <span class="s">{</span></li><li>	<a class="l_k" href="functions/my.html">my</a> <span class="i">$pat</span> = <a class="l_k" href="functions/shift.html">shift</a><span class="sc">;</span></li><li>	<a class="l_k" href="functions/my.html">my</a> <span class="i">@got</span><span class="sc">;</span></li><li>	if <span class="s">(</span><a class="l_k" href="functions/opendir.html">opendir</a> <a class="l_k" href="functions/my.html">my</a> <span class="i">$d</span><span class="cm">,</span> <span class="q">&#39;.&#39;</span><span class="s">)</span> <span class="s">{</span> </li><li>	    <span class="i">@got</span> = <a class="l_k" href="functions/grep.html">grep</a> <span class="q">/$pat/</span><span class="cm">,</span> <a class="l_k" href="functions/readdir.html">readdir</a> <span class="i">$d</span><span class="sc">;</span> </li><li>	    <a class="l_k" href="functions/closedir.html">closedir</a> <span class="i">$d</span><span class="sc">;</span>   </li><li>	<span class="s">}</span></li><li>	<a class="l_k" href="functions/return.html">return</a> <span class="i">@got</span><span class="sc">;</span></li><li>    <span class="s">}</span></li><li>    <span class="n">1</span><span class="sc">;</span></li></ol></pre><p>And here's how it could be (ab)used:</p>
<pre class="verbatim"><ol><li>    <span class="c">#use REGlob &#39;GLOBAL_glob&#39;;	    # override glob() in ALL namespaces</span></li><li><a name="package-Foo"></a>    package <span class="i">Foo</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/use.html">use</a> <span class="w">REGlob</span> <span class="q">&#39;glob&#39;</span><span class="sc">;</span>		    <span class="c"># override glob() in Foo:: only</span></li><li>    <a class="l_k" href="functions/print.html">print</a> for <span class="q">&lt;^[a-z_]+\.pm\$&gt;</span><span class="sc">;</span>	    <span class="c"># show all pragmatic modules</span></li></ol></pre><p>The initial comment shows a contrived, even dangerous example.
By overriding <code class="inline"><a class="l_k" href="functions/glob.html">glob</a></code> globally, you would be forcing the new (and
subversive) behavior for the <code class="inline"><a class="l_k" href="functions/glob.html">glob</a></code> operator for <i>every</i> namespace,
without the complete cognizance or cooperation of the modules that own
those namespaces.  Naturally, this should be done with extreme caution--if
it must be done at all.</p>
<p>The <code class="inline"><span class="w">REGlob</span></code>
 example above does not implement all the support needed to
cleanly override perl's <code class="inline"><a class="l_k" href="functions/glob.html">glob</a></code> operator.  The built-in <code class="inline"><a class="l_k" href="functions/glob.html">glob</a></code> has
different behaviors depending on whether it appears in a scalar or list
context, but our <code class="inline"><span class="w">REGlob</span></code>
 doesn't.  Indeed, many perl built-in have such
context sensitive behaviors, and these must be adequately supported by
a properly written override.  For a fully functional example of overriding
<code class="inline"><a class="l_k" href="functions/glob.html">glob</a></code>, study the implementation of <code class="inline"><span class="w">File::DosGlob</span></code>
 in the standard
library.</p>
<p>When you override a built-in, your replacement should be consistent (if
possible) with the built-in native syntax.  You can achieve this by using
a suitable prototype.  To get the prototype of an overridable built-in,
use the <code class="inline"><a class="l_k" href="functions/prototype.html">prototype</a></code> function with an argument of <code class="inline"><span class="q">&quot;CORE::builtin_name&quot;</span></code>

(see <a href="functions/prototype.html">prototype</a>).</p>
<p>Note however that some built-ins can't have their syntax expressed by a
prototype (such as <code class="inline"><a class="l_k" href="functions/system.html">system</a></code> or <code class="inline"><a class="l_k" href="functions/chomp.html">chomp</a></code>).  If you override them you won't
be able to fully mimic their original syntax.</p>
<p>The built-ins <code class="inline"><a class="l_k" href="functions/do.html">do</a></code>, <code class="inline"><a class="l_k" href="functions/require.html">require</a></code> and <code class="inline"><a class="l_k" href="functions/glob.html">glob</a></code> can also be overridden, but due
to special magic, their original syntax is preserved, and you don't have
to define a prototype for their replacements.  (You can't override the
<code class="inline"><a class="l_k" href="functions/do.html">do</a> <span class="w">BLOCK</span></code>
 syntax, though).</p>
<p><code class="inline"><a class="l_k" href="functions/require.html">require</a></code> has special additional dark magic: if you invoke your
<code class="inline"><a class="l_k" href="functions/require.html">require</a></code> replacement as <code class="inline"><a class="l_k" href="functions/require.html">require</a> <span class="w">Foo::Bar</span></code>
, it will actually receive
the argument <code class="inline"><span class="q">&quot;Foo/Bar.pm&quot;</span></code>
 in @_.  See <a href="functions/require.html">require</a>.</p>
<p>And, as you'll have noticed from the previous example, if you override
<code class="inline"><a class="l_k" href="functions/glob.html">glob</a></code>, the <code class="inline"><span class="q">&lt;*&gt;</span></code>
 glob operator is overridden as well.</p>
<p>In a similar fashion, overriding the <code class="inline"><a class="l_k" href="functions/readline.html">readline</a></code> function also overrides
the equivalent I/O operator <code class="inline"><span class="q">&lt;FILEHANDLE&gt;</span></code>
.  Also, overriding
<code class="inline"><a class="l_k" href="functions/readpipe.html">readpipe</a></code> also overrides the operators <code class="inline"><span class="q">``</span></code>
 and <code class="inline"><a class="l_k" href="functions/qx.html">qx//</a></code>.</p>
<p>Finally, some built-ins (e.g. <code class="inline"><a class="l_k" href="functions/exists.html">exists</a></code> or <code class="inline"><a class="l_k" href="functions/grep.html">grep</a></code>) can't be overridden.</p>
<a name="Autoloading"></a><h2>Autoloading
 </h2>
<p>If you call a subroutine that is undefined, you would ordinarily
get an immediate, fatal error complaining that the subroutine doesn't
exist.  (Likewise for subroutines being used as methods, when the
method doesn't exist in any base class of the class's package.)
However, if an <code class="inline">AUTOLOAD</code>
 subroutine is defined in the package or
packages used to locate the original subroutine, then that
<code class="inline">AUTOLOAD</code>
 subroutine is called with the arguments that would have
been passed to the original subroutine.  The fully qualified name
of the original subroutine magically appears in the global $AUTOLOAD
variable of the same package as the <code class="inline">AUTOLOAD</code>
 routine.  The name
is not passed as an ordinary argument because, er, well, just
because, that's why.  (As an exception, a method call to a nonexistent
<code class="inline"><a class="l_k" href="functions/import.html">import</a></code> or <code class="inline"><span class="w">unimport</span></code>
 method is just skipped instead.  Also, if
the AUTOLOAD subroutine is an XSUB, there are other ways to retrieve the
subroutine name.  See <a href="perlguts.html#Autoloading-with-XSUBs">Autoloading with XSUBs in perlguts</a> for details.)</p>
<p>Many <code class="inline">AUTOLOAD</code>
 routines load in a definition for the requested
subroutine using eval(), then execute that subroutine using a special
form of goto() that erases the stack frame of the <code class="inline">AUTOLOAD</code>
 routine
without a trace.  (See the source to the standard module documented
in <a href="AutoLoader.html">AutoLoader</a>, for example.)  But an <code class="inline">AUTOLOAD</code>
 routine can
also just emulate the routine and never define it.   For example,
let's pretend that a function that wasn't defined should just invoke
<code class="inline"><a class="l_k" href="functions/system.html">system</a></code> with those arguments.  All you'd do is:</p>
<pre class="verbatim"><ol><li><a name="AUTOLOAD"></a>    sub <span class="m">AUTOLOAD</span> <span class="s">{</span></li><li>	<a class="l_k" href="functions/my.html">my</a> <span class="i">$program</span> = <span class="i">$AUTOLOAD</span><span class="sc">;</span></li><li>	<span class="i">$program</span> =~ <span class="q">s/.*:://</span><span class="sc">;</span></li><li>	<a class="l_k" href="functions/system.html">system</a><span class="s">(</span><span class="i">$program</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>    <span class="i">date</span><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li>    <span class="i">who</span><span class="s">(</span><span class="q">&#39;am&#39;</span><span class="cm">,</span> <span class="q">&#39;i&#39;</span><span class="s">)</span><span class="sc">;</span></li><li>    <span class="i">ls</span><span class="s">(</span><span class="q">&#39;-l&#39;</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>In fact, if you predeclare functions you want to call that way, you don't
even need parentheses:</p>
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/use.html">use</a> <span class="w">subs</span> <span class="q">qw(date who ls)</span><span class="sc">;</span></li><li>    <span class="w">date</span><span class="sc">;</span></li><li>    <span class="w">who</span> <span class="q">&quot;am&quot;</span><span class="cm">,</span> <span class="q">&quot;i&quot;</span><span class="sc">;</span></li><li>    <span class="w">ls</span> <span class="q">'-l'</span><span class="sc">;</span></li></ol></pre><p>A more complete example of this is the Shell module on CPAN, which
can treat undefined subroutine calls as calls to external programs.</p>
<p>Mechanisms are available to help modules writers split their modules
into autoloadable files.  See the standard AutoLoader module
described in <a href="AutoLoader.html">AutoLoader</a> and in <a href="AutoSplit.html">AutoSplit</a>, the standard
SelfLoader modules in <a href="SelfLoader.html">SelfLoader</a>, and the document on adding C
functions to Perl code in <a href="perlxs.html">perlxs</a>.</p>
<a name="Subroutine-Attributes"></a><h2>Subroutine Attributes
  </h2>
<p>A subroutine declaration or definition may have a list of attributes
associated with it.  If such an attribute list is present, it is
broken up at space or colon boundaries and treated as though a
<code class="inline"><a class="l_k" href="functions/use.html">use</a> <span class="w">attributes</span></code>
 had been seen.  See <a href="attributes.html">attributes</a> for details
about what attributes are currently supported.
Unlike the limitation with the obsolescent <code class="inline"><a class="l_k" href="functions/use.html">use</a> <span class="w">attrs</span></code>
, the
<code class="inline"><span class="j">sub :</span> <span class="w">ATTRLIST</span></code>
 syntax works to associate the attributes with
a pre-declaration, and not just with a subroutine definition.</p>
<p>The attributes must be valid as simple identifier names (without any
punctuation other than the '_' character).  They may have a parameter
list appended, which is only checked for whether its parentheses ('(',')')
nest properly.</p>
<p>Examples of valid syntax (even though the attributes are unknown):</p>
<pre class="verbatim"><ol><li><a name="fnord"></a>    sub <span class="m">fnord (&amp;\%)</span> <span class="co">:</span> <span class="q">switch(10,foo(7,3))</span>  <span class="co">:</span>  <span class="w">expensive</span><span class="sc">;</span></li><li><a name="plugh"></a>    sub <span class="m">plugh ()</span> <span class="co">:</span> <span class="q">Ugly(&#39;\(&quot;)</span> <span class="co">:</span><span class="w">Bad</span><span class="sc">;</span></li><li><a name="xyzzy"></a>    sub <span class="m">xyzzy</span> <span class="co">:</span> <span class="w">_5x5</span> <span class="s">{</span> ... <span class="s">}</span></li></ol></pre><p>Examples of invalid syntax:</p>
<pre class="verbatim"><ol><li>    sub fnord : switch(10,foo(); # ()-string not balanced</li><li>    sub snoid : Ugly('(');	  # ()-string not balanced</li><li>    sub xyzzy : 5x5;		  # "5x5" not a valid identifier</li><li>    sub plugh : Y2::north;	  # "Y2::north" not a simple identifier</li><li>    sub snurt : foo + bar;	  # "+" not a colon or space</li></ol></pre><p>The attribute list is passed as a list of constant strings to the code
which associates them with the subroutine.  In particular, the second example
of valid syntax above currently looks like this in terms of how it's
parsed and invoked:</p>
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/use.html">use</a> <span class="w">attributes</span> <span class="w">__PACKAGE__</span><span class="cm">,</span> \<span class="i">&amp;plugh</span><span class="cm">,</span> <span class="q">q[Ugly(&#39;\(&quot;)]</span><span class="cm">,</span> <span class="q">&#39;Bad&#39;</span><span class="sc">;</span></li></ol></pre><p>For further details on attribute lists and their manipulation,
see <a href="attributes.html">attributes</a> and <a href="Attribute/Handlers.html">Attribute::Handlers</a>.</p>
<a name="SEE-ALSO"></a><h1>SEE ALSO</h1>
<p>See <a href="perlref.html#Function-Templates">Function Templates in perlref</a> for more about references and closures.
See <a href="perlxs.html">perlxs</a> if you'd like to learn about calling C subroutines from Perl.  
See <a href="perlembed.html">perlembed</a> if you'd like to learn about calling Perl subroutines from C.  
See <a href="perlmod.html">perlmod</a> to learn about bundling up your functions in separate files.
See <a href="perlmodlib.html">perlmodlib</a> to learn what library modules come standard on your system.
See <a href="perlootut.html">perlootut</a> to learn how to make object method calls.</p>




  <div id="page_index" class="hud_container">
    <div id="page_index_header" class="hud_header">
      <div id="page_index_close" class="hud_close"><a href="#" onClick="pageIndex.hide();return false;"></a></div>
      <div id="page_index_title" class="hud_title"><span class="hud_span_top">Page index</span></div>
      <div id="page_index_topright" class="hud_topright"></div>
    </div>
    <div id="page_index_content" class="hud_content">
      <ul><li><a href="#NAME">NAME
 </a><li><a href="#SYNOPSIS">SYNOPSIS</a><li><a href="#DESCRIPTION">DESCRIPTION</a><ul><li><a href="#Signatures">Signatures</a><li><a href="#Private-Variables-via-my()">Private Variables via my()
    
 </a><li><a href="#Persistent-Private-Variables">Persistent Private Variables
     </a><li><a href="#Temporary-Values-via-local()">Temporary Values via local()
   
</a><li><a href="#Lvalue-subroutines">Lvalue subroutines
 </a><li><a href="#Lexical-Subroutines">Lexical Subroutines
   </a><li><a href="#Passing-Symbol-Table-Entries-(typeglobs)">Passing Symbol Table Entries (typeglobs)
 </a><li><a href="#When-to-Still-Use-local()">When to Still Use local()
 </a><li><a href="#Pass-by-Reference">Pass by Reference
  </a><li><a href="#Prototypes">Prototypes
 </a><li><a href="#Constant-Functions">Constant Functions
</a><li><a href="#Overriding-Built-in-Functions">Overriding Built-in Functions
   </a><li><a href="#Autoloading">Autoloading
 </a><li><a href="#Subroutine-Attributes">Subroutine Attributes
  </a></ul><li><a href="#SEE-ALSO">SEE ALSO</a></ul>
    </div>
    <div id="page_index_footer" class="hud_footer">
      <div id="page_index_bottomleft" class="hud_bottomleft"></div>
      <div id="page_index_bottom" class="hud_bottom"><span class="hud_span_bottom"></span></div>
      <div id="page_index_resize" class="hud_resize"></div>
    </div>
  </div>


	    &nbsp;
          </div>
          <div id="content_footer">
          </div>
        </div>
        <div class="clear"></div>
      </div>
      
    <div id="footer">
      <div id="footer_content">
        <div id="footer_strapline">
          perldoc.perl.org - Official documentation for the Perl programming language
        </div>
        <div id="footer_links">
          <div id="address">
            <p class="name">Contact details</p>
            <p class="address">
	      Site maintained by <a href="mailto:jj@jonallen.info">Jon Allen (JJ)</a><br>
	    </p>
            <p class="contact">
              Documentation maintained by the <a href="http://lists.cpan.org/showlist.cgi?name=perl5-porters">Perl 5 Porters</a>
            </p>
          </div>
          <ul class="f1">
            <li>Manual
              <ul class="f2">
                <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">Changes</a>
              </ul>
            <li>Reference
              <ul class="f2">
                <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">Variables</a>
              </ul>
            <li>Modules
              <ul class="f2">
                <li><a href="index-modules-A.html">Modules</a>
                <li><a href="index-pragmas.html">Pragmas</a>
                <li><a href="index-utilities.html">Utilities</a>
              </ul>
            <li>Misc
              <ul class="f2">
                <li><a href="index-licence.html">License</a>
                <li><a href="index-internals.html">Internals</a>
                <li><a href="index-platforms.html">Platforms</a>
              </ul>          </ul>
          <div class="clear"></div>
        </div>
      </div>
      <div id="footer_end">
      </div>
    </div>
      
    </div>
      <script language="JavaScript" type="text/javascript" src="static/exploreperl.js"></script>
      <script language="JavaScript" src="static/combined-20100403.js" type="text/javascript"></script>
<script language="JavaScript" type="text/javascript">
  perldoc.setPath(0);
  perldoc.pageName    = 'perlsub';
  perldoc.pageAddress = 'perlsub.html';
  perldoc.contentPage = 1;
  explorePerl.render();
  explorePerl.addEvents('explore_anchor');
</script>
    
  </body>
</html>