- binmode(FILEHANDLE)
- binmode FILEHANDLE
-
Arranges for the file to be read in "binary" mode in operating systems
that distinguish between binary and text files.
Files that are not read in binary mode have CR LF sequences translated
to LF on input and LF translated to CR LF on output.
Binmode has no effect under Unix.
If FILEHANDLE is an expression, the value is taken as the name of
the filehandle.
- close(FILEHANDLE)
- close FILEHANDLE
-
Closes the file or pipe associated with the file handle.
You don't have to close FILEHANDLE if you are immediately going to
do another open on it, since open will close it for you.
(See
open.)
However, an explicit close on an input file resets the line counter ($.), while
the implicit close done by
open
does not.
Also, closing a pipe will wait for the process executing on the pipe to complete,
in case you want to look at the output of the pipe afterwards.
Closing a pipe explicitly also puts the status value of the command into $?.
Example:
open(OUTPUT, '|sort >foo'); # pipe to sort
... # print stuff to output
close OUTPUT; # wait for sort to finish
open(INPUT, 'foo'); # get sort's results
FILEHANDLE may be an expression whose value gives the real filehandle name.
- dbmclose(ASSOC_ARRAY)
- dbmclose ASSOC_ARRAY
-
Breaks the binding between a dbm file and an associative array.
The values remaining in the associative array are meaningless unless
you happen to want to know what was in the cache for the dbm file.
This function is only useful if you have ndbm.
- dbmopen(ASSOC,DBNAME,MODE)
- This binds a dbm or ndbm file to an associative array.
ASSOC is the name of the associative array.
(Unlike normal open, the first argument is NOT a filehandle, even though
it looks like one).
DBNAME is the name of the database (without the .dir or .pag extension).
If the database does not exist, it is created with protection specified
by MODE (as modified by the umask).
If your system only supports the older dbm functions, you may perform only one
dbmopen in your program.
If your system has neither dbm nor ndbm, calling dbmopen produces a fatal
error.
Values assigned to the associative array prior to the dbmopen are lost.
A certain number of values from the dbm file are cached in memory.
By default this number is 64, but you can increase it by preallocating
that number of garbage entries in the associative array before the dbmopen.
You can flush the cache if necessary with the reset command.
If you don't have write access to the dbm file, you can only read
associative array variables, not set them.
If you want to test whether you can write, either use file tests or
try setting a dummy array entry inside an eval, which will trap the error.
Note that functions such as keys() and values() may return huge array values
when used on large dbm files.
You may prefer to use the each() function to iterate over large dbm files.
Example:
# print out history file offsets
dbmopen(HIST,'/usr/lib/news/history',0666);
while (($key,$val) = each %HIST) {
print $key, ' = ', unpack('L',$val), "\n";
}
dbmclose(HIST);
- eof(FILEHANDLE)
- eof()
- eof
- Returns 1 if the next read on FILEHANDLE will return end of file, or if
FILEHANDLE is not open.
FILEHANDLE may be an expression whose value gives the real filehandle name.
(Note that this function actually reads a character and then ungetc's it,
so it is not very useful in an interactive context.)
An eof without an argument returns the eof status for the last file read.
Empty parentheses () may be used to indicate the pseudo file formed of the
files listed on the command line, i.e. eof() is reasonable to use inside
a while (<>) loop to detect the end of only the last file.
Use eof(ARGV) or eof without the parentheses to test EACH file in a while (<>) loop.
Examples:
# insert dashes just before last line of last file
while (<>) {
if (eof()) {
print "--------------\n";
}
print;
}
# reset line numbering on each input file
while (<>) {
print "$.\t$_";
if (eof) { # Not eof().
close(ARGV);
}
}
- fcntl(FILEHANDLE,FUNCTION,SCALAR)
- Implements the fcntl(2) function.
You'll probably have to say
require "fcntl.ph"; # probably /usr/local/lib/perl/fcntl.ph
first to get the correct function definitions.
If fcntl.ph doesn't exist or doesn't have the correct definitions
you'll have to roll
your own, based on your C header files such as <sys/fcntl.h>.
(There is a perl script called h2ph that comes with the perl kit
which may help you in this.)
Argument processing and value return works just like ioctl below.
Note that fcntl will produce a fatal error if used on a machine that doesn't implement
fcntl(2).
- fileno(FILEHANDLE)
- fileno FILEHANDLE
-
Returns the file descriptor for a filehandle.
Useful for constructing bitmaps for select().
If FILEHANDLE is an expression, the value is taken as the name of
the filehandle.
- flock(FILEHANDLE,OPERATION)
- Calls flock(2) on FILEHANDLE.
See manual page for flock(2) for definition of OPERATION.
Returns true for success, false on failure.
Will produce a fatal error if used on a machine that doesn't implement
flock(2).
Here's a mailbox appender for BSD systems.
$LOCK_SH = 1;
$LOCK_EX = 2;
$LOCK_NB = 4;
$LOCK_UN = 8;
sub lock {
flock(MBOX,$LOCK_EX);
# and, in case someone appended
# while we were waiting...
seek(MBOX, 0, 2);
}
sub unlock {
flock(MBOX,$LOCK_UN);
}
open(MBOX, ">>/usr/spool/mail/$ENV{'USER'}")
|| die "Can't open mailbox: $!";
do lock();
print MBOX $msg,"\n\n";
do unlock();
- getc(FILEHANDLE)
- getc FILEHANDLE
- getc
- Returns the next character from the input file attached to FILEHANDLE, or
a null string at EOF.
If FILEHANDLE is omitted, reads from STDIN.
- ioctl(FILEHANDLE,FUNCTION,SCALAR)
- Implements the ioctl(2) function.
You'll probably have to say
require "ioctl.ph"; # probably /usr/local/lib/perl/ioctl.ph
first to get the correct function definitions.
If ioctl.ph doesn't exist or doesn't have the correct definitions
you'll have to roll
your own, based on your C header files such as <sys/ioctl.h>.
(There is a perl script called h2ph that comes with the perl kit
which may help you in this.)
SCALAR will be read and/or written depending on the FUNCTION--a pointer
to the string value of SCALAR will be passed as the third argument of
the actual ioctl call.
(If SCALAR has no string value but does have a numeric value, that value
will be passed rather than a pointer to the string value.
To guarantee this to be true, add a 0 to the scalar before using it.)
The pack() and unpack() functions are useful for manipulating the values
of structures used by ioctl().
The following example sets the erase character to DEL.
require 'ioctl.ph';
$sgttyb_t = "ccccs"; # 4 chars and a short
if (ioctl(STDIN,$TIOCGETP,$sgttyb)) {
@ary = unpack($sgttyb_t,$sgttyb);
$ary[2] = 127;
$sgttyb = pack($sgttyb_t,@ary);
ioctl(STDIN,$TIOCSETP,$sgttyb)
|| die "Can't ioctl: $!";
}
The return value of ioctl (and fcntl) is as follows:
if OS returns:\h'|3i'perl returns:
-1\h'|3i' undefined value
0\h'|3i' string "0 but true"
anything else\h'|3i' that number
Thus perl returns true on success and false on failure, yet you can still
easily determine the actual value returned by the operating system:
($retval = ioctl(...)) || ($retval = -1);
printf "System returned %d\n", $retval;
- open(FILEHANDLE,EXPR)
- open(FILEHANDLE)
- open FILEHANDLE
- Opens the file whose filename is given by EXPR, and associates it with
FILEHANDLE.
If FILEHANDLE is an expression, its value is used as the name of the
real filehandle wanted.
If EXPR is omitted, the scalar variable of the same name as the FILEHANDLE
contains the filename.
If the filename begins with "<" or nothing, the file is opened for
input.
If the filename begins with ">", the file is opened for output.
If the filename begins with ">>", the file is opened for appending.
(You can put a '+' in front of the '>' or '<' to indicate that you
want both read and write access to the file.)
If the filename begins with "|", the filename is interpreted
as a command to which output is to be piped, and if the filename ends
with a "|", the filename is interpreted as command which pipes
input to us.
(You may not have a command that pipes both in and out.)
Opening '-' opens
STDIN
and opening '>-' opens
STDOUT.
Open returns non-zero upon success, the undefined value otherwise.
If the open involved a pipe, the return value happens to be the pid
of the subprocess.
Examples:
$article = 100;
open article || die "Can't find article $article: $!\n";
while (<article>) {...
open(LOG, '>>/usr/spool/news/twitlog');
# (log is reserved)
open(article, "caesar <$article |");
# decrypt article
open(extract, "|sort >/tmp/Tmp$$");
# $$ is our process#
# process argument list of files along with any includes
foreach $file (@ARGV) {
do process($file, 'fh00'); # no pun intended
}
sub process {
local($filename, $input) = @_;
$input++; # this is a string increment
unless (open($input, $filename)) {
print STDERR "Can't open $filename: $!\n";
return;
}
while (<$input>) { # note use of indirection
if (/^#include "(.*)"/) {
do process($1, $input);
next;
}
... # whatever
}
}
You may also, in the Bourne shell tradition, specify an EXPR beginning
with ">&", in which case the rest of the string
is interpreted as the name of a filehandle
(or file descriptor, if numeric) which is to be duped and opened.
You may use & after >, >>, <, +>, +>> and +<.
The mode you specify should match the mode of the original filehandle.
Here is a script that saves, redirects, and restores
STDOUT
and
STDERR:
#!/usr/bin/perl
open(SAVEOUT, ">&STDOUT");
open(SAVEERR, ">&STDERR");
open(STDOUT, ">foo.out") || die "Can't redirect stdout";
open(STDERR, ">&STDOUT") || die "Can't dup stdout";
select(STDERR); $| = 1; # make unbuffered
select(STDOUT); $| = 1; # make unbuffered
print STDOUT "stdout 1\n"; # this works for
print STDERR "stderr 1\n"; # subprocesses too
close(STDOUT);
close(STDERR);
open(STDOUT, ">&SAVEOUT");
open(STDERR, ">&SAVEERR");
print STDOUT "stdout 2\n";
print STDERR "stderr 2\n";
If you open a pipe on the command "-", i.e. either "|-" or "-|",
then there is an implicit fork done, and the return value of open
is the pid of the child within the parent process, and 0 within the child
process.
(Use defined($pid) to determine if the open was successful.)
The filehandle behaves normally for the parent, but i/o to that
filehandle is piped from/to the
STDOUT/ STDIN
of the child process.
In the child process the filehandle isn't opened--i/o happens from/to
the new
STDOUT
or
STDIN.
Typically this is used like the normal piped open when you want to exercise
more control over just how the pipe command gets executed, such as when
you are running setuid, and don't want to have to scan shell commands
for metacharacters.
The following pairs are more or less equivalent:
open(FOO, "|tr '[a-z]' '[A-Z]'");
open(FOO, "|-") || exec 'tr', '[a-z]', '[A-Z]';
open(FOO, "cat -n '$file'|");
open(FOO, "-|") || exec 'cat', '-n', $file;
Explicitly closing any piped filehandle causes the parent process to wait for the
child to finish, and returns the status value in $?.
Note: on any operation which may do a fork,
unflushed buffers remain unflushed in both
processes, which means you may need to set $| to
avoid duplicate output.
The filename that is passed to open will have leading and trailing
whitespace deleted.
In order to open a file with arbitrary weird characters in it, it's necessary
to protect any leading and trailing whitespace thusly:
$file =~ s#^(\s)#./$1#;
open(FOO, "< $file\0");
- pipe(READHANDLE,WRITEHANDLE)
- Opens a pair of connected pipes like the corresponding system call.
Note that if you set up a loop of piped processes, deadlock can occur
unless you are very careful.
In addition, note that perl's pipes use stdio buffering, so you may need
to set $| to flush your WRITEHANDLE after each command, depending on
the application.
[Requires version 3.0 patchlevel 9.]
- print(FILEHANDLE LIST)
- print(LIST)
- print FILEHANDLE LIST
- print LIST
- print
- Prints a string or a comma-separated list of strings.
Returns non-zero if successful.
FILEHANDLE may be a scalar variable name, in which case the variable contains
the name of the filehandle, thus introducing one level of indirection.
(NOTE: If FILEHANDLE is a variable and the next token is a term, it may be
misinterpreted as an operator unless you interpose a + or put parens around
the arguments.)
If FILEHANDLE is omitted, prints by default to standard output (or to the
last selected output channel--see select()).
If LIST is also omitted, prints $_ to
STDOUT.
To set the default output channel to something other than
STDOUT
use the select operation.
Note that, because print takes a LIST, anything in the LIST is evaluated
in an array context, and any subroutine that you call will have one or more
of its expressions evaluated in an array context.
Also be careful not to follow the print keyword with a left parenthesis
unless you want the corresponding right parenthesis to terminate the
arguments to the print--interpose a + or put parens around all the arguments.
- printf(FILEHANDLE LIST)
- printf(LIST)
- printf FILEHANDLE LIST
- printf LIST
-
Equivalent to a "print FILEHANDLE sprintf(LIST)".
- read(FILEHANDLE,SCALAR,LENGTH,OFFSET)
- read(FILEHANDLE,SCALAR,LENGTH)
-
Attempts to read LENGTH bytes of data into variable SCALAR from the specified
FILEHANDLE.
Returns the number of bytes actually read, or undef if there was an error.
SCALAR will be grown or shrunk to the length actually read.
An OFFSET may be specified to place the read data at some other place
than the beginning of the string.
This call is actually implemented in terms of stdio's fread call. To get
a true read system call, see sysread.
- seek(FILEHANDLE,POSITION,WHENCE)
- Randomly positions the file pointer for FILEHANDLE, just like the fseek()
call of stdio.
FILEHANDLE may be an expression whose value gives the name of the filehandle.
Returns 1 upon success, 0 otherwise.
- select(FILEHANDLE)
- select
-
Returns the currently selected filehandle.
Sets the current default filehandle for output, if FILEHANDLE is supplied.
This has two effects: first, a
write
or a
print
without a filehandle will default to this FILEHANDLE.
Second, references to variables related to output will refer to this output
channel.
For example, if you have to set the top of form format for more than
one output channel, you might do the following:
select(REPORT1);
$^ = 'report1_top';
select(REPORT2);
$^ = 'report2_top';
FILEHANDLE may be an expression whose value gives the name of the actual filehandle.
Thus:
$oldfh = select(STDERR); $| = 1; select($oldfh);
- sprintf(FORMAT,LIST)
- Returns a string formatted by the usual printf conventions.
The * character is not supported.
- sysread(FILEHANDLE,SCALAR,LENGTH,OFFSET)
- sysread(FILEHANDLE,SCALAR,LENGTH)
-
Attempts to read LENGTH bytes of data into variable SCALAR from the specified
FILEHANDLE, using the system call read(2).
It bypasses stdio, so mixing this with other kinds of reads may cause
confusion.
Returns the number of bytes actually read, or undef if there was an error.
SCALAR will be grown or shrunk to the length actually read.
An OFFSET may be specified to place the read data at some other place
than the beginning of the string.
- syswrite(FILEHANDLE,SCALAR,LENGTH,OFFSET)
- syswrite(FILEHANDLE,SCALAR,LENGTH)
-
Attempts to write LENGTH bytes of data from variable SCALAR to the specified
FILEHANDLE, using the system call write(2).
It bypasses stdio, so mixing this with prints may cause
confusion.
Returns the number of bytes actually written, or undef if there was an error.
An OFFSET may be specified to place the read data at some other place
than the beginning of the string.
- tell(FILEHANDLE)
- tell FILEHANDLE
- tell
- Returns the current file position for FILEHANDLE.
FILEHANDLE may be an expression whose value gives the name of the actual
filehandle.
If FILEHANDLE is omitted, assumes the file last read.
- write(FILEHANDLE)
- write(EXPR)
- write
- Writes a formatted record (possibly multi-line) to the specified file,
using the format associated with that file.
By default the format for a file is the one having the same name is the
filehandle, but the format for the current output channel (see
select)
may be set explicitly
by assigning the name of the format to the $~ variable.
Top of form processing is handled automatically:
if there is insufficient room on the current page for the formatted
record, the page is advanced by writing a form feed,
a special top-of-page format is used
to format the new page header, and then the record is written.
By default the top-of-page format is the name of the filehandle with
"_TOP" appended, but it may be dynamicallly set to the
format of your choice by assigning the name to the $^ variable while
the filehandle is selected.
The number of lines remaining on the current page is in variable $-, which
can be set to 0 to force a new page.
If FILEHANDLE is unspecified, output goes to the current default output channel,
which starts out as
STDOUT
but may be changed by the
select
operator.
If the FILEHANDLE is an EXPR, then the expression is evaluated and the
resulting string is used to look up the name of the FILEHANDLE at run time.
For more on formats, see the section on formats later on.
Note that write is NOT the opposite of read.