Perl 5 Unleashed

Perl 5

      U N L E A S H E D

by Kamran Husain and Robert F. Breedlove

---

C  O  N  T  E  N  T  S

---

Introduction

Chapter 1  What is Perl?

• Why Perl?
• A Brief History of Perl
• The Benefits of Using Perl
  • Cost and Licensing
  • Availability
  • Interpreted Language
  • Practical
  • Language Capabilities
  • Integration with C
  • Specialized Extensions to Perl
  • Socket Capability
  • Perl Is Relatively Easy to Learn
  • Perl Has Built-In Debugging Facilities
  • Perl Help Is Readily Available
  • Perl Examples Are Readily Available
• What Are the Negatives of Using Perl?
  • Interpreted Language
  • Perceived as Public Domain
  • Informal Support
  • Protecting Proprietary Code
  • Concerns About Reliability
  • Maintainability of Scripts
  • GNU Copyleft License Agreement
• What Can Perl Do?
  • UNIX System Maintenance
  • CGI Scripts
  • Mail Processing
  • Automating Web Site Maintenance
  • Automating File Retrieval
• Is Perl for You?
• Summary

Chapter 2  A Brief Introduction to Perl

• Running Perl
• Variables in Perl
  • Special Variables
  • Code Blocks
  • Quoting Rules
• Arrays and Associative Arrays
  • What Are Associative Arrays?
• Array Operations
• File Handles and Operators
• Working with Patterns
• Subroutines
• A Final Note
• Summary

Chapter 3  References

• Introduction to References
• Using References
• The Backslash Operator
• References and Arrays
• Using Multidimensional Arrays
• References to Subroutines
  • Using Subroutine Templates
• Implementing State Machines
• Passing More Than One Array into a Subroutine
  • Pass by Value or by Reference?
• References to File Handles
  • What Does the *variable Operator Do?
• Using Symbolic References
  • Declaring with Curly Braces
  • Multidimensional Associative Arrays
• Strict References
• For More Information
• Summary

Chapter 4  Introduction to Perl Modules

• What Is a Perl Module?
• Using Perl Modules: use vs. require
• The Sample Letter.pm Module
• Subroutines and Passing Parameters
• Another Sample Module: Finance
  • Returned Values from Subroutines in a Package
• Multiple Inheritance
• The Perl Module Libraries
  • Extension Modules
  • What Is CPAN?
• Summary

Chapter 5  Object-Oriented Programming in Perl

• Introduction to Modules
  • The Three Important Rules
• Classes in Perl
• Creating a Class
• Blessing a Constructor
  • Instance Variables
• Methods
• Exporting Methods with Exporter.pm
• Invoking Methods
• Overrides
• Destructors
• Inheritance
• Overriding Methods
• A Few Comments About Classes and Objects in Perl
• Summary

Chapter 6  Binding Variables to Objects

• The tie() Function
• Tying Scalars
• Tying to an Array
• Tying to an Associative Array
• For More Information
• Summary

Chapter 7  String and Patterns

• Basic String Operations
  • The chop() and length() Functions
  • Handling the Case in Strings
  • Joining Strings Together
  • Printing Formatted Numbers
• Finding Substrings
  • The substr Function
  • String Searching with Patterns
  • Special Characters in Perl Pattern Searches
  • Shortcuts for Words in Perl
  • The quotemeta Function
  • Specifying the Number of Matches
  • Specifying More Than One Choice
  • Searching a String for More Than One Pattern to Match
• Reusing Portions of Patterns
• Pattern-Matching Options
• Substituting Text Through Pattern Matching
• The Translation Operator
• Extended Pattern Matching
• Summary

Chapter 8  Documenting Perl Scripts

• Embedding man Pages
• The POD Format
• Translating POD into Other Formats
• Summary

Chapter 9  Portability Issues with Windows and Perl

• Perl for Windows
• Getting the Distribution
• Differences in Perl on NT and UNIX
• Unsupported Functions
• Extensions to Perl 5 for Windows NT
  • Event Log Functions
  • NT Registry Routines
• Problems with Windows 95
• Summary

Chapter 10  Win32 Modules on Windows NT

