perl.man

早期freebsd实现

Each operator decides which sort of scalar it would be most
appropriate to return.
Some operators return the length of the list
that would have been returned in an array context.
Some operators return the first value in the list.
Some operators return the last value in the list.
Some operators return a count of successful operations.
In general, they do what you want, unless you want consistency.
.Ip "/PATTERN/" 8 4
See m/PATTERN/.
.Ip "?PATTERN?" 8 4
This is just like the /pattern/ search, except that it matches only once between
calls to the
.I reset
operator.
This is a useful optimization when you only want to see the first occurrence of
something in each file of a set of files, for instance.
Only ?? patterns local to the current package are reset.
.Ip "accept(NEWSOCKET,GENERICSOCKET)" 8 2
Does the same thing that the accept system call does.
Returns true if it succeeded, false otherwise.
See example in section on Interprocess Communication.
.Ip "alarm(SECONDS)" 8 4
.Ip "alarm SECONDS" 8
Arranges to have a SIGALRM delivered to this process after the specified number
of seconds (minus 1, actually) have elapsed.  Thus, alarm(15) will cause
a SIGALRM at some point more than 14 seconds in the future.
Only one timer may be counting at once.  Each call disables the previous
timer, and an argument of 0 may be supplied to cancel the previous timer
without starting a new one.
The returned value is the amount of time remaining on the previous timer.
.Ip "atan2(Y,X)" 8 2
Returns the arctangent of Y/X in the range
.if t \-\(*p to \(*p.
.if n \-PI to PI.
.Ip "bind(SOCKET,NAME)" 8 2
Does the same thing that the bind system call does.
Returns true if it succeeded, false otherwise.
NAME should be a packed address of the proper type for the socket.
See example in section on Interprocess Communication.
.Ip "binmode(FILEHANDLE)" 8 4
.Ip "binmode FILEHANDLE" 8 4
Arranges for the file to be read in \*(L"binary\*(R" 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.
.Ip "caller(EXPR)"
.Ip "caller"
Returns the context of the current subroutine call:
.nf

	($package,$filename,$line) = caller;

.fi
With EXPR, returns some extra information that the debugger uses to print
a stack trace.  The value of EXPR indicates how many call frames to go
back before the current one.
.Ip "chdir(EXPR)" 8 2
.Ip "chdir EXPR" 8 2
Changes the working directory to EXPR, if possible.
If EXPR is omitted, changes to home directory.
Returns 1 upon success, 0 otherwise.
See example under
.IR die .
.Ip "chmod(LIST)" 8 2
.Ip "chmod LIST" 8 2
Changes the permissions of a list of files.
The first element of the list must be the numerical mode.
Returns the number of files successfully changed.
.nf

.ne 2
	$cnt = chmod 0755, \'foo\', \'bar\';
	chmod 0755, @executables;

.fi
.Ip "chop(LIST)" 8 7
.Ip "chop(VARIABLE)" 8
.Ip "chop VARIABLE" 8
.Ip "chop" 8
Chops off the last character of a string and returns the character chopped.
It's used primarily to remove the newline from the end of an input record,
but is much more efficient than s/\en// because it neither scans nor copies
the string.
If VARIABLE is omitted, chops $_.
Example:
.nf

.ne 5
	while (<>) {
		chop;	# avoid \en on last field
		@array = split(/:/);
		.\|.\|.
	}

.fi
You can actually chop anything that's an lvalue, including an assignment:
.nf

	chop($cwd = \`pwd\`);
	chop($answer = <STDIN>);

.fi
If you chop a list, each element is chopped.
Only the value of the last chop is returned.
.Ip "chown(LIST)" 8 2
.Ip "chown LIST" 8 2
Changes the owner (and group) of a list of files.
The first two elements of the list must be the NUMERICAL uid and gid,
in that order.
Returns the number of files successfully changed.
.nf

.ne 2
	$cnt = chown $uid, $gid, \'foo\', \'bar\';
	chown $uid, $gid, @filenames;

.fi
.ne 23
Here's an example that looks up non-numeric uids in the passwd file:
.nf

	print "User: ";
	$user = <STDIN>;
	chop($user);
	print "Files: "
	$pattern = <STDIN>;
	chop($pattern);
.ie t \{\
	open(pass, \'/etc/passwd\') || die "Can't open passwd: $!\en";
'br\}
.el \{\
	open(pass, \'/etc/passwd\')
		|| die "Can't open passwd: $!\en";
'br\}
	while (<pass>) {
		($login,$pass,$uid,$gid) = split(/:/);
		$uid{$login} = $uid;
		$gid{$login} = $gid;
	}
	@ary = <${pattern}>;	# get filenames
	if ($uid{$user} eq \'\') {
		die "$user not in passwd file";
	}
	else {
		chown $uid{$user}, $gid{$user}, @ary;
	}

.fi
.Ip "chroot(FILENAME)" 8 5
.Ip "chroot FILENAME" 8
Does the same as the system call of that name.
If you don't know what it does, don't worry about it.
If FILENAME is omitted, does chroot to $_.
.Ip "close(FILEHANDLE)" 8 5
.Ip "close FILEHANDLE" 8
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
.IR open .)
However, an explicit close on an input file resets the line counter ($.), while
the implicit close done by
.I 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:
.nf

.ne 4
	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

.fi
FILEHANDLE may be an expression whose value gives the real filehandle name.
.Ip "closedir(DIRHANDLE)" 8 5
.Ip "closedir DIRHANDLE" 8
Closes a directory opened by opendir().
.Ip "connect(SOCKET,NAME)" 8 2
Does the same thing that the connect system call does.
Returns true if it succeeded, false otherwise.
NAME should be a package address of the proper type for the socket.
See example in section on Interprocess Communication.
.Ip "cos(EXPR)" 8 6
.Ip "cos EXPR" 8 6
Returns the cosine of EXPR (expressed in radians).
If EXPR is omitted takes cosine of $_.
.Ip "crypt(PLAINTEXT,SALT)" 8 6
Encrypts a string exactly like the crypt() function in the C library.
Useful for checking the password file for lousy passwords.
Only the guys wearing white hats should do this.
.Ip "dbmclose(ASSOC_ARRAY)" 8 6
.Ip "dbmclose ASSOC_ARRAY" 8
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.
.Ip "dbmopen(ASSOC,DBNAME,MODE)" 8 6
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.
.Sp
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.
.Sp
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.
.Sp
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:
.nf

.ne 6
	# print out history file offsets
	dbmopen(HIST,'/usr/lib/news/history',0666);
	while (($key,$val) = each %HIST) {
		print $key, ' = ', unpack('L',$val), "\en";
	}
	dbmclose(HIST);

.fi
.Ip "defined(EXPR)" 8 6
.Ip "defined EXPR" 8
Returns a boolean value saying whether the lvalue EXPR has a real value
or not.
Many operations return the undefined value under exceptional conditions,
such as end of file, uninitialized variable, system error and such.
This function allows you to distinguish between an undefined null string
and a defined null string with operations that might return a real null
string, in particular referencing elements of an array.
You may also check to see if arrays or subroutines exist.
Use on predefined variables is not guaranteed to produce intuitive results.
Examples:
.nf

.ne 7
	print if defined $switch{'D'};
	print "$val\en" while defined($val = pop(@ary));
	die "Can't readlink $sym: $!"
		unless defined($value = readlink $sym);
	eval '@foo = ()' if defined(@foo);
	die "No XYZ package defined" unless defined %_XYZ;
	sub foo { defined &$bar ? &$bar(@_) : die "No bar"; }

.fi
See also undef.
.Ip "delete $ASSOC{KEY}" 8 6
Deletes the specified value from the specified associative array.
Returns the deleted value, or the undefined value if nothing was deleted.
Deleting from $ENV{} modifies the environment.
Deleting from an array bound to a dbm file deletes the entry from the dbm
file.
.Sp
The following deletes all the values of an associative array:
.nf

.ne 3
	foreach $key (keys %ARRAY) {
		delete $ARRAY{$key};
	}

.fi
(But it would be faster to use the
.I reset
command.
Saying undef %ARRAY is faster yet.)
.Ip "die(LIST)" 8
.Ip "die LIST" 8
Outside of an eval, prints the value of LIST to
.I STDERR
and exits with the current value of $!
(errno).
If $! is 0, exits with the value of ($? >> 8) (\`command\` status).
If ($? >> 8) is 0, exits with 255.
Inside an eval, the error message is stuffed into $@ and the eval is terminated
with the undefined value.
.Sp
Equivalent examples:
.nf

.ne 3
.ie t \{\
	die "Can't cd to spool: $!\en" unless chdir \'/usr/spool/news\';
'br\}
.el \{\
	die "Can't cd to spool: $!\en"
		unless chdir \'/usr/spool/news\';
'br\}

	chdir \'/usr/spool/news\' || die "Can't cd to spool: $!\en" 

.fi
.Sp
If the value of EXPR does not end in a newline, the current script line
number and input line number (if any) are also printed, and a newline is
supplied.
Hint: sometimes appending \*(L", stopped\*(R" to your message will cause it to make
better sense when the string \*(L"at foo line 123\*(R" is appended.
Suppose you are running script \*(L"canasta\*(R".
.nf

.ne 7
	die "/etc/games is no good";
	die "/etc/games is no good, stopped";

produce, respectively

	/etc/games is no good at canasta line 123.
	/etc/games is no good, stopped at canasta line 123.

.fi
See also
.IR exit .
.Ip "do BLOCK" 8 4
Returns the value of the last command in the sequence of commands indicated
by BLOCK.
When modified by a loop modifier, executes the BLOCK once before testing the
loop condition.
(On other statements the loop modifiers test the conditional first.)
.Ip "do SUBROUTINE (LIST)" 8 3
Executes a SUBROUTINE declared by a
.I sub
declaration, and returns the value
of the last expression evaluated in SUBROUTINE.
If there is no subroutine by that name, produces a fatal error.
(You may use the \*(L"defined\*(R" operator to determine if a subroutine
exists.)
If you pass arrays as part of LIST you may wish to pass the length
of the array in front of each array.
(See the section on subroutines later on.)
The parentheses are required to avoid confusion with the \*(L"do EXPR\*(R"
form.
.Sp
SUBROUTINE may also be a single scalar variable, in which case
the name of the subroutine to execute is taken from the variable.
.Sp
As an alternate (and preferred) form,
you may call a subroutine by prefixing the name with
an ampersand: &foo(@args).
If you aren't passing any arguments, you don't have to use parentheses.
If you omit the parentheses, no @_ array is passed to the subroutine.
The & form is also used to specify subroutines to the defined and undef
operators:
.nf

	if (defined &$var) { &$var($parm); undef &$var; }

.fi
.Ip "do EXPR" 8 3
Uses the value of EXPR as a filename and executes the contents of the file
as a
.I perl
script.
Its primary use is to include subroutines from a
.I perl
subroutine library.
.nf

	do \'stat.pl\';

is just like

	eval \`cat stat.pl\`;

.fi
except that it's more efficient, more concise, keeps track of the current
filename for error messages, and searches all the
.B \-I
libraries if the file
isn't in the current directory (see also the @INC array in Predefined Names).
It's the same, however, in that it does reparse the file every time you
call it, so if you are going to use the file inside a loop you might prefer
to use \-P and #include, at the expense of a little more startup time.
(The main problem with #include is that cpp doesn't grok # comments\*(--a
workaround is to use \*(L";#\*(R" for standalone comments.)
Note that the following are NOT equivalent:
.nf

.ne 2
	do $foo;	# eval a file
	do $foo();	# call a subroutine

.fi
Note that inclusion of library routines is better done with
the \*(L"require\*(R" operator.
.Ip "dump LABEL" 8 6
This causes an immediate core dump.
Primarily this is so that you can use the undump program to turn your
core dump into an executable binary after having initialized all your
variables at the beginning of the program.
When the new binary is executed it will begin by executing a "goto LABEL"
(with all the restrictions that goto suffers).
Think of it as a goto with an intervening core dump and reincarnation.
If LABEL is omitted, restarts the program from the top.
WARNING: any files opened at the time of the dump will NOT be open any more
when the program is reincarnated, with possible resulting confusion on the pa