Visit https://ebooknice.

com to download the full version and

explore more ebooks

(Ebook) Perl: The Complete Reference by Brown,

Martin C. ISBN 9780072129502, 0072129506

_____ Click the link below to download _____

https://ebooknice.com/product/perl-the-complete-
reference-33188080

Explore and download more ebooks at ebooknice.com

Here are some recommended products that might interest you.
You can download now and explore!

(Ebook) Perl: The Complete Reference by Martin C. Brown ISBN

9780072129502, 9780072194258, 0072129506, 0072194251

https://ebooknice.com/product/perl-the-complete-reference-918684

ebooknice.com

(Ebook) Biota Grow 2C gather 2C cook by Loucas, Jason; Viles, James

ISBN 9781459699816, 9781743365571, 9781925268492, 1459699815,
1743365578, 1925268497

https://ebooknice.com/product/biota-grow-2c-gather-2c-cook-6661374

ebooknice.com

(Ebook) XML Processing with Perl, Python, and PHP by Martin C. Brown
ISBN 0782140211

https://ebooknice.com/product/xml-processing-with-perl-python-and-
php-2143994

ebooknice.com

(Ebook) XML Processing with Perl, Python, and PHP by Martin C. Brown
ISBN 9780782140217, 0782140211

https://ebooknice.com/product/xml-processing-with-perl-python-and-
php-4433582

ebooknice.com
(Ebook) Matematik 5000+ Kurs 2c Lärobok by Lena Alfredsson, Hans
Heikne, Sanna Bodemyr ISBN 9789127456600, 9127456609

https://ebooknice.com/product/matematik-5000-kurs-2c-larobok-23848312

ebooknice.com