• The Win32 Module
• The Process Module Extensions
• The Kill Method
  • The Resume and Suspend Methods
  • The GetExitCode() Function
  • The Wait($Timeout) Function
  • Class Priority
• The Win32::Semaphore Utilities
• Using Mutex with Win32::Mutex
• Using Win32::ChangeNotification
• The Win32::Eventlog Module
  • Reading Events
  • Reporting the Contents of an Event
• The Win32::Registry Module
• The Win32::NetAdmin Module
  • Adding a User
  • Creating or Deleting a Group
  • Comments About a Group
  • Adding Users to a Group
  • Removing Users from a Group
  • Checking Group Membership
  • Listing Group Members
• Using the Win32::Service Module
• Using the Win32::NetResource Module
• Handling Input from Multiple Sources
• Summary

Chapter 11  Security Issues in Perl

• A Few Words Before We Begin
• Setuid Scripts
• Why Is Perl More Secure Than Shell Scripts?
• Some Tips on Making Scripts Secure
• The Perl Safe.pm Module
  • Using the Safe Class
• Setuid CGI Scripts and CGIwrap
• Reference Books
• Summary

Chapter 12  Using Sockets

• A Very Brief Introduction to Sockets
• Perl Functions for Working with Protocols
• Socket Primitives
  • socket()
  • The bind() System Call
  • The listen() and accept() System Calls
  • The connect() System Call
• Connection-Oriented Servers in Perl
• The h2ph Script
• Using Socket.pm
• Summary

Chapter 13  Messaging Facilities: The System V Ipc Functions

• An Introduction to the System V Ipc
• Using the UNIX System V Ipc Functions
  • The msgget() Function
• The ipcs Command
• The msgsnd() and msgrcv() Functions
• Shared Memory
  • The shmwrite() and shmread() Functions
• Semaphores
• The SysV::Ipc Module
• Applications of Ipc
• Summary

Chapter 14  Signals, Pipes, FIFOs, and Perl

• Signals
  • Using the Config Module
• The kill() Function
• The warn() Function
• Timeouts
• Pipes and FIFOs
• Using open() for Ipc
• Summary

Chapter 15  Direct Access to System Facilities

• Introduction
• Working with UNIX Users and Groups
  • Information from /etc/passwd with getpwent()
  • Getting Group-Related Information with getgrent() and getgrnam()
• Getting Information in Network Files
  • The getnetent Function
  • Working with Host Names Using gethostbyaddr() Functions
  • Working with Process Groups Using the getpgrp() Function
• Getting and Changing the Priority of a Process
  • The setpriority Function
  • The getpriority Function
  • Working with Protocol Files Using the getprotoent() Function
  • The getservent Function
• System-Level Functions
  • The chroot Function
  • The dump Function
  • Using the ioctl Function
  • Using the select Call
  • The syscall Function
• Summary

Chapter 16  Command-line Interface with Perl

• The Command-line Options to Perl
  • Sending Options via the Command Line
  • Specifying an Option within the Program
  • The -c and -w Syntax Checking and Warning Options
  • The -e Option: Executing a Single-line Program
  • The -s Option to Supply Custom Command-line Options
  • The -I Option to Include Other Files
  • The -P Option for Using the C Preprocessor
  • Using the -n and -p Options for Handling Multiple Files
  • The -i Option to Edit Files
  • Using the -a Option
  • Using the -F Option
  • Using the -0 Option
  • Using the -l Option
  • Using the -x Option to Get a Perl Program from Another File
  • Using the -S Option
  • The -v Option: Printing the Perl Version Number
  • Using Conditional Code with the C Preprocessor
• Reading Input from STDIN
  • The Term::Query Module
  • Using the Term::Query Module
  • Extending the Query.pm Module
  • Using query_table()
• The Getopts Package
  • Using Std.pm
  • The Long.pm module
  • Examples of Options Settings
• Summary

Chapter 17  GUI Interfaces with Perl/Tk

• Introduction to the Perl/Tk Package
  • About the Authors of the Perl/Tk Package
