File IO and Filesystem Functions

In input/output operations, FILEHANDLE may be a filehandle as opened by the open operator, a predefined filehandle (e.g., STDOUT) or a scalar variable that evaluates to the name of a filehandle to be used.

Perl's "open" function was designed to mimic the way command-line redirection in the shell works. Examples:

open INFO, "< datafile" or die "can't open datafile: $!"; open RESULTS,"> runstats" or die "can't open runstats: $!"; open LOG, ">> logfile " or die "can't open logfile: $!"; The leading less-than is optional. If omitted, Perl assumes that you want to open the file for reading.

Any white space before or after the filename is ignored.

Pipe Opens

If the leading character is a pipe symbol, "open" starts up a new command and open a write-only filehandle leading into that command. This lets you write into that handle and have what you write show up on that command's standard input. For example: open(PRINTER, "| lpr -Plp1") || die "can't run lpr: $!"; print PRINTER "stuff\n"; close(PRINTER) || die "can't close lpr: $!"; If the trailing character is a pipe, you start up a new command and open a read-only filehandle leading out of that command. This lets whatever that command writes to its standard output show up on your handle for reading. For example: open(NET, "netstat -i -n |") || die "can't fun netstat: $!"; while (<NET>) { } # do something with input close(NET) || die "can't close netstat: $!";

The <> Default File Handle

One of the most common uses for "open" is one you never even notice. When you process the ARGV filehandle using "", Perl actually does an implicit open on each file in @ARGV. Thus a program called like this:

$ myprogram file1 file2 file3

Can have all its files opened and processed one at a time using a construct no more complex than: while (<>) { # do something with $_ } If @ARGV is empty when the loop first begins, Perl pretends you've opened up minus, that is, the standard input. In fact, $ARGV, the currently open file during "" processing, is even set to "-" in these circumstances.

File IO Example

open FILE , ">my_file.txt"; print FILE "it's me!\n"; close FILE; open FILE , "<my_file.txt"; while( <FILE> ) { print $_; } close FILE;

File IO Functions

binmode FILEHANDLE

Arranges for the file opened on FILEHANDLE to be read or written in binary mode as opposed to text mode (null operation on UNIX).

close FILEHANDLE

Closes the file or pipe associated with the filehandle.

dbmclose %HASH

Deprecated, use untie instead.

dbmopen %HASH, DBMNAME, MODE

Deprecated, use tie instead.

eof FILEHANDLE

Returns true if the next read will return end of file, or if the file is not open.

eof

Returns the EOF status for the last file read.

eof()

Indicates EOF on the pseudo file formed of the files listed on the command line.

fcntl FILEHANDLE, FUNCTION, $VAR

Implements the fcntl(2) function. This function has non-standard return values.

fileno FILEHANDLE

Returns the file descriptor for a given (open) file.

flock FILEHANDLE, OPERATION

Calls flock(2) on the file. OPERATION formed by adding 1 (shared), 2 (exclusive), 4 (non-blocking), or 8 (unlock).

getc [ FILEHANDLE ]

Yields the next character from the file, or an empty string on end of file. If FILEHANDLE is omitted, reads from STDIN.

ioctl FILEHANDLE, FUNCTION, $VAR

Performs ioctl(2) on the file. This function has non-standard return values.

open FILEHANDLE [ , FILENAME ]

Opens a file and associates it with FILEHANDLE. If FILENAME is omitted, the scalar variable of the same name as the FILEHANDLE must contain the filename.
The following filename conventions apply when opening a file.

`"`FILE`"`	open FILE for input. Also `"<`FILE`"`.
`">`FILE`"`	open FILE for output, creating it if necessary.
`">>`FILE`"`	open FILE in append mode.
`"+<`FILE`"`	open FILE with read/write access (file must exist).
`"+>`FILE`"`	open FILE with read/write access (file truncated).
`"\|`CMD`"`	opens a pipe to command CMD; forks if CMD is `-`.
`"`CMD`\|"`	opens a pipe from command CMD; forks if CMD is `-`.

FILE may be &FILEHND in which case the new filehandle is connected to the (previously opened) filehandle FILEHND. If it is &=N, FILE will be connected to the given file descriptor. open returns undef upon failure, true otherwise.

pipe READHANDLE, WRITEHANDLE

Returns a pair of connected pipes.

print [ FILEHANDLE ] [ LIST† ]

Equivalent to print FILEHANDLE sprintf LIST.

printf[([FILEHANDLE] LIST†)]

Equivalent to print FILEHANDLE sprintf(LIST).

read FILEHANDLE, $VAR, LENGTH [ , OFFSET ]

Reads LENGTH binary bytes from the file into the variable at OFFSET. Returns number of bytes actually read.

seek FILEHANDLE, POSITION, WHENCE

Arbitarily positions the file. Returns true if successful.

select [ FILEHANDLE ]

Returns the currently selected filehandle. Sets the current default filehandle for output operations if FILEHANDLE is supplied.

select RBITS, WBITS, NBITS, TIMEOUT

Performs a select(2) system call with the same parameters.

sprintf FORMAT, LIST

Returns a string formatted by (almost all of) the usual printf(3) conventions.

sysread FILEHANDLE, $VAR, LENGTH [ , OFFSET ]

Reads LENGTH bytes into $VAR at OFFSET.

syswrite FILEHANDLE, SCALAR, LENGTH [ , OFFSET ]

Writes LENGTH bytes from SCALAR at OFFSET.

tell [ FILEHANDLE ]

Returns the current file position for the file. If FILENAME is omitted, assumes the file last read.

write [ FILEHANDLE ]

Writes a formatted record to the specified file, using the format associated with that file.

Operations on Files

Functions operating on a list of files return the number of files successfully operated upon.

chmod LIST: Changes the permissions of a list of files. The first element of the list must be the numerical mode.
chown LIST: Changes the owner and group of a list of files. The first two elements of the list must be the numerical uid and gid.
truncate FILE, SIZE: Truncates FILE to SIZE. FILE may be a filename or a filehandle.
link OLDFILE, NEWFILE: Creates a new filename linked to the old filename.
lstat FILE: Like stat, but does not traverse a final symbolic link.
mkdir DIR, MODE: Creates a directory with given permissions. Sets $! on failure.
readlink EXPR†: Returns the value of a symbolic link.
rename OLDNAME, NEWNAME: Changes the name of a file.
rmdir FILENAME†: Deletes the directory if it is empty. Sets $! on failure.
stat FILE: Returns a 13-element array (0: $dev, 1: $ino, 2: $mode, 3: $nlink, 4: $uid, 5: $gid, 6: $rdev, 7: $size, 8: $atime, 9: $mtime, 10: $ctime, 11: $blksize, 12: $blocks). FILE can be a filehandle, an expression evaluating to a filename, or _ to refer to the last file test operation or stat call. Returns a null list if the stat fails.
symlink OLDFILE, NEWFILE: Creates a new filename symbolically linked to the old filename.
unlink LIST: Deletes a list of files.
utime LIST: Changes the access and modification times. The first two elements of the list must be the numerical access and modification times.