(Ebook) SAT II Success MATH 1C and 2C 2002 (Peterson's SAT II Success)

by Peterson's ISBN 9780768906677, 0768906679

https://ebooknice.com/product/sat-ii-success-
math-1c-and-2c-2002-peterson-s-sat-ii-success-1722018

ebooknice.com

(Ebook) Master SAT II Math 1c and 2c 4th ed (Arco Master the SAT
Subject Test: Math Levels 1 & 2) by Arco ISBN 9780768923049,
0768923042

https://ebooknice.com/product/master-sat-ii-math-1c-and-2c-4th-ed-
arco-master-the-sat-subject-test-math-levels-1-2-2326094

ebooknice.com

(Ebook) Cambridge IGCSE and O Level History Workbook 2C - Depth Study:

the United States, 1919-41 2nd Edition by Benjamin Harrison ISBN
9781398375147, 9781398375048, 1398375144, 1398375047

https://ebooknice.com/product/cambridge-igcse-and-o-level-history-
workbook-2c-depth-study-the-united-states-1919-41-2nd-edition-53538044

ebooknice.com

(Ebook) C++: The Complete Reference by Herbert Schildt ISBN

9780070532465, 007053246X

https://ebooknice.com/product/c-the-complete-reference-7304404

ebooknice.com
TE
AM
FL
Y
Perl: The Complete Reference
Second Edition
This page intentionally left blank.
 Perl:
The Complete Reference
Second Edition
Martin C. Brown

Osborne/McGraw-Hill
New York Chicago San Francisco
Lisbon London Madrid Mexico City
Milan New Delhi San Juan
Seoul Singapore Sydney Toronto
Copyright © 2001 by The McGraw-Hill Companies. All rights reserved. Manufactured in the United States of America. Except as per-
mitted under the United States Copyright Act of 1976, no part of this publication may be reproduced or distributed in any form or by
any means, or stored in a database or retrieval system, without the prior written permission of the publisher.

0-07-219425-1

The material in this eBook also appears in the print version of this title: 0-07-212950-6.

All trademarks are trademarks of their respective owners. Rather than put a trademark symbol after every occurrence of a trade-
marked name, we use names in an editorial fashion only, and to the benefit of the trademark owner, with no intention of infringe-
ment of the trademark. Where such designations appear in this book, they have been printed with initial caps.
McGraw-Hill eBooks are available at special quantity discounts to use as premiums and sales promotions, or for use in corporate
training programs. For more information, please contact George Hoare, Special Sales, at [email protected] or (212)
904-4069.

TERMS OF USE
This is a copyrighted work and The McGraw-Hill Companies, Inc. (“McGraw-Hill”) and its licensors reserve all rights in and to the
work. Use of this work is subject to these terms. Except as permitted under the Copyright Act of 1976 and the right to store and
retrieve one copy of the work, you may not decompile, disassemble, reverse engineer, reproduce, modify, create derivative works
based upon, transmit, distribute, disseminate, sell, publish or sublicense the work or any part of it without McGraw-Hill’s prior con-
sent. You may use the work for your own noncommercial and personal use; any other use of the work is strictly prohibited. Your
right to use the work may be terminated if you fail to comply with these terms.
THE WORK IS PROVIDED “AS IS”. McGRAW-HILL AND ITS LICENSORS MAKE NO GUARANTEES OR WARRANTIES
AS TO THE ACCURACY, ADEQUACY OR COMPLETENESS OF OR RESULTS TO BE OBTAINED FROM USING THE
WORK, INCLUDING ANY INFORMATION THAT CAN BE ACCESSED THROUGH THE WORK VIA HYPERLINK OR
OTHERWISE, AND EXPRESSLY DISCLAIM ANY WARRANTY, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
TO IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. McGraw-Hill and its
licensors do not warrant or guarantee that the functions contained in the work will meet your requirements or that its operation will
be uninterrupted or error free. Neither McGraw-Hill nor its licensors shall be liable to you or anyone else for any inaccuracy, error
or omission, regardless of cause, in the work or for any damages resulting therefrom. McGraw-Hill has no responsibility for the con-
tent of any information accessed through the work. Under no circumstances shall McGraw-Hill and/or its licensors be liable for any
indirect, incidental, special, punitive, consequential or similar damages that result from the use of or inability to use the work, even
if any of them has been advised of the possibility of such damages. This limitation of liability shall apply to any claim or cause what-
soever whether such claim or cause arises in contract, tort or otherwise.

DOI: 10.1036/0072194251
 To Darcy and Leon, two little kittens
who do try to help daddy with the typing,
but usually just end up typing
“jjskdjjvoookko000000000000000000000”
 About the Author
Martin C. Brown is the author of six Perl
books, including the first edition of Perl: The
Complete Reference, Perl Programmer’s Reference,
ActivePerl Developer’s Guide, and Debugging
Perl. In addition to Perl, he has worked in
Python, Java, Visual Basic, and other languages.
A programmer for 15 years, he is the former
IT director of a large advertising agency
dealing with blue chip clients such as Hewlett
Packard, Oracle, and Cable & Wireless.

Copyright 2001 The McGraw-Hill Companies, Inc. Click Here for Terms of Use.
Contents at a Glance
Part I Fundamentals

1 Perl Backgrounder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2 Perl Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
3 Perl Parsing Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
4 Variables and Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
5 Statements and Control Structures . . . . . . . . . . . . . . . . . . 109
6 Subroutines, Packages, and Modules . . . . . . . . . . . . . . . . 123
7 Working with Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
8 Data Manipulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
9 Errors and Trapping Them . . . . . . . . . . . . . . . . . . . . . . . . . 269

Part II Programming with Perl

10 Complex Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . 287

11 System Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
12 Networking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361

vii
Copyright 2001 The McGraw-Hill Companies, Inc. Click Here for Terms of Use.
viii Perl: The Complete Reference

13 Database Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391

14 Interprocess Communication . . . . . . . . . . . . . . . . . . . . . . . 447
15 Other Execution Enhancements . . . . . . . . . . . . . . . . . . . . . 479

Part III Developing Applications

16 User Interface Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 513

17 Advanced User Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . 529
18 Developing for the World Wide Web (WWW) . . . . . . . . 575
19 Controlling Execution with Pragmas . . . . . . . . . . . . . . . . 611
20 Extending and Embedding Perl . . . . . . . . . . . . . . . . . . . . . 641

Part IV Fine-Tuning Applications

21 Debugging and Tuning . . . . . . . . . . . . . . . . . . . . . . . . . . . . 715

22 Perl Compiler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 773
23 Perl Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 803
24 Cross-Platform Migration Traps . . . . . . . . . . . . . . . . . . . . 825
25 Distributing Modules and Applications . . . . . . . . . . . . . . 837

Part V Appendixes

A Function Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 869

B Standard Perl Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 993
C Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1141

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1153
 Contents
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxiii
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxv

Part I
Fundamentals

1 Perl Backgrounder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Versions and Naming Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Perl, perl or PeRl? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Life Before Perl 5.6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Perl History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Main Perl Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Perl Is Free . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Perl Is Simple to Learn, Concise, and Easy to Read . . . . . . 7
Perl Is Fast . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Perl Is Extensible . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Perl Has Flexible Data Types . . . . . . . . . . . . . . . . . . . . . . . . . 8
Perl Is Object Oriented . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Perl Is Collaborative . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Compiler or Interpreter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

ix
Copyright 2001 The McGraw-Hill Companies, Inc. Click Here for Terms of Use.
x Perl: The Complete Reference

Similar Programming Languages . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Unix Shells . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Tcl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Python . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
C/C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
awk/gawk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Popular “Mythconceptions” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
It’s Only for the Web . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
It’s Not Maintenance Friendly . . . . . . . . . . . . . . . . . . . . . . . . 13
It’s Only for Hackers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
It’s a Scripting Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
There’s No Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
All Perl Programs Are Free . . . . . . . . . . . . . . . . . . . . . . . . . . 14
There’s No Development Environment . . . . . . . . . . . . . . . . 14
Perl Is a GNU Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Perl Is Difficult to Learn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Perl Success Stories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Y
FL
2 Perl Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Installing and Using Perl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
AM

Writing a Perl Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Perl Under Unix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Perl Under Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Perl Under Mac OS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
TE

Perl Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Subroutines (Functions) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Where Next? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

3 Perl Parsing Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

The Execution Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Syntax and Parsing Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Basic Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Component Identity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Operators and Precedence . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Bare Words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Contexts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Logical Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Perl Coding Styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

Team-Fly®
 Contents xi

4 Variables and Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Basic Naming Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Scalar Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Literals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Numeric Literals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
String Literals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Quotes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Interpolation of Array Values . . . . . . . . . . . . . . . . . . . . . . . . 81
Here Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Hashes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Typeglobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
The defined Function and the Undefined Value . . . . . . . . . . . . . . . . 97
Default Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Other Tokens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Special Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

5 Statements and Control Structures . . . . . . . . . . . . . . . . . 109

Code Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Conditional Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Loops . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
while Loops . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
until Loops . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
for Loops . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
foreach Loops . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
The continue Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Loop Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Unqualified Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
goto . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

6 Subroutines, Packages, and Modules . . . . . . . . . . . . . . . 123

Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Return Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Error Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Prototypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
Package Symbol Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
xii Perl: The Complete Reference

Special Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
Creating Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
The Exporter Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
Comparing use and require . . . . . . . . . . . . . . . . . . . . . . . . . . 150
no . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
do . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
Effects of my . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
Effects of local . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
Effects of our . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
Scope Within Loops . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
Autoloading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158

7 Working with Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

Filehandles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
Opening and Closing Files . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
Reading and Writing Filehandles . . . . . . . . . . . . . . . . . . . . . 172
Locating Your Position Within a File . . . . . . . . . . . . . . . . . . 181
Miscellaneous Control Functions . . . . . . . . . . . . . . . . . . . . . 183
File Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
File Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
Basic File Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
Accessing Directory Entries . . . . . . . . . . . . . . . . . . . . . . . . . . 196
Managing Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
File Control with fcntl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
I/O Control with ioctl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
select . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
File Locking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205

8 Data Manipulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209

Working with Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
abs—the Absolute Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
int—Converting Floating Points to Integers . . . . . . . . . . . . 211
exp—Raising e to the Power . . . . . . . . . . . . . . . . . . . . . . . . . 211
sqrt—the Square Root . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
log—the Logarithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
Trigonometric Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
Conversion Between Bases . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
Conversion Between Characters and Numbers . . . . . . . . . 214
Random Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
Working with Very Small Integers . . . . . . . . . . . . . . . . . . . . 216
 Contents xiii

Working with Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217

String Concatenation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
String Length . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
Case Modifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
End-of-Line Character Removal . . . . . . . . . . . . . . . . . . . . . . 219
String Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
Extracting Substrings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
Stacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
Splicing Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
join . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
split . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
grep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
sort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
reverse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
Regular Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
Pattern Modifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
The Match Operator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
The Substitution Operator . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
Translation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
Regular Expression Elements . . . . . . . . . . . . . . . . . . . . . . . . 242
Regular Expression Variables . . . . . . . . . . . . . . . . . . . . . . . . 258
Regular Expression Extensions/Assertions . . . . . . . . . . . . 259
Precompiling Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
Regular Expression Support Functions . . . . . . . . . . . . . . . . 263
Unicode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
Perl’s Interpretation of Unicode . . . . . . . . . . . . . . . . . . . . . . 266
Unicode Characters in Perl . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
Unicode’s Effects on Perl Code . . . . . . . . . . . . . . . . . . . . . . . 267

9 Errors and Trapping Them . . . . . . . . . . . . . . . . . . . . . . . . 269

Adding Error Checking to Your Scripts . . . . . . . . . . . . . . . . . . . . . . . 270
Error Checking Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
Error Checking Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
What to Check . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
What Not to Check . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
When to Stop Checking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
Don’t Check Things Twice . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
Functions, Return Values, and Nesting . . . . . . . . . . . . . . . . 276
Error Messages and Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
Reporting Errors Within Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
The Warn Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
The Die Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
Directives and Tokens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
xiv Perl: The Complete Reference

Reporting Errors Within Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281

The Carp Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
The Cluck Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
The Croak Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
The Confess Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283

Part II
Programming with Perl

10 Complex Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . 287

Accessing Packed Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
Creating Hard References . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
Dereferencing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
Determining a Reference Type . . . . . . . . . . . . . . . . . . . . . . . 301
Symbolic References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
Complex Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
Arrays of Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
Hashes of Hashes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
Arrays of Hashes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
Hashes of Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
Beyond Two Dimensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
Object Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
Creating and Using Objects . . . . . . . . . . . . . . . . . . . . . . . . . . 322
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
Classes and Inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
Destructors and Garbage Collection . . . . . . . . . . . . . . . . . . . 330
Comparing Perl Objects to Other Languages . . . . . . . . . . . 330
Using tie . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
Creating New tie Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332

11 System Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339

Users and Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
Getting Unix Password Entries . . . . . . . . . . . . . . . . . . . . . . . 341
Getting Unix Group Entries . . . . . . . . . . . . . . . . . . . . . . . . . . 343
Password Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344
Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
gmtime and localtime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
time Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
Comparing Time Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
Converting Dates and Times into Epochs . . . . . . . . . . . . . . 348
 Contents xv

Time Arithmetic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348

times Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
sleep Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
Alarms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353

12 Networking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
Obtaining Network Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364
Hosts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364
Protocols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366
Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367
Networks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368
The Socket Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368
Address Resolution and Conversion . . . . . . . . . . . . . . . . . . 369
Address Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369
Socket Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
Line Termination Constants . . . . . . . . . . . . . . . . . . . . . . . . . . 370
Socket Communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371
Connecting to a Remote Socket . . . . . . . . . . . . . . . . . . . . . . . 371
Listening for Socket Connections . . . . . . . . . . . . . . . . . . . . . 374
Using IO::Socket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380
Client Side . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
Server Side . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
Using IO::Socket and IO::Select . . . . . . . . . . . . . . . . . . . . . . . 382
Getting Socket Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
Closing Sockets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384
Socket Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384
Data Transfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386
Graham Barr’s libnet Bundle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387
Gisle Aas’ LWP Bundle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389

13 Database Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391

Text Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393
Delimited Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
Fixed-Length Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
DBM Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
DBM Implementations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400
DBM Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402
Using Tied DBM Databases . . . . . . . . . . . . . . . . . . . . . . . . . . 403
Converting Between DBM Formats . . . . . . . . . . . . . . . . . . . 406
Using AnyDBM_File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407
GDBM Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408
xvi Perl: The Complete Reference

Berkeley DB Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409

Storing Complex Data in a DBM Database . . . . . . . . . . . . . 418
Relational Databases with DBM . . . . . . . . . . . . . . . . . . . . . . 421
Database File Locking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424
Using the DBI and Win32::ODBC Toolkits . . . . . . . . . . . . . . . . . . . . 425
DBI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425
Win32::ODBC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426
Database Mechanics and Compatibility . . . . . . . . . . . . . . . . 427
Connecting to a Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428
Executing Simple Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . 430
Executing Extended Queries . . . . . . . . . . . . . . . . . . . . . . . . . 431
Closing the Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432
Identifying Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433
Doing More . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433
SQL Refresher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434
SQL Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435

14 Interprocess Communication . . . . . . . . . . . . . . . . . . . . . . 447

Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448
Controlling Perl Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . 449
Process Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449
Process Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449
Process Priority . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450
Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451
Signal Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453
The __WARN__ and __DIE__ Signals . . . . . . . . . . . . . . . . . 455
Sending Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458
Pipes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459
Anonymous Pipes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459
Two-Way Communication . . . . . . . . . . . . . . . . . . . . . . . . . . . 460
Named Pipes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461
Named Pipes Under Windows . . . . . . . . . . . . . . . . . . . . . . . 463
Safe Pipes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467
Executing Additional Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468
Running Other Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468
Replacing the Current Script . . . . . . . . . . . . . . . . . . . . . . . . . 470
Creating Child Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470
Other Function Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477
System V IPC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 478

15 Other Execution Enhancements . . . . . . . . . . . . . . . . . . . . 479

Perl on the Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480
Special Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489
 Contents xvii

Perl Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489

Perl in Perl (eval) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491
Using eval EXPR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 492
Using eval BLOCK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 492
Trapping Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493
Returning Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493
eval and the __DIE__ signal handler . . . . . . . . . . . . . . . . . . 494
Threads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494
How Multitasking Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494
From Multitasking to Multithreading . . . . . . . . . . . . . . . . . 495
Comparing Threads to Multiple Processes . . . . . . . . . . . . . 497
Comparing Threads to select() . . . . . . . . . . . . . . . . . . . . . . . . 498
Threads and Perl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498
Creating a New Thread . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498
Creating a Thread Using an Anonymous Subroutine . . . . 499
Controlling a Thread . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500
Controlling Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 501
Controlling Subroutines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 502
Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 503
Semaphores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 504
Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 504
Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 505
Using Taint Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 505
The Safe and Opcode Modules . . . . . . . . . . . . . . . . . . . . . . . 508

Part III
Developing Applications

16 User Interface Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 513

Processing Command Line Arguments . . . . . . . . . . . . . . . . . . . . . . . 514
Getopt::Std . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 515
Getopt::Long . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 516
Perl’s Reporting Mechanism . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521
Headers and Footers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 525
Format Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526
Format Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 527

17 Advanced User Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . 529

Working with a Terminal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 531
Using Tk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 532
Installing Tk Under Unix . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533
Installing Tk Under Windows . . . . . . . . . . . . . . . . . . . . . . . . 533
Hello from Tk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533
xviii Perl: The Complete Reference

Event Loops . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 537

Widgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 540
Controlling Window Geometry . . . . . . . . . . . . . . . . . . . . . . 563
Easing the Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 567

18 Developing for the World Wide Web (WWW) . . . . . . . 575

HTML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 576
Uniform Resource Locators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 578
Web Operation Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 579
The Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 580
The Common Gateway Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 584
Extracting Form Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 586
Sending Information Back to the Browser . . . . . . . . . . . . . . 589
Document Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 593
Smarter Web Programming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 593
The CGI Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 594
Cookies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 598
Parsing HTML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 601
Parsing XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 602
Debugging and Testing CGI Applications . . . . . . . . . . . . . . . . . . . . . 605
Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 608

19 Controlling Execution with Pragmas . . . . . . . . . . . . . . . 611

Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 612
The $^W Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 614
The Old warnings Pragma . . . . . . . . . . . . . . . . . . . . . . . . . . . 614
Lexical Warnings in Perl 5.6 . . . . . . . . . . . . . . . . . . . . . . . . . . 615
The strict Pragma . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 620
The vars Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 621
The refs Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 623
The subs Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 624
Other Perl Pragmas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 625
attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 625
autouse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 626
base . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 627
blib . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 628
bytes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 628
charnames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 629
constant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 629
diagnostics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 631
fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 633
 Contents xix

filetest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 634
integer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 634
less . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 634
lib . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 635
locale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 636
open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 636
ops . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 636
overload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 637
re . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 637
sigtrap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 638
subs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 639
vars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 640

20 Extending and Embedding Perl . . . . . . . . . . . . . . . . . . . . 641

Perl Internals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 643
Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 644
Internal Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 644
Translator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 646
Opcodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 647
Compilation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 650
Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 652
Perl’s Internal Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 653
Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 654
The Stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 662
Stack Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 668
Internals Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 669
Extending Perl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 669
The Extension Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 670
XS Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 670
SWIG Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 671
Using XS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 672
Embedding Perl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 698
Embedding the Perl Interpreter . . . . . . . . . . . . . . . . . . . . . . . 699
Using a Specific Perl Function . . . . . . . . . . . . . . . . . . . . . . . . 700
Multiplicity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 704
XS Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 705
Cooperating with Other Languages . . . . . . . . . . . . . . . . . . . . . . . . . . 706
Converting Other Languages to Perl . . . . . . . . . . . . . . . . . . 706
Converting Perl to Other Languages . . . . . . . . . . . . . . . . . . 711
Calling Other Languages from Perl . . . . . . . . . . . . . . . . . . . 712
xx Perl: The Complete Reference

Part IV
Fine-Tuning Applications

21 Debugging and Tuning . . . . . . . . . . . . . . . . . . . . . . . . . . . 715

Debugging Techniques . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 717
Using print . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 717
Using caller . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 721
Using eval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 724
Writing a Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 726
Reporting to syslog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 729
Reporting to the Windows NT/2000 Event Log . . . . . . . . . 729
Using a Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 730
Watches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 730
Stepping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 730
Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 731
The Perl Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 731
The ActivePerl Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . 748

Y
Traps for Programmers of Other Languages . . . . . . . . . . . . . . . . . . .
Differences from awk/gawk . . . . . . . . . . . . . . . . . . . . . . . . .
750
750
FL
C Traps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 752
sed Traps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 754
AM

emacs Traps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 754

Shell Script Traps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 754
Python Traps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 755
Optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 757
TE

The Perl Profiler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 758

Profiling by Hand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 765
Optimization Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 766

22 Perl Compiler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 773

Using dump . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 775
Using the Compiler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 776
The Backends . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 777
The perlcc Frontend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 791
Differences Between Interpreted and Compiled Code . . . 795
Comparing Script and Executable Speeds . . . . . . . . . . . . . . . . . . . . . 795
Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 797
Summary Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 800

23 Perl Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 803

Using the Supplied Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . 805
Unix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 808
Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 810
Mac OS/Mac OS X . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 811

Team-Fly®
 Contents xxi

Writing POD Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 812

POD Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 813
Command Paragraph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 813
Ordinary Text Paragraph . . . . . . . . . . . . . . . . . . . . . . . . . . . . 816
Verbatim Paragraph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 816
Escape Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 816
Embedding Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . 816
Converting POD to Other Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . 818
Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 819
HTML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 820
Unix man Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 820
PostScript/PDF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 823
Converting POD to HTML On The Fly . . . . . . . . . . . . . . . . 823

24 Cross-Platform Migration Traps . . . . . . . . . . . . . . . . . . . 825

Function Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 826
Constant Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 827
Execution Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 827
Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 828
Line Termination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 828
Character Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 829
Data Differences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 829
Files and Pathnames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 829
Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 830
Performance and Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 830
Platform Migration Tricks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 831
Determining Your Platform . . . . . . . . . . . . . . . . . . . . . . . . . . 831
Determining the Perl Version . . . . . . . . . . . . . . . . . . . . . . . . 832
Checking for Supported Functions . . . . . . . . . . . . . . . . . . . . 833
Function Overloading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 834

25 Distributing Modules and Applications . . . . . . . . . . . . . 837

Perl Makefiles and ExtUtils::MakeMaker . . . . . . . . . . . . . . . . . . . . . . 838
Perl Makefiles and CPAN . . . . . . . . . . . . . . . . . . . . . . . . . . . 839
Perl Makefiles and PPM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 839
Extension Building and Installation Overview . . . . . . . . . . 840
MakeMaker Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 842
Start with h2xs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 843
MakeMaker Configurable Options . . . . . . . . . . . . . . . . . . . . 845
Creating a Dummy Makefile . . . . . . . . . . . . . . . . . . . . . . . . . 853
Default Makefile Targets . . . . . . . . . . . . . . . . . . . . . . . . . . . . 853
Creating a New Perl Binary . . . . . . . . . . . . . . . . . . . . . . . . . . 854
Targets for Package Builders . . . . . . . . . . . . . . . . . . . . . . . . . 855
Related Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 858
xxii Perl: The Complete Reference

MakeMaker Tricks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 860

Checking for Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . 860
Packing for CPAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 863
Packing for PPM/VPM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 863

Part V
Appendixes

A Function Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 869

-X . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 879
abs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 880
accept . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 881
alarm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 881
atan2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 882
bind . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 882
binmode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 883
bless . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 883
caller . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 884
chdir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 884
chmod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 885
chomp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 885
chop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 886
chown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 886
chr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 887
chroot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 887
close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 888
closedir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 888
connect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 889
continue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 889
cos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 890
crypt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 890
dbmclose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 890
dbmopen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 891
defined . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 892
delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 892
die . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 893
do . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 893
dump . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 894
each . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 895
endgrent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 895
endhostent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 895
endnetent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 896
endprotoent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 896
 Contents xxiii

endpwent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 897
endservent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 897
eof . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 897
eval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 898
exec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 899
exists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 899
exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 900
exp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 900
fcntl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 901
fileno . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 901
flock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 902
fork . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 903
format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 903
formline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 904
getc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 904
getgrent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 904
getgrgid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 905
getgrnam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 906
gethostbyaddr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 906
gethostbyname . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 907
gethostent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 907
getlogin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 908
getnetbyaddr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 908
getnetbyname . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 909
getnetent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 909
getpeername . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 910
getpgrp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 910
getppid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 911
getpriority . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 911
getprotobyname . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 911
getprotobynumber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 912
getprotoent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 912
getpwent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 913
getpwnam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 914
getpwuid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 914
getservbyname . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 915
getservbyport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 915
getservent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 916
getsockname . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 916
getsockopt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 917
glob . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 918
gmtime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 918
goto . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 919
xxiv Perl: The Complete Reference

grep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 920
hex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 920
import . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 921
index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 921
int . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 922
ioctl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 922
join . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 922
keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 923
kill . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 923
last . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 925
lc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 925
lcfirst . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 925
length . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 926
link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 926
listen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 927
local . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 927
localtime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 928
log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 928
lstat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 929
m// . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 929
map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 929
mkdir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 930
msgctl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 930
msgget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 931
msgrcv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 931
msgsnd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 932
my . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 932
next . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 933
no . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 933
oct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 934
open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 934
opendir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 937
ord . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 937
our . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 937
pack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 938
package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 940
pipe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 940
pop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 941
pos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 941
print . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 942
printf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 942
prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 945
push . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 945
 Contents xxv

quotemeta . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 946
rand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 946
read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 946
readdir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 947
readline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 947
readlink . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 948
readpipe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 948
recv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 949
redo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 949
ref . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 950
rename . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 951
require . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 951
reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 952
return . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 952
reverse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 953
rewinddir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 953
rindex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 953
rmdir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 954
s/// . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 954
scalar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 955
seek . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 955
seekdir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 956
select (filehandle) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 957
select (files) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 957
semctl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 958
semget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 958
semop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 958
send . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 959
setgrent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 960
sethostent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 960
setnetent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 960
setpgrp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 961
setpriority . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 961
setprotoent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 962
setpwent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 962
setservent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 962
setsockopt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 963
shift . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 964
shmctl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 964
shmget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 965
shmread . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 966
shmwrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 966
shutdown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 967
xxvi Perl: The Complete Reference

sin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 967
sleep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 968
socket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 968
socketpair . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 969
sort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 969
splice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 970
split . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 970
sprintf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 971
sqrt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 972
srand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 972
stat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 972
study . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 974
sub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 974
substr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 975
symlink . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 975
syscall . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 976
sysopen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 976
sysread . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 978
sysseek . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 978
system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 979
syswrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 980
tell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 980
telldir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 981
tie . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 981
tied . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 982
time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 982
times . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 982
tr/// . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 983
truncate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 983
uc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 984
ucfirst . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 984
umask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 984
undef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 985
unlink . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 985
unpack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 986
unshift . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 986
untie . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 986
use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 987
utime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 988
values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 988
vec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 988
wait . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 989
waitpid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 989
 Contents xxvii

wantarray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 990
warn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 991
write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 991
y/// . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 992

B Standard Perl Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . 993

AnyDBM_File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 994
AutoLoader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 995
AutoSplit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 996
B ........................................................ 996
B::Asmdata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 998
B::Assembler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 999
B::Bblock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 999
B::Bytecode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 999
B::C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 999
B::CC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1000
B::Debug . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1000
B::Deparse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1000
B::Disassembler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1000
B::Lint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1001
B::Showlex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1001
B::Stackobj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1001
B::Terse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1001
B::Xref . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1001
Benchmark . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1002
Carp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1003
CGI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1004
Import Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1005
CGI::Apache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1006
CGI::Switch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1006
Class::Struct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1007
Using Scalar Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1008
Using Array Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1008
Using Hash Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1009
Using Class Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1010
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1010
Config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1011
CPAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1012
Interactive Shell Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1012
Programmable Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1015
CPAN::FirstTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1016
CPAN::Nox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1016
Cwd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1016
xxviii Perl: The Complete Reference

Data::Dumper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1017
DB_File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1018
Devel::SelfStubber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1020
DirHandle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1020
DynaLoader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1021
English . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1021
Env . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1024
Errno . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1025
Exporter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1025
Unknown Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1026
Tag-Handling Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1026
Version Checking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1027
ExtUtils::Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1027
ExtUtils::Embed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1028
ExtUtils::Install . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1029
ExtUtils::Installed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1029
ExtUtils::Liblist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1029
ExtUtils::MakeMaker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1030
ExtUtils::Manifest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1030
ExtUtils::Miniperl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1030
ExtUtils::Mkbootstrap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1030
ExtUtils::Mksymlists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1030
ExtUtils::MM_OS2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1030
ExtUtils::MM_Unix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1030
ExtUtils::MM_VMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1031
ExtUtils::MM_Win32 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1031
ExtUtils::Packlist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1031
Fatal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1031
Fcntl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1031
FileCache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1032
FileHandle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1033
File::Basename . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1035
File::CheckTree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1036
File::Compare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1037
File::Copy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1037
File::DosGlob . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1038
File::Find . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1039
File::Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1040
File::Spec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1041
File::Spec::Mac . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1042
File::Spec::OS2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1043
File::Spec::Unix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1043
File::Spec::VMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1045
 Contents xxix

File::Spec::Win32 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1046
FindBin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1046
GDBM_File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1047
Getopt::Long . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1048
Linkage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1049
Aliases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1050
Callback Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1050
Return Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1051
Customizing GetOptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1051
Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1053
Getopt::Std . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1053
I18N::Collate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1054
IO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1054
IO::File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1055
IO::Handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1055
IO::Pipe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1058
IO::Seekable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1059
IO::Select . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1059
IO::Socket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1061
IO::Socket::INET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1063
IO::Socket::UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1065
IPC::Msg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1066
IPC::Open2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1067
IPC::Open3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1068
IPC::Semaphore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1068
IPC::SysV . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1070
Math::BigFloat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1072
Math::BigInt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1073
Math::Complex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1075
Math::Trig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1076
Net::Ping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1077
NDBM_File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1078
O ........................................................ 1079
ODBM_File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1079
Opcode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1079
Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1080
Opcode Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1082
Pod::Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1087
Pod::Html . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1087
Pod::Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1087
POSIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1089
Supported Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1089
Symbol Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1102
xxx Perl: The Complete Reference

Safe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1111
SDBM_File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1114
Search::Dict . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1114
SelectSaver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1114
SelfLoader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1115
Shell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1116
Socket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1116
Symbol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1118
Sys::Hostname . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1119
Sys::Syslog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1119
Term::Cap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1121
Term::Complete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1122
Term::ReadLine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1123
Test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1124
Test::Harness . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1127
Text::Abbrev . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1127
Text::ParseWords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1128
Text::Soundex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1129
Y
Text::Tabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1130
FL
Text::Wrap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1131
Tie::Array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1131
Tie::Handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1132
AM

Tie::Hash . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1132
Tie::RefHash . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1133
Tie::Scalar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1133
TE

Tie::SubstrHash . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1134
Time::Local . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1134
Time::gmtime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1135
Time::localtime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1136
Time::tm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1137
UNIVERSAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1137
User::grent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1138
User::pwent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1139
utf8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1139

C Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1141
Supplied Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1142
Unix Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1142
Windows Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . 1143
Mac OS Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1143
Other Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1144
Books . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1144

Team-Fly®
 Contents xxxi

Journals/Websites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1146
The Perl Journal (www.tpj.com) . . . . . . . . . . . . . . . . . . . . . . 1146
Internet.com (www.internet.com) . . . . . . . . . . . . . . . . . . . . . 1146
Server/Workstation Expert Magazine
(sun.expert.com) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1146
TechWeb (www.techweb.com) . . . . . . . . . . . . . . . . . . . . . . . 1146
Web Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1147
Mailing Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1148
General Mailing Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1149
Windows-Specific Mailing Lists . . . . . . . . . . . . . . . . . . . . . . 1149
Newsgroups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1150

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1153
This page intentionally left blank.
 Acknowledgments
irst of all, I’d like to thank my wife. Two years ago, based on the offer for the first

F edition of Perl: The Complete Reference, she stood by me when I wanted to start
writing full time. Without her continued support, I wouldn’t have written the first
edition or the various other books that I’ve written since then, or been able to do this
second edition. Meanwhile, she still gives advice, listens to my rants when things aren’t
going well, and continues to be impressed when each book arrives.
Next, I’d like to thank all the people at Osborne who made this book possible. That
includes Wendy Rinaldi for offering me the opportunity, Rebekah Young for keeping
me in check, LeeAnn Pickrell and Betsy Manini for getting it through production, the
desktop compositors for laying out each chapter, and Andy Carroll and Bob Campbell
for doing the copy editing.
For technical input, thanks again to Mark Strivens, Ann-Marie Mallon, Huga van
der Sanden, Jon Nangle, and a myriad of others, including those people on Cix who
gave me ideas and input about topics and tricks that should be included in the book.
It’s not possible to write a Perl book without thanking Perl’s original author and the
current maintainers—that includes Larry Wall, Tom Christiansen, Randal L. Schwartz,
Sriram Srinivasan, Gurusamy Sarathay, and many many others. It continues to amaze
me how much you can cram into one language, and these people are the ones who do it.
If there’s anybody I’ve forgotten to acknowledge, I apologize unreservedly in
advance. I have done my best to check and verify all sources and contact all parties
involved, but it’s perfectly possible I made a mistake.

xxxiii
Copyright 2001 The McGraw-Hill Companies, Inc. Click Here for Terms of Use.
This page intentionally left blank.
 Introduction

he idea of this book is to provide a reference guide to everything you could

T possibly want to know about Perl. I’ve done my best to try and cover all the
different aspects, from the core of the language to the different functions, and
on into the different tasks and areas of the Perl language. I even cover how to debug
your software, write documentation, and then build and distribute your applications
or modules to the world at large. Along the way, we also look at some nonstandard
features and extensions, including better ways of networking, web programming, and
designing interfaces.
Throughout the entire book, you’ll find real-world examples and guides on how to
approach real problems using Perl—not just how to use the features of Perl. If all you
want is a quick reference guide to the different areas of Perl, then use the appendixes
at the end of the book and on the Web at www.osborne.com, which cover basic
components, functions, the Perl standard library, CPAN (Comprehensive Perl Archive
Network) extension library, a complete guide to errors and warnings, and a list of
resources for more information.

xxxv
Copyright 2001 The McGraw-Hill Companies, Inc. Click Here for Terms of Use.
xxxvi Perl: The Complete Reference

What’s Changed Since the First Edition?

Beyond the obvious updates and fixes for the newer versions of Perl, we’ve also
changed the overall layout of this edition. We got a lot of feedback on the first edition
and its pitfalls and problems. The most requested feature was a better introductory
guide to the language. As such, we’ve completely restructured the first section
of the book to provide a well-rounded introduction to the language, for people new
to programming and for those migrating from another language.
The second and third sections have been updated, with many of the chapters
modified to provide a more solution-oriented approach, and that means the order and
content of many of the chapters has been changed. We’ve expanded on the content in
many areas, including more information on networking, database access (which now
covers the DBI extension and Win32::ODBC module) and web programming.
The last section has also been modified into a guide for the final processes behind
turning your Perl program into a distributable application. This includes debugging
and retuning your script and using the Perl compiler to improve performance and
find coding errors. The chapter on Perl documentation has also been updated to
provide information on using the supplied documentation and information on how
to write your own. Finally, we cover the topics of cross-platform development and
the packaging and distribution of your application or module.
Overall, I’ve tried to make the book less Unix-centric and cover more of the issues
surrounding cross-platform development throughout the book, instead of concentrating
the information into a few chapters at the end.

Who Is the Book For?

I haven’t targeted the book at any specific group of Perl users. To put it simply, if you
program in Perl, you will find this book useful. As a reference, most people should find
it useful to keep on the desk or the shelf just as a quick means of looking up a particular
function or feature. For learners and expert users alike, the information in this book
will be invaluable.
You should also find the book useful if you want to know how to do a particular
task in Perl, since you’ll also find working real-world examples of the different features
of Perl within the book. If you are looking for more examples, you might want to look
at Perl Annotated Archives, which contains over 100 scripts to solve a myriad of different
problems. For more information on migrating Unix scripts to the Windows platform,
especially when using the ActivePerl distribution, try ActivePerl Developer’s Guide.
If debugging and tuning are more your thing, then look at Debugging Perl. You can
get more information on all of these titles and many others, in Appendix C.
 Introduction xxxvii

How to Use This Book

Pick it up, look up the feature you want to get more information on from the contents
or the index, and read! The scripts and script fragments included in the book should all
work without modification on your machine. Be aware though that not all platforms
support all Perl features—Chapter 24 provides a guide to most of the issues
surrounding cross-platform development.
If you want purely reference information—that is, you want to look up the
arguments and return values to a function—then use the appendixes at the back of the
book and on the Web at www.osborne.com. For discussion, examples, and detailed
information on a particular feature, use one of the earlier chapters. You should find
references between the chapters and appendixes in both directions to help you get
more information.

Chapter Breakdown
Each chapter in the book attempts to cover a different aspect of the solutions that Perl
is able to provide.
Chapter 1 looks at the background of Perl and the fundamental abilities that you
will need to use and understand in order to make the best use of Perl.
Chapter 2 examines the basic processes behind programming in Perl, from
installing Perl onto your machine (Unix, Windows, and Mac OS are covered), to
writing and executing your first script. We also look at some of the key terms that
you come across while reading the book and using Perl.
Chapter 3 covers all of the basic semantics and parsing rules behind the Perl
language, including an outline of how the execution process works, and all of the
different components that make up a Perl script.
Chapter 4 looks at the Perl variable types; Perl supports three basic types, the
scalar, the array and the hash (or associative array).
Chapter 5 details the statement and control structures that will control the flow
and execution of your program.
Chapter 6 starts off by covering the theories behind dissecting a program into
different components, from simple subroutines, right up to the more complex issues
of creating your own modules.
Chapter 7 covers the use of files, from the basics of printing information to the
screen to reading information from multiple files.
Chapter 8 details the processing behind data processing—by far the most useful
and popular use of Perl. We start by looking at basic ways of manipulating strings and
arrays before covering the Perl regular expression mechanism.
Chapter 9 looks at the basic mechanisms available for identifying and trapping errors
and bugs, and how to go about handling the situation without upsetting the user.
xxxviii Perl: The Complete Reference

Chapter 10 looks at the more complex data structures available in Perl—arrays and
hashes. We go beyond the normal uses of these structures and look at other ways they
can be employed to aid in the programming process. We also take the opportunity to
examine references, which provide a different way of accessing and using information
stored in variables, and this leads us on to nested data structures and object-oriented
programming. This final section also leads to tied data structures—a system whereby
information from an external source can be attached to an internal data structure.
Chapter 11 covers the different ways of finding out system information, such as
information about users and groups, time and how to manipulate time values, and
finally the environment and how it can affect the execution of your script.
Chapter 12 describes the processing required within Perl to support communication
over standard network sockets, such as those used for communication over the Internet.
Chapter 13 looks at the storage of information in external databases, both
homegrown and using systems such as DBM, Oracle, and ODBC sources.
Chapter 14 discusses the processes involved in interprocess communication, using
both standard filehandles and System V IPC functions. The chapter also describes the
methods available for creating, controlling, and communicating with external processes.
Chapter 15 details the more advanced methods of executing Perl scripts, from
supplying arguments to the command line, to executing scripts within scripts (using
eval), to multi-threaded execution.
Chapter 16 covers the basic processes behind getting and communicating
information back to your users through a structured interface on the command line
and back through the Perl reporting mechanism.
Chapter 17 takes a detailed look at user interfaces, especially at Perl/Tk—the Perl
interface to the Tk user interface development system.
Chapter 18 describes the environment available to you when you are writing
web scripts. This covers the physical environment of a script and also the ways of
communicating between the web server, the user’s browser, and a Perl script, otherwise
known as CGI. We then go on to look at smarter ways of handling the web-development
process and the specifics of web programming with Perl, including a useful checklist of
the security issues surrounding the web-programming process.
Chapter 19 looks at ways in which you can control the execution of your Perl script.
Perl uses a series of pragmas to improve the monitoring of potential problems in your
script, provide additional warnings and error messages, and change the way in which
different aspects of your scrip are interpreted.
Chapter 20 details the methods behind extending Perl through external C functions
and libraries or through embedding Perl into your existing applications.
Chapter 21 covers the essential process of debugging Perl scripts, both at a simple
level and at deeper levels within the Perl interpreter. We also look at how to debug
regular expressions and how to use the Perl profiler to determine which parts of your
Perl script need optimization.
Chapter 22 looks in detail at the Perl compiler. This supports several different
systems that take a Perl script and produce a number of different reports and output
formats. At a simple level, this includes a parsing tree that describes the real execution
 Introduction xxxix

profile of your script, and at the other end of the scale, the compiler that supports the
creation of stand-alone Perl binaries.
Chapter 23 details the use and development of Perl documentation, both when
reading supplied documentation and writing your own.
Chapter 24 concentrates on ways in which you can write Perl programs that are
cross-platform compatible, even if you don’t know what the destination platform is.
We look at the basics of using Perl in different environments, the major differences and
things to watch out for, and also ways in which you can make a script more aware of
its surroundings.
Chapter 25 discusses the processes involved in releasing a Perl module to the Perl
community. In particular, it describes the MakeMaker utility for creating Perl Makefiles
that can compile and automatically install Perl extensions.
The appendixes at the back of the book provide a quick reference resource for Perl
functions (Appendix A) and the standard Perl library (Appendix B). Appendix C gives
a list of all of the different areas—books, websites, mailing lists, and newsgroups—that
can provide more information on how to use and program with Perl.
The appendixes on the Web (www.osborne.com) provide a reference to the core
Perl constructs (Web Appendix A), the extensions for Perl available from CPAN
(Web Appendix B), and a complete list and description of all the warnings and error
messages generated by the Perl interpreter (Web Appendix C).

Conventions Used in This Book

All Perl keywords are highlighted in bold, but functions are listed without parentheses.
This is because the C functions on which the Perl versions may be based are shown
like this( ).

Examples and code are displayed using a fixed-width font.

Function descriptions are formatted using the same fixed-width font.

Notes are formatted like this and include additional information about a particular
topic. You’ll also find similarly formatted “Cautions” and “Warnings,” which highlight
possible dangerous tools or tricks to watch out for when programming.

Contacting the Author

I always welcome comments and suggestions on my work. I particularly appreciate
guides and recommendations on better ways of achieving different goals, especially
with a language as varied and capable as Perl. The best way to contact me is via
email. You can use either [email protected]. Alternatively, visit my website,
http://www.mcwords.com, which contains resources and updated information about
the scripts and contents of this book. You can find the homepage for this book at
http://www.mcwords.com/projects/books/pcr2e/.
This page intentionally left blank.

Y
FL
AM
TE

Team-Fly®
Part I
Fundamentals

Copyright 2001 The McGraw-Hill Companies, Inc. Click Here for Terms of Use.
This page intentionally left blank.
Chapter 1
Perl Backgrounder

Copyright 2001 The McGraw-Hill Companies, Inc. Click Here for Terms of Use.
4 Perl: The Complete Reference

erl is many different things to many different people. The most fundamental

P aspect of Perl is that it’s a high-level programming language written originally

by Larry Wall and now supported and developed by a cast of thousands. The
Perl language semantics are largely based on the C programming language, while also
inheriting many of the best features of sed, awk, the Unix shell, and at least a dozen
other tools and languages.
Although it is a bad idea to pigeonhole any language and assign it to a specific list
of tasks, Perl is particularly strong at process, file, and text manipulation. This makes
it especially useful for system utilities, software tools, systems management tasks,
database access, graphical programming, networking, and web programming. These
strengths make it particularly attractive to CGI script authors, systems administrators,
mathematicians, journalists, and just about anybody who needs to write applications
and utilities very quickly.
Perl has its roots firmly planted in the Unix environment, but it has since become
a cross-platform development tool. Perl runs on IBM mainframes; AS/400s; Windows
NT, 95, and 98; OS/2; Novell Netware; Cray supercomputers; Digital’s VMS; Tandem
Guardian; HP MPE/ix; Mac OS; and all flavors of Unix, including Linux. In addition,
Perl has been ported to dozens of smaller operating systems, including BeOS, Acorn’s
RISCOS, and even machines such as the Amiga.
Larry Wall is a strong proponent of free software, and Perl is no exception. Perl,
including the source code, the standard Perl library, the optional modules, and all of
the documentation, is provided free and is supported entirely by its user community.
Before we get into the details of how to program in Perl, it’s worth taking the
time to familiarize yourself with where Perl has come from, what it can be used
for, and how it stacks up against other languages. We’ll also look at some popular
“mythconceptions” about what Perl is and at some success stories of how Perl has
helped a variety of organizations solve an equally varied range of problems.

What Does PERL Stand For?

There is a lot of controversy and rumor about exactly what PERL stands for and if,
in fact, it stands for anything. According to Larry Wall, the original acronym stood
for Practical Extraction and Reporting Language, and this relates to the original
development purpose, which was to process a large amount of textual report
information.
Over the years, other solutions have been proposed for the PERL acronym. The
most popular recent version is Pathologically Eclectic Rubbish Lister. Luckily, a
rough translation of that expansion equates to the original version!
Random documents with unrelated
content Scribd suggests to you:
 The five years Mr. Laborde was to pass in the queen’s service extended
to ten. His patroness gave him house and home, lands and slaves; and as he
is married to a native woman, and has a son by this marriage, he will
probably remain here to the end of his life, though he has long been free
and independent, and may leave the island whenever he chooses to do so.
Besides his manufactories for arms and powder, this industrious man has
also established works for glass-blowing, indigo-dyeing, soap and tallow
boiling, and a distillery for rum. He wished also to stock the island with
European fruits and vegetables, and most of those he planted flourished
wonderfully, but his example remained unfollowed. The natives preferred to
live on in their pristine indolence, and to continue eating nothing but rice,
with the addition of a piece of beef now and then.
If Mr. Laborde, however, did not succeed in producing all the results he
expected from his undertakings, they have at least done good service in
showing the capability of this beautiful land for cultivation.
It was toward four o’clock in the afternoon when we arrived in Mr.
Laborde’s house.
Our friendly host immediately introduced two Europeans to us, the only
ones then staying at Tananariva. The two gentlemen were clergymen; one of
them had been living for two years, the other for seven months, in Mr.
Laborde’s house. It was not the time to appear as missionaries, and they
concealed the fact of their belonging to a mission very carefully, the prince
and the Europeans being the only persons admitted into the secret. One
passes as a physician, the other as tutor to Mr. Laborde’s son, who had
come back two years since from Paris, where he had been sent by his father
to be educated.
We were soon assembled at a good dinner round our host’s table. Every
thing was arranged in European style, with the exception that the dishes and
plates were all of massive silver, and silver goblets supplied the place of
drinking-glasses. I observed jokingly to Mr. Laborde that I had never met
with such luxury at any table, and that Tananariva was the last place in the
world where I should have expected to find it. He replied that similar luxury
prevailed in all the houses of the rich, but that there were certainly not many
houses of this description. He said he had himself introduced the fashion,
but not from ostentation, but, on the contrary, on economical grounds. He
found that china-ware had continually to be replaced, as the slaves were
perfect adepts in the art of breaking any given number of articles in the
shortest possible time, so that the use of china became very expensive.
Before we had nearly concluded our pleasant meal, while Champagne
was being handed round, and the toasts were beginning, a slave came
running up in hot haste to announce the approach of Prince Rakoto. We rose
hastily from table, but had little time to go and meet the prince, for, in his
impatience to see Mr. Lambert, he had followed close at the slave’s heels.
The two men held each other in a long embrace, but for some time neither
of them could find a word to express his joy. It was easy to see that a deep
and true friendship existed between them, and we who stood round could
not view the scene without feelings of pleasurable emotion.
Prince Rakoto, or, to call him by his full name, Rako-dond-Radama, is a
young man twenty-seven years of age. Contrary to my expectation, his
appearance was far from disagreeable. He is short and slim in stature, and
his face does not betray a likeness, in form or color, to any of the four races
who inhabit Madagascar. His features have quite the type of the Moldavian
Greeks. His black hair is curly, but not woolly; he has dark eyes, full of life
and fire; a well-shaped mouth, and handsome teeth. His features wear an
expression of such childlike goodness that one feels drawn toward him from
the first moment of seeing him. He often goes about in European costume.
The prince is honored and beloved alike by high and low; and I was
assured by Mr. Laborde that he fully deserved all this affection and honor.
The son is, in fact, as kind-hearted as the mother is cruel; he is just as
averse to the shedding of blood as his mother is addicted to it, and his chief
efforts are directed toward mitigating the severe punishments the queen is
continually inflicting, and obtaining a reversal of the sentences of death
which she is always too ready to pronounce upon her subjects.
He is always ready to listen to the unfortunate, and to help them; and has
strictly forbidden his slaves to turn any applicant away on the score that he
is sleeping or engaged at his meals. Well aware of this, people often come
in the middle of the night and wake the prince from his sleep, with petitions
for their relations who are to be executed early next morning. If he can not
obtain a pardon from his mother, he manages to pass as if by accident along
the road by which the poor culprits are led, bound with cords, to meet their
fate. Then he cuts their bonds asunder, and either tells them to flee, or to go
quietly home, according as their offenses have been grave or venial. When
the queen is informed of what her son has done, she never makes any
remark, but only tries to keep the next sentences she pronounces as secret as
possible, and to hasten their execution. Condemnation and punishment thus
often succeed each other so rapidly, that if the prince is absent from the
town when sentence is passed, the application to him for assistance is
almost sure to come too late.
It is strange, considering how radically different their dispositions are,
that mother and son should love each other so tenderly. The prince is
devoted to the queen with the utmost affection; he tries to excuse her deeds
of severity by every conceivable argument, and it is a bitter reflection to
him that she can be neither loved nor respected by the nation.
The prince’s character is the more remarkable, inasmuch as he has had
his mother’s bad example before his eyes from his earliest youth, and can
not escape from her influence; moreover, not the slightest care has been
taken of his education. In most similar cases, the son would certainly have
imbibed the prejudices and acquired the vices of the mother.
No one has attempted to teach him any thing, with the exception of a few
words of the English language; what he knows, and what he is, he owes
entirely to himself. What might this prince not have been had a judicious
education opened his mind and developed his talents? I had frequent
opportunities of seeing and observing him, for a day seldom passed without
his paying Mr. Lambert a visit. I found no fault in him except a certain want
of independence and a distrust of his own abilities; and the only thing I fear,
should the government one day fall into his hands, is, that he will not come
forward with sufficient energy, and may fail in thoroughly carrying out his
good intentions.
A few of the actions of this man will sufficiently prove the nobility of his
mind.
It frequently happens that the queen orders hundreds of her subjects to
perform the heaviest labor for months together for some favored personage
—such work, for instance, as hewing timber for building, and then dragging
it thirty miles along the road; hewing stone, and kindred occupations; for all
which the poor people get not the slightest reward of any kind. When the
prince hears of a case of this kind, he manages to pass by the neighborhood
where the people are at work, meets them as if by chance, and asks for
whom they are laboring thus. On receiving their reply, he farther inquires if
they are properly fed, for wages are of course out of the question. Then it
generally turns out that they not only have no food provided for them, but
frequently have consumed all the provisions they have brought with them,
and are trying to satisfy their hunger with herbs and roots. The prince then
has one or two oxen killed, according to the number of the laborers, and this
meat, with a good supply of rice, is by his command distributed among
them. If the owner should come forward in surprise at this order, and
attempt to remonstrate, the prince sends him away with this assurance:
“Whoever works for you has a just claim to be supported by you; and if you
will not make the arrangement yourself, your steward must.”
A few years ago, a ship was wrecked on the coast of Madagascar, and
the majority of the crew perished. Five sailors who had escaped from the
wreck were sent, according to the usual custom, to the capital, to be sold
there as slaves. The prince met them during an excursion he was making,
about a day’s journey from Tananariva, and noticing that one of the sailors
had no shoes, and was limping painfully after the rest, he drew off his own
and gave them to him. He also took care that the poor men were well fed.
Mr. Laborde bought these five sailors, clothed them, gave them money and
letters of recommendation, and helped them to get back to their own
country. The prince is seldom in a position to carry out his benevolent
designs, for he has no money, or, at any rate, very little; his whole wealth
consisting in slaves, rice-fields, and oxen given to him by his mother.
Another time the prince saw a European being led as a prisoner to the
capital by several natives. The poor wretch was being urged on like a brute
beast by his guards with blows and pushes; he was so exhausted and weak
from the long journey and the bad roads that he could drag himself no
farther. The prince reproved the guards for their cruelty, himself alighted
from his tacon, or sedan-chair, and told the captive to take his place.
The prince, moreover, found an opportunity of showing his generosity
toward one of our bearers. True to the habits of his country, this poor wretch
had stolen an ox in the vicinity of the capital, driven it to one of the
markets, and tried to dispose of it; but he was caught in the fact, and
brought to the capital. In cases of this kind, justice in Madagascar is very
quick in taking its course; on the same day sentence of death was passed
upon him, and toward evening he was to be executed in the manner of the
country, with the lance or gagaya. Mr. Laborde heard of this, and sent in all
directions in search of the prince to obtain his mediation. Luckily, the
prince was found in time, scarcely half an hour before the execution was to
have taken place. He proceeded at once to the prison, opened the door for
the captive, and recommended him to flee to his own home as fast as he
could.
Many similar traits were told me of the prince, and seldom, it is said, do
many days elapse without his saving lives or performing some generous
action. He often gives away his last dollar, distributes all his stores of rice
and other provisions, and is doubly glad when he can help some unfortunate
being without letting the recipient of his bounty know who is his benefactor.
The following words, which I heard from his own mouth, speak more
eloquently than my weak pen could do the praises of this really noble man.
He declared it to be a matter of indifference to him whether the French or
the English, or any other nation, took possession of the island, if only the
people were properly governed. For himself, he wished neither for the
throne nor for the regal title, and would at any time be ready to give a
written abdication of his claims, and retire and live as a private man, if he
could by such a course insure the prosperity of the people.
I must confess that this declaration moved me deeply, and inspired me
with a high respect for this prince—such respect as I feel for very few
human beings. To my mind, a man of such sentiments is greater than the
most prominent among the ambitious and egotistical monarchs of Europe.
May 31. This morning the queen sent one of the grandees of the empire
to inquire after our health, and to invite us to take the sambas-sambas next
day in the house of the Lady Rasoaray.
On this occasion she sent Mr. Lambert a present as a mark of her favor.
The gift consisted of a magnificent fatted ox, of proportions I had rarely
seen equaled even in Europe, besides some very fine poultry and a basket of
eggs. The presents of the queen never consist of any other articles, and are
generally confined to poultry and eggs; oxen are only added when she
wishes to confer on the recipient a mark of peculiar distinction.
The sambas-sambas is a dish made of fine strips of beef broiled in fat,
and of rice. It is customary, in the first month of the new year, to regale
friends and relations who come to visit you with this dish. Every one takes a
pinch of it, rises from his seat, turns to the right and to the left, and says,
“May the queen live a thousand years.” After this he may eat as much as he
likes of the preparation, or may leave it untouched, as he pleases. This
ceremony is somewhat equivalent to wishing a happy new-year among us.
As we happened to arrive in the first month of the new year, and the
queen wished to show Mr. Lambert all kinds of attention, she invited him to
this feast, and my humble self and the other Europeans were included in the
honor as friends of Mr. Lambert.
All the banquets to which friends are invited are not held in the royal
palace, but at the house of the Lady Rasoaray, who is of very high birth, and
whose spacious, richly-furnished dwelling is well adapted for such
purposes. To eat in the palace of the queen, or, still more, in her company,
would be considered too great an honor for a stranger; so far the
condescension of this haughty, self-opinioned potentate extendeth not.
I made use of this day to visit the town, of which, however, I can say
nothing more than that it is very bustling, and extends over a large space of
ground, especially if the suburbs be taken as part of it. It is said, with its
immediate environs, to contain 50,000 houses, or “roofs,” as they are called
here, and 100,000 inhabitants. This estimate is probably much exaggerated;
but certainly the proportion of dwellings is unusually great, from the simple
reason that the houses themselves are particularly small, consisting of no
more than one room, or at most but two. If the family is large, two or three
additional little houses are built up around the original dwelling; all who
have any pretensions to wealth have their kitchen under a separate roof;
and, of course, the slaves are also quartered in various small houses. Still, I
do not think Tananariva can contain many more than 15,000, or, at the most,
20,000 houses.
Mr. Laborde, for instance, is the owner of nine small dwellings, tenanted
by seven free men and thirty slaves; here, then, the proportion of inhabitants
to houses would be as four to one. But Mr. Laborde is a European, and does
not live with his people in such a crowded manner as the natives affect—
with them six, or certainly at least five, inhabitants may be reckoned to
every roof.
June 1. At two o’clock in the afternoon we betook ourselves to the house
of the Lady Rasoaray, and were conducted to a large hall, the walls papered
in European fashion, and the floor covered with handsome mats. In the
middle of the room stood a table, elegantly spread, in a style of which no
prince in Europe need have been ashamed. The other arrangements in the
room were simple, but tasteful. Many an English lady would have been
exceedingly scandalized by the fact that in the room in which we were to
dine stood two beds—two very handsome beds, with heavy curtains of rich
silk. As I am, however, not an Englishwoman, but only a simple German, I
took no notice of the circumstance, and the presence of the two beds did not
prevent me from eating my share of beef and rice in all peace and quietness
of spirit. These two dishes are the only ones admitted at the sambas-sambas,
and water is the only beverage allowed on these occasions.
I particularly admired two silver vases, with carving on them in relief,
which stood on the table; and my wonder rose considerably when I was
informed that they had been executed by native artificers. They would
certainly have met with high approval even in Europe. Like the Chinese, the
natives are gifted in a high degree with the faculty of imitation, but they
lack originality.
Among the high personages invited with ourselves to the feast were
many who spoke either French or English, English being the more common.
The knowledge of this language dates from the time of King Radama, in
whose reign English missionaries came to Madagascar, and a certain
number of young men were sent to the Mauritius or to England for their
education.
The ceremony of the sambas-sambas was very soon ended, and we
returned home early; in the evening we were surprised by a visit from
Prince Rakoto. He brought with him the mother of his little five-year-old
son, to introduce her to me. As I have already mentioned, the prince can
not, according to the laws that prevail here, marry this woman, because she
is a slave, and her son has, therefore, not the smallest claim to his father’s
rank; nevertheless, they are both honored with the princely title. It may
certainly be said that in this country the laws are of little importance in so
far as they affect the ruler; they depend solely and entirely upon the will of
the reigning sovereign; and as soon as Prince Rakoto comes to the throne,
he can alter them at his pleasure, and make his former slave his queen and
her son heir-apparent.
I have spoken of the character of this woman. As regards her beauty, if it
is to be discovered, it must certainly not be judged of by European eyes, or
the beholder should have lived long enough among the natives to have
become accustomed to their ugly features, and to consider the least hideous
among them as handsome.
June 2. To-day we were present at a great review on the Field of Mars, a
beautiful meadow spreading out at the foot of the hill in front of the town. It
is asserted that from ten to twelve thousand soldiers are always assembled
at Tananariva; but, like the estimate of the houses, this number must
probably be reduced about one half. The military who appeared on this
occasion did not certainly exceed 4500 or 5000 men. The soldiers formed a
great double square, with the officers and band in the centre.
A review of this kind is held every fortnight—namely, on the third day
of every second week; its object is to ascertain that the soldiers who should
be on duty are present; that they are in health, and their weapons and
clothes in proper condition. Their names are called over, and if in a
company only a few are missing, the captain merely receives a reprimand;
but if the list of absentees is a long one, the commanding officer is punished
on the spot with a dozen blows or more. The latter incident is reported to be
of frequent occurrence; for among such a large number of soldiers, there are
many whose homes are several days’ journey from the capital, so that they
can hardly find time, between one review and another, to go thither,
cultivate their fields, provide themselves with food, and return punctually.
No military manœuvres were undertaken, and I was told that war is
carried on entirely without system, as among the wildest tribes. Especially
when a company thinks itself lost, all subordination ceases, and the men
take to flight on every side.
Horrible is the fate of the sick and wounded soldiers, not only during a
flight, when, of course, no one cares about them, but even during ordinary
marches. Their comrades are bound to take care of them, and to carry and
feed them; but how can people be expected to do this who are themselves in
want of every thing, and often so much weakened by hunger and toil of
every kind that they can scarcely drag themselves along and carry their
weapons? It frequently happens that efforts are made by the soldiers to rid
themselves of these poor wretches. They are not killed outright, which
would be rather a benefit to them, under the circumstances; but their
comrades drag them along the ground, without giving them any food, or
even a refreshing draught from the nearest spring. When they have ceased
to give any sign of life, they are left by the wayside, no one caring to
ascertain whether they are dead or not.
On these marches a fearful number of lives are sacrificed. In the last war,
for instance, which the queen waged against the Seklaves two years ago, ten
thousand men were sent into the field. More than half died on the march for
want of food; many deserted; and when the army reached the scene of
action, its force is said to have scarcely exceeded three thousand men.
The prisoners are much better off, for care is taken of them, as a profit is
derived from their sale; and even as slaves they are not in nearly so
unhappy a condition as the soldiers and peasants. Their owners feed, clothe,
and lodge them; nor are they overworked; for, by transgressing in this
respect, the owner runs the risk of losing his bondman, for his slave runs
away; and fugitive slaves are seldom captured, there being no police or
similar institution in the country. The master certainly has the power of
beating his slave to death; the government will not interfere with him; but
his own interest will deter him from any extreme measures. Many slaves
pay their owners a small yearly tax in money, and live like free men; others
even keep slaves themselves, who work for their master-bondmen.
After the review, the officers and music marched past our house to
welcome Mr. Lambert.
The officers were mostly clothed, like their brethren at Tamatavé, in
European garb, and looked ridiculous and comical enough. One wore a
dress-coat, the tails of which reached almost to his heels; another had a coat
of flowered chintz; a third, a faded red jacket, which had once done duty as
part of a marine’s uniform. Their hats were just as diverse in character.
There were straw hats and felt hats, of all sizes and shapes, caps and head-
coverings of fearful and wonderful forms. The generals wore the regulation
cocked hat of Europe, and were mounted.
The military grades are modeled quite on the European plan; there are
thirteen gradations from the private soldier up to the field-marshal.
I succeeded also in finding European titles in Madagascar; there were
crowds of barons, counts, and princes, as at the most aristocratic European
courts.
The whole population of Madagascar is divided into eleven castes. The
eleventh caste consists of the regal personage; the tenth of the descendants
of the royal family. In this caste alone brothers and sisters may intermarry,
probably in order to prevent there being too many scions of the blood royal.
The six following castes, from the ninth to the fourth inclusive, comprise
the nobles of higher and lower rank; the people belong to the third caste, the
“white” slaves to the second—a class including all who were once free, and
have been sold as prisoners of war or as a punishment for crimes; and the
first, or lowest caste, consists of the “black” slaves, namely, those who have
been born in that condition of life.
A noble may take a wife not only out of his own caste, but out of the two
immediately below him, but never from a higher one. On no account may
he marry a slave-woman; and the law does not even allow any other kind of
connection between a noble and a slave. In this respect, by the way,
Madagascar might serve as a model to those countries governed by white
men where slavery exists; for the morality of the entire community would
be greatly benefited if this custom were observed. This law was in former
times very stringently enforced, and on the discovery of a connection of the
kind alluded to the noble was sold as a slave, and the slave-woman
beheaded. If the woman in the case was a noble and the man a slave, both
were beheaded. In these latter days, however, this strictness has been much
relaxed. Indeed, in the universally low state of morality prevailing here at
the present time, the greater number of the nobles and officials would have
to lose their heads or their freedom; and what would then become of the
court? Some amount of good is, however, still effected by the law; for when
such an affair between a nobleman and his slave is suspected, he is
compelled to set her free to escape punishment.
As polygamy has been introduced here, every man may have as many
wives as he pleases; but among the nobles only a certain number of these
women have a claim to the actual title of wife, and the first wife always
keeps precedence over those taken subsequently. She alone lives in her
husband’s house, and great respect is shown to her; her children, too, have
privileges beyond those of the other wives. The other children, like the
subsequent wives, live in little separate houses. The king may take twelve
lawful wives, but they must be all members of the highest families. The
ruling queen and her sisters and daughters have the right of sending away
their husbands and taking new ones as often as they choose so to do.
Our breakfast was just over, and I had retired to my room, when Mr.
Lambert came to announce that the queen had summoned us to an
introduction or audience. This honor is generally accorded to strangers eight
or ten days after their arrival; but her majesty seemed desirous of showing
distinction to Mr. Lambert above all Europeans who had ever visited her
court, and so, not later than the fourth day, we had the happiness of
appearing before that exalted personage.
All these tokens of honor and consideration astonished Mr. Lambert not
a little. He had already told me in the Mauritius that he had very many good
friends at the queen’s court, and dangerous enemies also, who might have
taken advantage of his absence to slander him in the vilest manner, not only
in her eyes, but in Prince Rakoto’s too. But a circumstance that Mr. Lambert
now confided to me for the first time was, that attempts had been made in
another quarter to prejudice the queen against him, and that he expected not
exactly to be coldly received, but to be looked upon with some degree of
suspicion.
And now, for the first time, I got an insight into Mr. Lambert’s real plans
and intentions, which were certainly not calculated to prepossess the queen
in his favor.
When Mr. Lambert came to Tananariva for the first time in the year
1855, and saw with what cruelty the queen ruled, a wish arose in his mind
to free the unhappy people from this tyrant. He succeeded in gaining the
friendship of Prince Rakoto, who was also deeply moved by the people’s
misery, and who at that period told Mr. Lambert that he cared not who ruled
over the nation so long as the government was good and just. They soon
came to an understanding, and Mr. Lambert made a treaty with Prince
Rakoto, and conceived the design of seeking help from either the French or
English government.
In the year 1856 he went to Paris, and in a private interview with the
emperor he made him acquainted with the boundless misery of the people
of Madagascar, and tried to induce the French autocrat to come to the
assistance of that unhappy country. But it is difficult to enlist the sympathy
of a European government where philanthropy and not state interest is in
question. This audience had no result, and an interview of Mr. Lambert with
the English minister, Lord Clarendon, also led to nothing; nay, instead of
any advantage accruing from this step, it was productive of difficulty and
discomfiture, for every thing Mr. Lambert had done in reference to
Madagascar came to the ears of a great missionary society in England. The
society feared that, in the event of the French occupation of the island, the
Roman Catholic religion might be the only form of worship introduced and
licensed, which, in their opinion, would be, of course, a much greater
misfortune for the inhabitants than the mere fact of their being ruled by an
utterly cruel woman, like Queen Ranavola, who plays with human lives and
sacrifices them at her pleasure! The society accordingly formed the notable
resolution of opposing Mr. Lambert in every possible way, and immediately
dispatched a chosen member, a missionary, to Tananariva to acquaint the
queen with Mr. Lambert’s design against her.
To judge from what occurred, as it was reported to me, it would appear
that even an English missionary is capable of abandoning truth and sincerity
in order to effect a purpose, and, upon occasion, to employ arts of a
Jesuitical kind.
In the Mauritius, where the missionary made some stay before
proceeding to Madagascar, he ventured to assert that Queen Ranavola had
summoned him to Madagascar!
On his arrival at Tananariva he took care to impress upon the queen that
he had been dispatched to her by the English government for the purpose of
assuring her that England desired nothing more than to continue the same
friendly relations with her country which had existed in the time of George
the Fourth. He farther informed the queen of every thing that Mr. Lambert
had undertaken against her in France and England; represented that
gentleman as a very dangerous person, and a spy in the employ of the
French government; and predicted that Mr. Lambert would speedily make
his appearance, accompanied by a body of French troops, to depose her in
favor of her son.
If even these misrepresentations had been made to effect some noble
purpose, they could only have been justified by the very Jesuitical axiom
that “the end sanctifies the means.” But the object sought here was to
impede, or perhaps altogether to frustrate, a truly Christian and
philanthropic work, an undertaking calculated to promote the well-being of
the entire nation. A missionary society ought surely to understand the
principles of brotherly love better than this, and keep in view the maxims of
religion, and especially to remember that they are not to be made
subservient to political views.
The missionary’s calling is the most exalted of any, for to few men are
vouchsafed the opportunities of doing good that fall to his lot; but the
misfortune is, that the majority of missionaries busy themselves more in
worldly intrigues than in the amelioration of the human race, and that,
instead of inculcating charity, union, and toleration, they excite their
followers by their preachings to hate, contemn, and, if possible, to persecute
every sect but their own. I can only refer my readers to what I have written
on this subject in my former works, particularly concerning the English and
American missionaries.
So the missionary from England came to Tananariva bearing the sword
instead of the olive-branch. He not only unfolded Mr. Lambert’s alarming
schemes to the queen, but gave Prince Rakoto a long lecture on the
exceeding turpitude of his conduct toward his royal mother in meditating
revolt, declaring, moreover, that the English court had been so shocked by
the news as verily to have put on mourning!
The prince condescended to excuse himself by asserting, in reply, that,
had he meditated removing his mother from the throne to place himself
upon it, he should have merited the reproach; but that such was not the case,
as he merely wished to deprive the queen of the power of perpetrating
cruelties; every other privilege he wished her to retain, and for himself he
had asked nothing at all.
At Tananariva, and also in the Mauritius, a report was circulated that Mr.
Lambert had obtained the prince’s signature to the contract by fraud; that
the prince had not been at all inclined to enter into a private treaty with Mr.
Lambert, but that the latter had invited him to a banquet, intoxicated him,
and prevailed on him to sign while in that condition. It was farther stated
that when, on the following day, Prince Rakoto heard what he had done, he
was so incensed against Mr. Lambert that he had banished him from his
presence forever. Mr. Lambert was therefore very considerately advised
never to return to Madagascar, as he might fear the worst from the hatred
and contempt alike of the queen and of Prince Rakoto.
At Tananariva the prince himself told me the story of the signing of the
treaty. He let me read the document, and assured me that the tale of the
intoxication was a fiction; that he had perfectly understood what he was
doing, and that he never repented this step at all. I much wish the author of
this scandalous report could have seen with what contemptuous anger he
was spoken of on this occasion.
 I must also contradict a statement that the English missionary spread
abroad in the Mauritius on his return from Madagascar. He boasted every
where of the favorable reception he had met with at Tananariva, and of the
great favor he enjoyed at the hands of the queen and of Prince Rakoto. This
favor was so great, in fact, that after a stay of scarcely four weeks at
Tananariva he received a peremptory order to depart. He applied for
permission to remain longer, alleging as a reason that the fever season was
not yet past, and disease was still rife in the lowlands. He begged the queen
to take this into consideration, and not to expose him to mortal danger. But
all was in vain; he was compelled to quit Tananariva. The queen was highly
exasperated against him because he had distributed some Bibles, while
Prince Rakoto resented his behavior toward Mr. Lambert.
 CHAPTER XIII.
Introduction at Court.—The Monosina.—The Royal Palace.—The Hovas.—Scenes of
Horror under the Queen’s Rule.—Executions.—The Tanguin.—Persecution of the
Christians.—One of the Queen’s Journeys.—Her Hatred of Europeans.—Bull-fights.—
Taurine Mausoleum.

Our introduction at court took place on the 2d of June.

Toward four o’clock in the afternoon our bearers carried us to the palace.
Over the door is fixed a great gilt eagle with extended wings. According to
the rule laid down here by etiquette, we stepped over the threshold first with
the right foot, and observed the same ceremony on coming to a second gate
leading to a great court-yard in front of the palace. Here we saw the queen
sitting on a balcony on the first story, and were directed to stand in a row in
the court-yard opposite to her. Under the balcony stood some soldiers, who
went through sundry evolutions, concluding with a very comic point of
drill, which consisted in suddenly poking up the right foot as if it had been
stung by a tarantula.
The queen was wrapped, according to the custom of the country, in a
wide silk simbu, and wore on her head a big golden crown. Though she sat
in the shade, a very large umbrella of crimson silk was held up over her
head; this being, it appears, a point of regal state.
The queen is of rather dark complexion, strong and sturdily built, and,
though already seventy-five years of age, she is, to the misfortune of her
poor country, still hale and of active mind. At one time she is said to have
been a great drunkard, but she has given up that fatal propensity some years
ago.
To the right of the queen stood her son, Prince Rakoto, and on the left
her adopted son, Prince Ramboasalama; behind her sat and stood sundry
nephews and nieces, and other relatives, male and female, and several
grandees of the empire.
The minister who had conducted us to the palace made a short speech to
the queen, after which we had to bow three times, and to repeat the words
“Esaratsara tombokoe,” equivalent to “We salute you cordially;” to which
she replied, “Esaratsara,” which means “Well—good!” Then we turned to
the left to salute the tomb of King Radama, lying a few paces on one side,
with three similar bows, whereupon we returned to our former place in front
of the balcony and made three more. Mr. Lambert, on this occasion, held up
a gold piece of fifty francs’ value, and put it in the hands of the minister
who accompanied us. This gift, which every stranger has to offer when he is
presented for the first time at court, is called “Monosina.” It is not necessary
that it should consist of a fifty-franc piece; the queen contents herself with a
Spanish dollar or a five-franc piece. Mr. Lambert had, however, already
given fifty francs on the occasion of the “sambas-sambas.”
After the delivery of the gold piece, the queen asked Mr. Lambert if he
wished to put any question to her, or if he stood in need of any thing; to
which he answered “No.” She was also condescending enough to turn to
me, and ask if I was well, and if I had escaped the fever.[B] After I had
answered this question, we staid a few minutes longer looking at each other,
when the bowings and greetings began anew. We had to take leave of
Radama’s monument, and on retiring were again reminded not on any
account to put the left foot first over the threshold.
Such is the way in which the proud Queen of Madagascar grants
audiences to strangers. She considers herself far too high and exalted to let
them come near her at the first interview. Those who have the great good
fortune to win her especial favor may afterward be introduced into the
palace itself; but this is never achieved at a first audience.
The royal palace is a very large wooden building, consisting of a ground
floor and two stories, surmounted by a peculiarly high roof. The stories are
surrounded by broad galleries. Around the building are pillars also of wood,
eighty feet high, supporting the roof, which rises to a height of forty feet
above them, resting in the centre on a pillar no less than a hundred and
twenty feet high. All these columns, the one in the centre not excepted,
consist of a single trunk; and when it is considered that the woods which
contain trees of a sufficient size to furnish these columns are fifty or sixty
English miles from the capital, that the roads are nowhere paved, and in
some places quite impassable, and that all the pillars are dragged hither
without the help of a single beast of burden, or any kind of machine, and are
afterward prepared and set up by means of the simplest tools, the building
of this palace may with truth be called a gigantic undertaking, and the place
itself be ranked among the wonders of the world. In bringing home the
chief pillar alone, five thousand persons were employed, and twelve days
were occupied in its erection.
All these labors were performed by the people as compulsory service,
for which they received neither wages nor food. I was told that during the
progress of the work fifteen thousand people fell victims to the hard toil and
the want of proper nourishment. But the queen is very little disturbed by
such a circumstance; half the population might perish, if only her high
behests are fulfilled.
In front of the principal building a handsome spacious court-yard has
been left; around this space stand several pretty houses, all of wood. The
chief building is, in fact, uninhabited, and contains only great halls of state
and banqueting-rooms; the dwelling-rooms and sleeping-rooms of the
queen are in one of the side buildings, communicating by a gallery with the
palace.
On the left, the “silver palace” adjoins the larger one. It takes its name
from the fact that all the Vandyked ends with which the roof is decorated,
and the window and door frames, are hung with innumerable little silver
bells. This palace is the residence of Prince Rakoto, who, however, makes
very little use of it, generally living at his house in the city.
Beside the silver palace stands the monument of King Radama, a tiny
wooden house without windows; to this fact, however, and to the farther
circumstance of its being built upon a pedestal, it owes its sole resemblance
to a monument.
The singular custom prevails in Madagascar, that when a king dies, all
his treasures in gold and silver ware and other valuables are laid with him in
the grave. In case of need, the heir can dig up the treasure, and, so far as I
could ascertain, this had been done in every instance.
Radama’s treasure is only estimated at 50,000 piastres, but his father’s
was valued at a million. The treasure or property of the present reigning
queen is computed, according to the account I received, at between 500,000
and 600,000 dollars, and her yearly income at 30,000 to 40,000 dollars. The
latter sum she is able to add annually, almost without deduction, to her
fund, for she incurs no expense in her government or for her personal
wants. As to the first, the whole burden falls upon the people, who have to
work without pay; and with respect to the latter, the queen is the owner of
the land, and possesses a great number of slaves, who have to provide every
necessary for her household. Even the very clothes she wears are mostly
made of materials produced in the country, and woven and prepared by
male and female slaves.
Among the natives at Tananariva there are said to be some who have
property to the amount of several hundred thousand dollars; but they make
a secret of their wealth, for if the queen should obtain intelligence of the
whereabouts of such a treasure, the wish to seize it and carry it off might
very probably enter her royal mind.
The whole wealth of the island in ready money is estimated at one
million dollars at most.
I do not grudge the queen the treasure she has accumulated; but it would
be a fortunate thing for the population of the island if it were to be buried
very soon, in company—of course—with its gracious possessor. She is
certainly one of the proudest and most cruel women on the face of the earth,
and her whole history is a record of bloodshed and deeds of horror. At a
moderate computation, it is reckoned that from twenty to thirty thousand
people perish annually in Madagascar, some through the continual
executions and poisonings, others through grievous labor purposely
inflicted, and from warfare. If this woman’s rule lasts much longer, the
beautiful island will be quite depopulated; the population is said to have
already shrunk to half the number that it comprised in King Radama’s time,
and a vast number of villages have disappeared from the face of the land.
Executions and massacres are often conducted in wholesale fashion, and
fall chiefly upon the Seklaves, whom the queen seems to look upon with
peculiar hatred; but the Malagaseys and the other nations are not much less
distasteful to her; and the only tribe that finds any favor at all in her eyes is,
as I have already said, the Hovas, from whom she herself is descended.
These Hovas were once the most scorned and hated of all the races in
Madagascar; they were regarded as the Pariahs are regarded in India. Under
King Radama, however, and especially under the present queen, this race
has distinguished itself, and attained the first place by dint of intelligence,
bravery, and ambition. But, unhappily, the race has not been improved by
prosperity, and the good qualities of the Hovas are more than overbalanced
by their evil propensities: Mr. Laborde even declares that the Hova
embodies in himself the vices of all the tribes in the island. Mendacity,
cunning, and hypocrisy are not only habitual, but cherished vices with him,
and he tries to initiate his offspring therein at the earliest possible age. The
Hovas dwell among themselves in a continual state of suspicion, and
friendship is with them an impossibility. Their cunning and slyness are said
to be incredible: the most practiced diplomatists of Europe would be no
match for them in these qualities.
Of Malay origin, the Hovas are undoubtedly less ugly than the other
races in Madagascar. Their features have less of the negro type, and are
even better shaped than those of the Malays in Java and the Indian
Archipelago, whose superiors they are also in stature and bodily strength.
Their complexion varies through every shade from olive-yellow to dark
reddish-brown. Some are very light; but, on the other hand, I noticed many,
especially among the soldiers, whose color approximated so much to the
red tint that I should have taken them for more genuine “red-skins” than
even the North American Indians, to whom that name is applied from the
ruddy tinge in their skin. Their eyes and hair are black; they wear the hair
long, and this is of a frizzly woolly texture.
Even the Hovas, the favorites of the queen, are ruled with a ruthless iron
hand; and though they may not be put to death by hundreds and thousands
like the other nations, they are still punished with death for very trifling
offenses.
Blood—and always blood—is the maxim of Queen Ranavola, and every
day seems lost to this wicked woman on which she can not sign at least half
a dozen death-warrants.
That my readers may become better acquainted with this queen, whose
cause the English missionary society, in its philanthropy, has so warmly
espoused, whose defense their agent has dared to undertake, and whom he
has sought to maintain on the throne, I will cite a few of the deeds of horror
which have been perpetrated on the unhappy land at her command, and of
which the first alone would be sufficient to brand with infamy the name of
Ranavola forever.
In the year 1831, when the army was still well trained, and the discipline
introduced by King Radama had not yet been quite forgotten, the queen
conquered a great portion of the eastern part of the coast, whose chief
population consisted of Seklaves. She ordered all the men of the conquered
country to come to an appointed place to do homage to her. When the men,
twenty-five thousand in number, were assembled, they were commanded to
lay down their arms, and they were then led out into a large open space
quite surrounded by soldiers. Here they were told to kneel down in token of
submission; but scarcely had they done this, when the soldiers fell upon the
unhappy wretches, and massacred them every one. Their wives and children
were afterward sold as slaves.
Such is the lot of the conquered nations; but the queen’s own subjects are
not much better off.
In the year 1837, for instance, the queen received a report from her
ministers to the effect that there were many magicians, thieves, violators of
graves, and other evil-doers among the people. The queen immediately
convened a kabar, or judicial meeting, for seven weeks, and at the same
time caused it to be proclaimed to the people that all evil-doers who
delivered themselves up should have their lives granted to them, but that
those who failed so to do should suffer the punishment of death. A body of
nearly sixteen hundred men gave themselves up accordingly. About fifteen
hundred had voluntarily surrendered themselves to justice, and ninety-six
had been denounced. Of these ninety-six, fourteen were burnt; and of the
remaining eighty-two, some were hurled over a high rock, in the district of
Tananariva, which has been the death-place of thousands; others were put
into pits, and scalded to death with boiling water; others, again, were
executed with the spear, or poisoned; a few were beheaded, and several had
their limbs separately hacked off. The most painful death of all, perhaps,
was inflicted on a portion of the victims, who were sewn up in mats in such
a way that the head only protruded, and who were then left alive to rot.
Those who had been their own accusers were spared from execution, in
accordance with the royal promise; but their fate was far worse than that of
the men condemned to death. The queen declared that it would be
dangerous to set such a number of criminals at liberty, and that they must, at
any rate, be made harmless. So she had heavy irons fastened round their
necks and wrists, and the unhappy victims were fastened together in gangs
of four and five by very thick iron bars, about eighteen inches long. After
this operation had been performed on them, they were set free—that is to
say, they were at liberty to go where they would, only that guards were
appointed in all directions, whose office it was to give strict heed that none
of the irons were filed off. If one of a group died, it was necessary to cut off
his head to extricate the corpse from the iron neck-ring, and the dead man’s
fetters were left to weigh upon the survivors, so that at last they could
hardly drag themselves from place to place, and perished miserably at last
under the heavy weight.
In the year 1855 certain people in the province of Vonizonga
unfortunately took it into their heads to assert that they had discovered a
means of catching a thief by invisible agency; that when he stretched out his
hand with felonious intent, they could charm his arm so as to prevent him
from drawing it back or moving from the spot. When the queen heard of
this, she commanded that the people in question should be severely
punished, for she fancied she herself might one day come into that district,
and be killed by similar witchcraft. Two hundred persons were taken
prisoners, and condemned to the tanguin, of whom a hundred and eighty
perished.
The tanguin, or poisoning test, is often applied to persons of all grades—
to the high nobles as well as the slaves; for the mere accusation of any
crime is sufficient to bring it upon the victim. Any man may start up as
accuser. He need not bring forward any proofs, for the only condition he has
to fulfill is to deposit a sum of twenty-eight and a half dollars. The accused
persons are not allowed to make any defense, for they must submit to the
poisoning ordeal under all circumstances. When any one gets through
without perishing, a third part of the deposited money is given to him, a
second third belongs to the queen, and the remainder is given back to the
accuser. If the accused dies, the accuser receives all his money back, for
then the accusation is looked upon as well founded.
The poisoning process in managed in the following manner: The poison
employed is taken from the kernel of a fruit as large as a peach, growing
upon trees called Tanguinea Veneniflora. The lampi-tanguini, or person who
administers the poison, announces to the accused the day on which he is to
take it. For forty-eight hours before the appointed time he is allowed to eat
very little, and for the last twenty-four hours before the trial nothing at all.
His friends accompany him to the poisoner’s house; here he has to undress
himself, and make oath that he has not had recourse to any kind of magic.
The lampi-tanguini then scrapes away as much powder from the kernel with
a knife as he judges necessary for the trial. Before administering the dose to
the accused, he asks him if he confesses his crime; but the culprit never
does this, as he would have to take the poison notwithstanding. The lampi-
tanguini spreads the poison on three little pieces of skin, about an inch in
size, cut from the back of a fat fowl; these he rolls together, and bids the
accused swallow them.
In former days, almost every one who was subjected to this ordeal died
in great agony; but for the last ten years every one who has not been
condemned by the queen herself to the tanguin is permitted to make use of
the following antidote. As soon as he has taken the poison, his friends make
him drink rice-water in such quantities that his whole body sometimes
swells visibly, and quick and violent vomiting is generally brought on. If
the poisoned man is fortunate enough to get rid not only of the poison, but
of the three little skins (which latter must be returned uninjured), he is
declared innocent, and his relations carry him home in triumph with songs
and rejoicings. But if one of the pieces of skin should fail to reappear, or if
it be at all injured, his life is forfeited, and he is executed with the spear or
by some other means.
One of the nobles who frequently visited our house had been condemned
several years ago to take the tanguin. Happily for him, he threw up the
poison and the three pieces of skin in perfect condition. His brother ran in
great haste to the wife of the accused to announce this joyful event to her,
and the poor woman was so moved by it that she sank fainting to the
ground. I was astonished at hearing of such a display of feeling from one of
the women of Madagascar, and could not at first believe the account true. I
heard, however, that if the husband had died, she would have been called a
witch, and probably condemned to the tanguin likewise, so that the violent
emotion was probably caused more by joy at her own deliverance than the
good fortune of her husband.
During my stay in Tananariva a woman suddenly lost several of her
children by death. The mother was accused of causing the fate of the poor
little ones by magic arts, and was condemned to the tanguin. The poor
creature threw up the poison and two of the skins, but as the third did not
make its appearance, she was killed without mercy.
As I have already said, the queen, immediately on her accession, had
strictly forbidden the profession of the Christian faith, which had been
introduced under King Radama. Notwithstanding this, there are said to be a
considerable number of Christians still in the island, who, of course, keep
their belief as secret as possible. In spite of all their caution, however, about
six years ago all the members of a little congregation were denounced and
captured. One of their number was burnt by the queen’s orders. This
punishment is generally inflicted only on nobles, officers, and soldiers;
fourteen were thrown over the rock, and many others beaten to death. Of
the remainder, the nobles were deprived of their titles and honors, and the
commoners sold as slaves. All the Bibles discovered were publicly burnt in
the great market-place.
The punishment of being sold as a slave is one of the lightest to which
the queen condemns her subjects. The following facts will show on what
slight grounds such sales are effected.
Once the queen had caused some Spanish dollars to be melted down for
silver dishes. When these dishes were brought to her, she found fault with
the workmanship, summoned the goldsmiths and silversmiths to the palace,
and exhorted them to furnish better work. The good people did their very
best, and, to their own misfortune, turned out better dishes than they had at
first produced. The queen was satisfied, praised the workmen, and, as a
reward for their exertions, had the whole guild sold as slaves, on the ground
that they had not at first delivered such good dishes as they had since
proved themselves able to make.
At another time many persons lost their freedom in consequence of a
death in the royal family. When a nobleman of any caste dies, the duty of
wrapping him in the dead-cloth and placing him in the grave devolves upon
the fourth caste. The deceased in this case had fallen into disgrace, and been
banished from the capital, and mourning was not put on for him at court;
under these circumstances, the nobles of the fourth class feared to offend
the queen by paying the last honors to the dead man, and left this duty to
men from among the people. As soon as this came to the queen’s ears, she
laid a fine of four hundred dollars upon the whole caste, and had one
hundred and twenty-six persons selected from it and sold as slaves; among
these were many women and children.
The entire population of a village sometimes fall into slavery merely for
eating the flesh of a stolen ox. Stealing an ox is a crime punished with
death; but if the stolen beast belonged to the queen, not only is the thief
executed, but all who have partaken of the ox’s flesh are sold into slavery;
and as no one takes the trouble to ascertain who has been implicated and
who not, the punishment falls upon the whole village in which the ox was
sold and slaughtered. None are spared but unweaned children, who are
graciously supposed not to have eaten any of the meat.
To have attained to wealth and independence is too great a crime in a
subject not to draw down all kinds of persecution on the luckless
delinquent. If the queen gets to know that any village is rich in cattle, rice,
and other produce—money, of course, is out of the question among the
villagers—she imposes a task upon the people which they can not execute;
for instance, she requires them to deposit a certain amount of wood, or a
certain number of stones, at a given place on an appointed day. The quantity
of materials to be delivered is made so large, and the time allowed for their
delivery so short, that, even with the greatest exertion, and every anxiety to
fulfill the conditions, the completion becomes impossible. The people are
then condemned to pay a fine of some hundreds of dollars; and as they have
no money, they are obliged to sell their cattle, their rice, their slaves, and
not unfrequently themselves.
Separate wealthy persons are plundered in the following way: An
Ysitralenga—that is to say, a man who does not tell lies—proceeds to the
house of the selected victim, accompanied by some soldiers; here, sticking a
lance in the ground, he accuses the head of the family of some offense
against the government—of having spoken disrespectfully of the queen, or
committed some other crime, and takes him prisoner, and leads him before
the judge. If the accused loses the suit, his whole property is confiscated; if
he wins it, half his wealth will have gone in bribes and other expenses; for,
although Madagascar is a half savage country, the judges understand their
business just as well as in the most civilized states in Europe.
But executions, poisonings, slavery, plunderings, and other punishments
do not exhaust the people’s catalogue of woes. In devising plans of
malignity and cruelty, Queen Ranavola’s penetration is wonderful; and she
has invented farther means for ruining the unhappy population, and
plunging it still deeper into misery. One device for carrying out this end,
often adopted by the queen, is a royal journey. Thus, in the year 1845,
Queen Ranavola made a progress to the province of Mancrinerina,
ostensibly to enjoy the sport of buffalo-hunting. On this journey she was
accompanied by more than 50,000 persons. She had invited all the officers,
all the nobles, far and near, around Tananariva; and that the procession
should appear as splendid as possible, every one had to bring with him all
his servants and slaves. Of soldiers alone, 10,000 marched with them, and
almost as many bearers, and 12,000 men always kept a day’s journey in
advance, to make the roads broader and repair them. Nor were the
inhabitants of the villages spared through which the queen passed. A certain
number, at least, had to follow the train with their wives and children. Many
of the people were sent forward, like the road-menders, to prepare the
night’s lodging for the queen; no trifling task, as the houses or tents
prepared for the royal family had to be surrounded by a high rampart of
earth, lest her gracious majesty should be attacked by enemies during the
night, and torn forcibly away from her beloved people.
Inasmuch as this philanthropic potentate is accustomed, on a journey of
this kind, only to make provision for her own support, and gives her
companions nothing but the permission to live on the stores they have
brought for themselves (provided, of course, they have been able to procure
any), famine very soon makes its appearance among the mass of soldiers,
people, and slaves. This was the case in the journey of which I speak; and in
the four months of its duration, nearly 10,000 people, and among them a
great proportion of women and children, are said to have perished. Even the
majority of the nobles had to suffer the greatest privations; for, wherever a
little rice was left, it was sold at such a high price that only the richest and
noblest were able to purchase it.
In the first years of Queen Ranavola’s rule, before she found herself
seated securely enough on the throne to gratify her bloodthirsty propensities
on her own subjects, her hatred was chiefly directed toward the descendants
of King Radama and toward the Europeans. Regarding the latter, she
frequently held councils with her ministers and other grandees concerning
the measures to be taken to keep the detested race away from her territories.
Mr. Laborde informed me that on these occasions the most absurd and
extravagant propositions were brought forward. Thus, for instance, one of
the wise councilors urged the expediency of building a very high, strong
wall in the sea round about Madagascar, so that no ship should be able to
approach any of the harbors. A second wiseacre proposed to the queen to
have four gigantic pairs of shears manufactured, and fixed on the roads
leading from the various harbors to the capital. Whenever a European came
along, the shears were to be clapped to the moment he stepped between
them, and thus the daring intruder would be cut in two. A third councilor, as
wise as his companions, advised the queen to have a machine prepared with
a great iron plate, against which the cannon balls fired from hostile ships
would rebound, and sink the aggressive vessels by being hurled back upon
them.
All these suggestions were received by her majesty with much
approbation, and formed matter for deliberation in the exalted council for
days and weeks; but, unfortunately, none of them were found practicable.
I must mention another touching trait, which the English missionary
society will not fail to interpret greatly to the advantage of Queen Ranavola,
should it not have done so already.
The queen is particularly fond of witnessing fights between bulls, and
this noble sport is frequently carried on in the fine large court-yard in front
of the palace. Among the horned combatants, some are her favorites: she
asks after their health every day, and is as anxious about them as a
European lady might be about her lapdogs; and, to carry out the simile, she
often takes more interest in their well-being than in the comforts of her
servants and friends.
In one of these contests, one of her favorite bulls—in fact, the chief of
them—was slain: the poor queen was inconsolable at her loss. Until now,
no one had ever seen her weep. But then, she had never before met with so
heavy a misfortune. She had certainly lost her parents, her husband, a few
children, and some brothers and sisters; but what were all these in
comparison to the favorite bull? She wept much and bitterly, and it was
long before she would take comfort. The animal was buried with all the
honors accorded to a grandee of the state. It was wrapped in a number of
simbus, and covered with a great white cloth, and the marshals had to lay it
in the grave. The marshals showed on this occasion that the race of courtiers
flourishes in Madagascar; they were so proud of the distinction that they
boast of it to the present day. Two great stones are placed upon the grave, in
memory of the dear departed; and the queen is said to think of him still with
gentle sorrow.
The bull’s monument is in the inner town. I saw it myself, and thought,
also with sorrow, not of the bull, but of the unhappy people languishing
under the cruel oppression of this barbarous queen; and with sorrow, too, I
thought of the equally unhappy sectarian spirit that can induce any section
of a Christian community to become the champions of such a woman!
 CHAPTER XIV.
Dinner at Mr. Laborde’s.—Foot-boxing.—Ladies of Madagascar and Parisian Fashions.—
The Conspiracy.—A Dream.—A Fancy-dress Ball.—An unquiet Night.—Concert at
Court.—The Silver Palace.—An Excursion of the Queen.

On the 3d, 4th, and 5th of June I was very unwell, with premonitory
symptoms announcing a coming attack of the malignant fever of
Madagascar. It luckily happened that, during these days, nothing of any
interest occurred.
On the 6th of June Mr. Laborde gave a grand dinner in honor of Prince
Rakoto, in his garden-house, situate at the foot of the hill.
Although the dinner was announced for six o’clock, we were carried to
the house as early as three o’clock. On the way we passed a place in the
upper town on which nineteen heavy guns (eighteen-pounders) were
planted, the muzzles pointing toward the lower town, the suburbs, and the
valley. They were placed there by King Radama, who had received them as
a present from the English. They were not landed at Tamatavé, but at
Bombetok, on the eastern coast. The distance from this place to the capital
is greater than from Tamatavé, but the roads are better, and river
conveyance can be made available for several days’ journey.
On our arrival at Mr. Laborde’s garden-house, all kinds of efforts were
made to shorten the interval before dinner: several native sports were
exhibited, the most popular of which was a kind of “foot-boxing.” The
combatants kicked each other all over, and with such hearty good-will that I
expected every moment broken legs or ribs would be the result. This
delicate sport is in particular favor among the people in winter, as it
effectually warms those engaged in it. The coldest season here is between
the month of May till the end of July, when the thermometer often falls to
four, three, or even to one degree (Réaumur). Nevertheless, every thing
remains green; the trees do not lose their leaves, and the landscape looks as
pretty and blooming as in Europe in the middle of spring. The inhabitants of
Tananariva are fond of the summer heat, and as they have no means of
procuring wood, and of thus artificially supplying the want of animal heat,
they resort to the aforesaid pastime of foot-boxing.
 The rich make their slaves bring wood from the distant forests to kindle
fires. In Mr. Laborde’s house, a coal fire was kept up in a great brazier from
early in the morning till late at night, but, of course, the door or the
windows remained always open. This piece of luxury costs a dollar per day
—a very high price compared with the cheapness of all other necessaries.
The foot-boxing was followed by dancing and gymnastic exercises; nor
was music wanting, for a band had been provided, which executed some
pieces skillfully enough. I was not so well pleased with the songs of a
number of native girls, who had been taught by a missionary residing with
Mr. Laborde. They knew a number of songs by heart, and did not scream in
such shrill fashion as those whom we had before heard; on the contrary,
their performance was tolerably correct; but it was a dreary entertainment,
and I was devoutly thankful when they came to the last bar.
A little before six o’clock came the prince, accompanied by his little son,
his beloved Mary, and a female friend of hers. Mary made even a less
favorable impression upon me than when I first saw her. The fault was in
her dress, for she was attired completely in the European style. Whatever
other people may say, the stiff, exaggerated fashions diffused by Paris over
the world do not charm me, even when worn by our own countrywomen,
and only look well on those whom nothing can disfigure; but where there is
a complete lack of natural beauty and grace, they become whimsical and
ridiculous, and particularly so in conjunction with clumsy figures and
monkey faces. Madame Mary may be a very good creature, and I should not
like to offend her in any way; but that did not prevent me from being
obliged to bite my lips till the blood almost came in the effort to avoid
laughing aloud at her appearance. Over half a dozen stiff-hooped petticoats
she wore a woolen dress with a number of great flounces, and great bows of
ribbon, the latter fastened, not in front, but at the back. She had thrown a
French shawl over her shoulders, and could never arrange it to her
satisfaction; and on the top of her head, woolly as a curled poodle’s, was
perched a quizzical little bonnet of reeds.
Her friend wore a muslin dress, and a cap of such antiquated form that,
sexagenarian as I am, I could never remember having seen one of similar
fashion; but afterward I remembered having seen a similar one on a portrait
of my grandmother, who lived about the middle of the last century. This
woman, who was of a more clumsy figure and had uglier features than
Mary, positively frightened me every time I looked at her; she always gave
me the idea of a cannibal chief in disguise.
The dinner-party was very cheerful. I had never seen Mr. Lambert in
such excellent spirits; as for the prince, he seems always in good-humor.
After dinner, Mr. Lambert and Mr. Laborde held a short political discussion
with the prince in another room. I was admitted to take part in this
conversation, and shall have to recur to it. The evening was unfortunately
somewhat spoiled for me by the singing chorus. The plentiful repast seemed
to have inspired the ladies with peculiar powers, for they screamed much
worse than before dinner, and, to increase the noise, clapped their hands as
an accompaniment. A few also performed the dreary dance of Madagascar
to the sound of the marovane, the only instrument yet invented by
Malagasey musical genius. It consists of a bamboo, as thick as a man’s arm,
and four feet long. Shreds of the bark are fastened all around it, supported
by little bridges of wood. The tone is very like that of a bad, worn-out
cithern.
As a conclusion, the guests themselves danced, and between the dances
Mr. Lambert gave us some very pretty songs.
About ten o’clock Mr. Laborde whispered to me that I should allege the
weakness that still remained from my late indisposition as a pretext for
breaking up the party. I replied that this was not my province, but that of
Prince Rakoto; but he urged me to do it, adding that he had a particular
reason for his request, which he would explain to me later; and,
accordingly, I broke up the party.
Favored by the brightest of moonlight, we marched up the hill toward
our dwellings to the sound of merry music.
Prince Rakoto and Mr. Lambert then called me into a side-chamber, and
the prince declared to me once more that the private contract between
himself and Mr. Lambert had been drawn up with his full concurrence, and
that he, the prince, had been grossly calumniated when he was represented
as intoxicated at the time of his signing it. He told me farther that Mr.
Lambert had come to Madagascar by his wish, and with the intention, in
conjunction with himself and a portion of the nobility and soldiers, to
remove Queen Ranavola from the throne, but without depriving her of her
freedom, her wealth, or the honors which were her due.
 Mr. Lambert, on his part, informed me that we had dined in Mr.
Laborde’s garden-house because every thing could be more quietly
discussed there, and that I had been requested to break up the party that the
little feast might seem to have been given in my honor; finally, that we had
gone through the town with the noisy music as a sign that the object of our
meeting had been social amusement.
He then showed me in the house a complete little arsenal of sabres,
daggers, pistols, and guns, wherewith to arm the conspirators, and leather
shirts of mail for resisting lance-thrusts; and told me, in conclusion, that all
preparations had been made, and the time for action had almost come—in
fact, I might expect it every hour.
I confess that a strange feeling came over me when I found myself thus
suddenly involved in a political movement of grave importance, and at the
first moment a crowd of conflicting thoughts rushed through my brain. I
could not conceal from myself the fact that if the affair failed, my life
would be in the same danger as Mr. Lambert’s; for, in a country like
Madagascar, where every thing depends on the despotic will of the ruler, no
trouble is taken to determine the question of guilty or not guilty. I had come
to Tananariva in the company of one of the chief conspirators; I had also
been present at several meetings; more was not required to make me an
accomplice in the plot, and therefore just as worthy of punishment as the
active members themselves.
My friends in the Mauritius had certainly warned me previously against
undertaking the journey in Mr. Lambert’s company, and, from what had
been reported there, and likewise from some scattered words which Mr.
Lambert had let fall from time to time, I was able to form an idea of what
was going on; but my wish to obtain a knowledge of Madagascar was so
great that it stifled all fear. Now, indeed, there was no drawing back; and the
best I could do was to put a good face upon a bad matter, and trust in that
Providence which had already helped me in many and great dangers.
I gave Prince Rakoto and Mr. Lambert my most heartfelt wishes for the
success of their undertaking, and then retired to my room. It was already
past midnight. I went to bed, and, exhausted as I was, soon fell asleep; but
all night long I had disturbed dreams, and, among others, the following very
singular one: I dreamed that the plot had been discovered, and that the
queen had summoned Mr. Lambert and myself to the palace. We were
Welcome to our website – the ideal destination for book lovers and
knowledge seekers. With a mission to inspire endlessly, we offer a
vast collection of books, ranging from classic literary works to
specialized publications, self-development books, and children's
literature. Each book is a new journey of discovery, expanding
knowledge and enriching the soul of the reade

Our website is not just a platform for buying books, but a bridge
connecting readers to the timeless values of culture and wisdom. With
an elegant, user-friendly interface and an intelligent search system,
we are committed to providing a quick and convenient shopping
experience. Additionally, our special promotions and home delivery
services ensure that you save time and fully enjoy the joy of reading.

Let us accompany you on the journey of exploring knowledge and

personal growth!

ebooknice.com