• Where Do I Get and Build Perl/Tk?
• Documentation for Perl/Tk
• Writing Scripts in Perl/Tk
• Widgets as Building Blocks
• Configuring Widgets
  • Using CheckButton Widgets
  • Using RadioButton Widgets
  • Calling Subroutines When a Button Is Pressed
  • Arranging the Layout of Widgets
  • Using the Listbox and Scrollbar Widgets
  • Using Text Widgets
  • Specifying Fonts for Text and Other Widgets
  • Text Entry Widgets
• Handling the Keyboard with Key Bindings
• Displaying a Bitmap
• Displaying Images with Photo
• Menus
• The Canvas Widget
• Miscellaneous Topics
  • References with Subroutines
  • Changing the Cursor
  • Debugging Your Perl/Tk Scripts
  • More Than One Input File Handle
  • Eliminating and Hiding Windows
  • Creating More Than One Independent Window
• Summary

Chapter 18  Databases for Perl

• The DBM Packages
• Viewing Your Data
• Adding and Removing Items
• Operations on a DBM File
• Using DBM in Modules
• Multiple DBM Files
• The Catch with DBM Utilities
• What Is the DBI Package?
  • Available Packages
• RDB
• Summary

Chapter 19  Generating Reports

• Formatted Output
• Defining a Format
• Using the format Statement
• Using More Than One Format
• Controlling the Format
• Creating Multiple Lines with the Caret
• Using format in Modules
• Another Example of Report Generation
• Summary

Chapter 20  Introduction to Web Pages and CGI

• HTML, CGI, and MIME
• A Simple HTML Document
• Formatting Lists
• Using HTML Tags
• Preformatted Text
• Special Characters in HTML Documents
• What Is a URL?
• CGI Scripts
  • CONTENT_LENGTH
  • CONTENT_TYPE
  • GATEWAY_INTERFACE
  • PATH_INFO
  • QUERY_STRING
• Input and Output to CGI Scripts
• A Test CGI Script
• Using Frames
• Summary

Chapter 21  Building VRML Models with Perl

• What Is VRML?
  • Why Write VRML.pm?
  • Where to Get More Information on VRML
• Basics of VRML
• Building the VRML Perl Module
  • Where to Get the Source for the Perl to VRML Package
• Using VRML.pm
• How to View Your World
• Inside the VRML.pm Package
• Summary

Chapter 22  Using HTML FORMs with Perl CGI Scripts

• Input and Output with CGI
• What Are GET and POST?
• Handling HTML FORMs with GET Methods
• Handling an HTML FORM with POST Methods
• Returning HTML Pages
• Using the Collected Data
  • Archiving User Responses
  • Forwarding User Responses
• Summary

Chapter 23  HTML with Perl Modules

• Presenting Data on the Web Using CGI Scripts
• Collecting User Input Using Perl Modules
• Using Tables in HTML
• Using the HTML Module
• Constructing HTML Objects
• Specifying the Body of the Text in HTML Documents
• Controlling the Output Destination File
• Using the Tables Feature in HTML::Base
• Making Clickable Images in HTML
• Summary

Chapter 24  Building and Installing the Perl 5 Interpreter

• Getting Perl 5
  • Getting Perl from the Internet
  • Getting Perl via E-mail
  • Web Sites with Perl Information
  • On CD-ROM
• Installing Perl on Most UNIX Systems
  • Configuring Your Perl Distribution
  • Making Dependencies
  • What Are hints Files?
• Running Some Tests
  • Finishing It Up
  • Confirming the Installation
• The DOS Platform
• Other Platforms
• Linux: A Special Case for Perl 5
  • Partial Upgrades of Your Linux Kernel for Getting Perl Running
  • The Real Danger During the Partial Upgrade
• Summary

Chapter 25  Perl Internal Files and Structures

• Introduction
  • Exploring Perl Source Code
• Perl Variable Types
  • Naming Conventions
• Scalars and Scalar Functions
• Array Functions
• Hash Functions
• Mortality of Variables
• Subroutines and Stacks
• What Is Magic?
• The Global Variable (GV) Type
• Where to Look for More Information
• Summary

Chapter 26  Writing C Extensions in Perl

• Introduction
• Compiling a C Program That Calls Perl
  • What Is ExtUtils::embed?
  • Using the embed.pm Package
• Adding a Perl Interpreter to Your C Program
• Calling Perl Subroutines from Within a C Program
• Working with the Perl Stack
  • The perl_call_sv Function
  • The perl_call_pv Function
  • The perl_call_method Function
  • The perl_call_argv Function
• The Flags to Use
  • The G_DISCARD Flag
  • The G_NOARGS Flag
  • The G_SCALAR Flag
  • The G_ARRAY Flag
  • The G_EVAL Flag
• Using SCALAR Context
• Returning Lists from Subroutines
• Using G_EVAL
• Getting Special Variable Values
• Using the ST Macros
• Evaluating Perl Expressions
• Pattern Matches and Substitutions from Your C Program
• Summary

Chapter 27  Writing Extensions in C

• Introduction to XS
• Steps for Creating an Extension
  • Step 1: Change to the Perl Directory
  • Step 2: Run h2sx
  • Step 3: Create a Makefile
  • Step 4: Add Some Code
  • Step 5: Test Your Extension Module
  • Final Considerations
• The xsubpp Compiler
• Input and Output Parameters to Functions
  • The typemap File
• The bootstrap Function
• Passing Arguments
• The RETVAL Variable and the OUTPUT Section
• Keywords
  • The MODULE Keyword
  • The PACKAGE Keyword
  • The CODE: Keyword
  • The OUTPUT: Keyword
  • PpcODE: for Returning More Than One Value
  • Returning Undef and Empty Lists
  • The BOOT: Keyword
• The Listings of Modules
• Summary

Chapter 28  Client/Server Using Java Applets and Perl

• Using CGI or Sockets
• Using the Disk
  • A Quick Note About Java
• Using CGI and Sockets
• For More Information on How to Program in Java
• Summary

Chapter 29  Practical Scripts While Using Perl

• Statistical Applications
• Using Perl for Simple Statistical Routines
  • Dot and Cross Products of Vectors
  • Adding or Subtracting Vectors
• Using Matrices
  • Reading the Image
  • Getting a Histogram
• The Filter
• An Added Touch
• A Parting Note
• Summary

Chapter 30  Using the Perl Debugger

• A Sample Session
• Stepping Through Code
• Looking at Values
• Breakpoints
• Actions
• Searching for Patterns
• Subroutines
• Caveats
• Customizing Your Debugger Environment
• For More Information
• Summary

Chapter 31  Generating Code

• Introduction
• Choosing the Input File
• Parsing Records
• Writing the C Header Files
• Writing the Encoder Source File
• Writing the Decoder
• Putting It Together
• Summary

Chapter 32  Dynamic Image Creation

• Introduction
• Two-Dimensional Plots
• Three-Dimensional Plots
• Using the Output in CGI Applications
• Creating GIF Images Directly from Perl
  • Installing the gd Library
  • Installing GD.pm
• Working with GD.pm
• Using GD with HTML Pages
• Summary

Chapter 33  Debugging CGI Applications

• Wrong Permissions on CGI Scripts
  • Checking Returned Values from Scripts
  • Checking Errors When Opening Files
  • Debug Your CGI Script
  • Checking Errors When Opening Pipes
  • Send Mail to Valid Recipients
• Use the Perl Interpreter Line on UNIX Systems
• Libraries for Dynamically Loaded Modules
• Check for Support for System Calls
• Don't Return Malformed Headers
• Flush Output Buffers Immediately
• Don't Set Environment Variables
• Clean Up After Yourself
• Configure Your Server Correctly
• Always Create an index.html File
• Summary

appendix A  Perl 5 Function and Variable Reference

appendix B  Perl Module Archives 737

• CPAN Sites
  • Module Examples
• Perl 5 Module List
• Newsgroups
• Web Pages
• Frequently Asked Questions (FAQ) Lists
  • Perl Meta-FAQ
  • Perl FAQ
• Mailing Lists
• Other Resources
• Summary

Credits

---

This book is dedicated to my parents: Dr. Saleha Bilal Husain and Dr. Bilal Riaz Husain. -KH To my family, my wife Madeline for giving me the time and encouragement, and my children Delenn, Duncan, and Diego for setting my life in perspective. -BB

Copyright © 1996 by Sams Publishing

FIRST EDITION

All rights reserved. No part of this book shall be reproduced, stored in a retrieval system, or transmitted by any means, electronic, mechanical, photocopying, recording, or otherwise, without written permission from the publisher. No patent liability is assumed with respect to the use of the information contained herein. Although every precaution has been taken in the preparation of this book, the publisher and author assume no responsibility for errors or omissions. Neither is any liability assumed for damages resulting from the use of the information contained herein. For information, address Sams Publishing, 201 W. 103rd St., Indianapolis, IN 46290.

International Standard Book Number: 0-672-30891-6

HTML conversion by :
    M/s. LeafWriters (India) Pvt. Ltd.
    Website : http://leaf.stpn.soft.net
    e-mail : leafwriters@leaf.stpn.soft.net

All terms mentioned in this book that are known to be trademarks or service marks have been appropriately capitalized. Sams Publishing cannot attest to the accuracy of this information. Use of a term in this book should not be regarded as affecting the validity of any trademark or service mark.

---

Publisher	Richard K. Swadley
Publishing Team Leader	Greg Wiegand
Managing Editor	Cindy Morrow
Director of Marketing	John Pierce
Assistant Marketing Managers	Kristina Perry, Rachel Wolfe

---

Acquisitions Editor	Christopher Denny	Development Editor	Anthony Amico
Software Development Specialist	Brad Myers	Production Editors	Kristi Hart, Katherine Ewing
Copy Editor	Bart Reed	Indexer	Chris Barrick
Technical Reviewers	Zachary Bir, John Fleming, Elliotte Harold, Scott Hutton, Matt Liggett, John Neinart	Editorial Coordinator	Bill Whitmer
Technical Edit Coordinator	Lynette Quinn	Editorial Assistants	Carol Ackerman, Andi Richter, Rhonda Tinch-Mize
Cover Designer	Tim Amrhein	Book Designer	Gary Adair
Copy Writer	Peter Fuller	Production Team Supervisor	Brad Chinn
Production	Debra Bolhuis, Mona Brown, Michael Dietsch, Jason Hand, Daniel Harris, Bill Hartman, Susan Knose, Clint Lahnen, Paula Lowell, Laura Robbins, Bobbi Satterfield, Susan Van Ness, Suzanne Whitmer

---

Acknowledgements

First of all, I would like to thank Chris Denny at Sams for giving me the opportunity to write a book on Perl 5. I would also to thank Kristi Hart, Tony Amico, and Bart Reed for their patience, help, advice, and forcing me to keep up with deadlines.

I'd like to thank Uzma, my wife, and Haya and Hana, my twin daughters, for putting up with my weird schedules and odd hours.

Last, but definitely not the least, thanks to all the Perl programmers on Perl mailing lists for all the critique and comments via e-mail.

---

About the Authors

Kamran Husain is a software consultant specializing in developing real-time applications, data acquisition, and turn-key systems in all sorts of software environments including C++, Java, Windows NT and 95, JavaScript, and Motif. He can be reached via e-mail at khusain@ikra.com.

Robert F. Breedlove is a senior systems engineer with EDS. He has over 20 years of experience in data processing including extensive client/server, UNIX, intranet and Internet experience. He can be reached at breedlov@netcom.com, or at his homepage: http://www.channel1.com/users/rbreed01/.

Tell Us What You Think!

As a reader, you are the most important critic and commentator of our books. We value your opinion and want to know what we're doing right, what we could do better, what areas you'd like to see us publish in, and any other words of wisdom you're willing to pass our way. You can help us make strong books that meet your needs and give you the computer guidance you require.

Do you have access to CompuServe or the World Wide Web? Then check out our CompuServe forum by typing GO SAMS at any prompt. If you prefer the World Wide Web, check out our site at http://www.mcp.com.

Note

If you have a technical question about this book, call the technical support line at (800) 571-5840, ext. 3668.

As the team leader of the group that created this book, I welcome your comments. You can fax, e-mail, or write me directly to let me know what you did or didn't like about this book-as well as what we can do to make our books stronger. Here's the information:

FAX:	317/581-4669
E-mail:	programming_mgr@sams.mcp.com
Mail:	Greg Wiegand Comments Department Sams Publishing 201 W. 103rd Street Indianapolis, IN 46290

---

Introduction

This book documents a very powerful language called Perl 5, which is version 5 of Larry Wall's creation, Perl. Perl is fast becoming the de facto language for UNIX system administrators, Webmasters on the World Wide Web, and programmers who want a fast, powerful, and easy-to-use program language. This book will provide you with the basics of the language and introduce you to the tools available for Perl.

While writing this book, I assumed that you, the reader, have had some prior programming experience. If you do not have any prior programming experience, I strongly suggest not skipping the first three chapters. If you are already a programmer and are familiar with Perl 4, this book should provide you with enough knowledge to use the great new features.

How This Book Is Organized

This book is divided into six parts.

Part I: The Basics

The first part provides a brief introduction to Perl as a programming language. It covers the use of references to variables, regular expressions, and the fundamentals of programming in Perl by using modules. It introduces the use of Perl for programming with an object-oriented paradigm. It also covers the not-so-basic but very important topic of tying variables in Perl programs.

Part II: Communications

The second part covers applying Perl to different platforms and types of applications. It begins with a chapter on processing patterns and strings in Perl. For a long time, I debated reversing the order of Chapters 6 and 7 because the concepts are both fundamental, but the chapter on tying variables seemed to fit in the first part. Most of the portability issues in programming in Perl on a Windows platform are also discussed in this part.

Part III: Presenting and Sharing Data

The third part gets into networking and system-level programming issues for Perl. The basic communications features in Perl include sockets, System V Ipc messaging facilities, signals, pipes, and FIFOs, and are covered in this part. The basics of handling the command-line interface as well as a graphical user interface using Tcl/Tk and Perl are also covered in this part. The last two chapters of this part introduce the use of database front-ends and the report-generating facilities of Perl. The information in this part serves as the basis for writing Perl applications that can provide reports on data stored in databases.

Part IV: Working with the Web

Section four introduces the World Wide Web and the Common Gateway Interface (CGI). Thick books have been written on these topics, and this part attempts to present the most practical information required to get you started writing CGI scripts and your own Web pages. This part covers how to access databases from within Perl and how to write your own module to generate VRML objects. The information in this chapter can serve as a basis for writing your own CGI scripts using the modules available on the World Wide Web for Perl.

Part V: Under the Hood

The chapters in this part are geared towards the advanced user or the system administrator who has to install Perl on various platforms. The topics in this part tend to be centered on UNIX systems, but that's just where most of the heavy Perl development seems to be. I cover the internal data types used in Perl, and then based on this knowledge I go on to show the techniques of writing extensions and embedding Perl in C programs.

This part covers the use of the Perl debugger. This was the part where I wanted to present some case studies on how to use Perl as a prototyping language to solve problems. I use Perl to solve some real-world problems involving parsing weird data formats and creating images on demand, and then I discuss issues on how to debug CGI applications. This part also covers how to use Java applets on a client to communicate with Perl servers, which is a hot Internet topic.

Conventions Used in This Book

The following typographic conventions are used in this book:

• Code lines, commands, statements, variables, and any text you type or see on the screen appears in a computer typeface. When lines of input and output are shown together, bold computer typeface is used to show the user's input.
• Placeholders in syntax descriptions and code snippets appear in italic computer typeface.
  Replace the placeholder with the actual filename, parameter, or whatever element it represents.
• Italics are used to emphasize important points.
• Sometimes a line of code is too long to fit as a single printed line in the book. If you see the special icon  at the beginning of a line of code, you should interpret that "line" as a continuation of the line preceding it.

There's Always a Better Way

Now for a personal disclaimer of sorts. Even though I attempt to cover all the major points of the latest release of Perl, version 5.002 at the time we go to print, I probably will never be able to list all the features of this wonderful language. If there is one thing that I've learned while working with Perl, it is that there are so many ways of doing any one task. Every time I write a Perl script, I think that I "could've done it this way and maybe it'll run faster." The number of combinations of things to do with Perl never really ends. So, if you find a better way of writing Perl scripts than the ones shown in this book, don't be surprised-it's bound to happen. Do drop me a line, though, because I will incorporate them into the next edition of this book. I look forward to receiving all your comments and, yes, even criticisms and the usual flames.

---

---