table of contents
other languages
PERLFUNC(7) | Perl Programmers Reference Guide | PERLFUNC(7) |
NAME¶
perlfunc - Perl 内部函数描述 DESCRIPTION¶
这一章里的函数可以作为表达式来使用。 Perl 中的函数主要分为两类:数组运算符和命名的一元运算符。 不同之处在于他们的优先级关系。(参阅 perlop 中的优先级表 ) 数组运算符需要一个以上的参数,而一元运算符不能超过一个参数。 因此,一个逗号将结束一个一元运算符, 但对于数组运算符,只是起到分隔的作用。 一元运算符一般只提供一个标量作为参数,而数组运算符可能会提供标量或者数组作为参数。 如果二者都有,标量参数一般在前面,数组参数跟在后面。 (注意,可以只有一个数组变量) 例如, splice() 有三个标量变量,后面加上一个数组, 相反 gethostbyname() 有四个标量变量。 在语法描述中,数组运算符需要一个用LIST标识的数组作为参数。 这些 数组可能由标量参数和数组值混合组成; 数组值将包含在数组中,每个元素被插入数组中, 形成一个更长一维的数组值。 数组的元素应该用逗号分开。 下面列出的任何函数可以在参数两边有括号,也可以没有。(语法描述中省略括号) 如果你使用括号,一个简单的规则是 (偶尔会令人吃惊): 如果是函数,没有优先级的问题;如果它是一个数组运算符或者一元运算符 那么就要考虑优先级。并且,函数两边的空白和 "(" 是不计算的--因此, 有时候需要小心行事。看看下面的几个例子:print 1+2+4; # Prints 7. print(1+2) + 4; # Prints 3. print (1+2)+4; # Also prints 3! print +(1+2)+4; # Prints 7. print ((1+2)+4); # Prints 7.前面说得似乎有点抽象,那么你在运行PERL时带上-w开关你将得到一些 警告信息,您可以根据这些信息再体会一下。例如,上面的例子会产生如下信息:
print (...) interpreted as function at - line 1. Useless use of integer addition in void context at - line 1.有些函数根本不需要参数,因此工作方式和一元运算符和数组运算符都不同, "time" 和 "endpwent" 算是两个典型吧. 如, "time+86_400" 实际上是 "time() + 86_400". 对于可以用在标量或者数组的上下文中的函数,非失败性的错误在标量环境下 通常暗示返回了未定义的值或在数组环境下返回一个空的数组。 记住下面的重要原则: 没有规则和数组环境下的表达式的行为和他的标量环境的行为有关系,反之亦然。 这可能产生两种完全不同的情况。在标量环境下,每个运算符和函数决定怎样以最恰当的次序返回值。 有些运算符在数组环境下返回数组的长度.,有些运算符返回的一个元素,有些返回数组中的最后一个元素,有些返回成功执行的操作的语句数。通常,他们返回一些你需要的值,除非你需要连续性。 在标量环境下的命名数组在第一眼看上去时和在标量环境下的列表有很大的不同。 在标量环境下,你不能得到一个像 "(1,2,3)" 的列表,因为在编译时,编译器是知道当前环境的,它将在那里产生标量的逗号运算符, 而不是用于分隔数组元素的逗号. 也就是说,它永远不会以一个数组开始。 一般说来, PERL中的函数对应相应的系统调用 (如 chown(2), fork(2), closedir(2), 等等.) 成功调用后返回真值,否则返回 "undef" , 下面将会提到。这一点和C的接口不一样,C中出错时将返回"-1" .但是也有几个例外,他们是 "wait", "waitpid", 和 "syscall" 。 系统调用出错时出错信息将通过特殊变量$!返回。其他的函数则不会,除非发生意外。
- 标量和字符串函数 Functions for SCALARs or strings
- "chomp", "chop", "chr", "crypt", "hex", "index", "lc", "lcfirst", "length", "oct", "ord", "pack", "q/STRING/", "qq/STRING/", "reverse", "rindex", "sprintf", "substr", "tr///", "uc", "ucfirst", "y///"
- 正则表达式和模式匹配 Regular expressions and pattern matching
- "m//", "pos", "quotemeta", "s///", "split", "study", "qr//"
- 数字运算 Numeric functions
- "abs", "atan2", "cos", "exp", "hex", "int", "log", "oct", "rand", "sin", "sqrt", "srand"
- 真实数组函数 Functions for real @ARRAYs
- "pop", "push", "shift", "splice", "unshift"
- 列表数据函数 Functions for list data
- "grep", "join", "map", "qw/STRING/", "reverse", "sort", "unpack"
- 真实哈希函数 Functions for real %HASHes
- "delete", "each", "exists", "keys", "values"
- 输入输出 Input and output functions
- "binmode", "close", "closedir", "dbmclose", "dbmopen", "die", "eof", "fileno", "flock", "format", "getc", "print", "printf", "read", "readdir", "rewinddir", "seek", "seekdir", "select", "syscall", "sysread", "sysseek", "syswrite", "tell", "telldir", "truncate", "warn", "write"
- 定长的数据或记录 Functions for fixed length data or records
- "pack", "read", "syscall", "sysread", "syswrite", "unpack", "vec"
- 文件目录控制 Functions for filehandles, files, or directories
- "-X", "chdir", "chmod", "chown", "chroot", "fcntl", "glob", "ioctl", "link", "lstat", "mkdir", "open", "opendir", "readlink", "rename", "rmdir", "stat", "symlink", "sysopen", "umask", "unlink", "utime"
- 流控制关键词 Keywords related to the control flow of your perl program
- "caller", "continue", "die", "do", "dump", "eval", "exit", "goto", "last", "next", "redo", "return", "sub", "wantarray"
- 作用域关键词 Keywords related to scoping
- "caller", "import", "local", "my", "our", "package", "use"
- 杂项 Miscellaneous functions
- "defined", "dump", "eval", "formline", "local", "my", "our", "reset", "scalar", "undef", "wantarray"
- 进程和进程组 Functions for processes and process groups
- "alarm", "exec", "fork", "getpgrp", "getppid", "getpriority", "kill", "pipe", "qx/STRING/", "setpgrp", "setpriority", "sleep", "system", "times", "wait", "waitpid"
- 模块关键词 Keywords related to perl modules
- "do", "import", "no", "package", "require", "use"
- 类和面向对象关键词 Keywords related to classes and object-orientedness
- "bless", "dbmclose", "dbmopen", "package", "ref", "tie", "tied", "untie", "use"
- 底层 socket 函数 Low-level socket functions
- "accept", "bind", "connect", "getpeername", "getsockname", "getsockopt", "listen", "recv", "send", "setsockopt", "shutdown", "socket", "socketpair"
- SysV 进程间通讯 System V interprocess communication functions
- "msgctl", "msgget", "msgrcv", "msgsnd", "semctl", "semget", "semop", "shmctl", "shmget", "shmread", "shmwrite"
- 获取用户信息 Fetching user and group info
- "endgrent", "endhostent", "endnetent", "endpwent", "getgrent", "getgrgid", "getgrnam", "getlogin", "getpwent", "getpwnam", "getpwuid", "setgrent", "setpwent"
- 获取网络信息 Fetching network info
- "endprotoent", "endservent", "gethostbyaddr", "gethostbyname", "gethostent", "getnetbyaddr", "getnetbyname", "getnetent", "getprotobyname", "getprotobynumber", "getprotoent", "getservbyname", "getservbyport", "getservent", "sethostent", "setnetent", "setprotoent", "setservent"
- 时间函数 Time-related functions
- "gmtime", "localtime", "time", "times"
- PERL5中的新函数 Functions new in perl5
- "abs", "bless", "chomp",
"chr", "exists", "formline",
"glob", "import", "lc", "lcfirst",
"map", "my", "no", "our",
"prototype", "qx", "qw",
"readline", "readpipe", "ref",
"sub*", "sysopen", "tie", "tied",
"uc", "ucfirst", "untie", "use"
- 过时的函数 Functions obsoleted in perl5
- "dbmclose", "dbmopen"
- -X FILEHANDLE
- -X EXPR
- -X
- A file test, where X is one of the letters listed below.
This unary operator takes one argument, either a filename or a filehandle,
and tests the associated file to see if something is true about it. If the
argument is omitted, tests $_, except for "-t", which tests
STDIN. Unless otherwise documented, it returns 1 for true and '' for
false, or the undefined value if the file doesn't exist. Despite the funny
names, precedence is the same as any other named unary operator, and the
argument may be parenthesized like any other unary operator. The operator
may be any of:
-r File is readable by effective uid/gid. -w File is writable by effective uid/gid. -x File is executable by effective uid/gid. -o File is owned by effective uid.
-R File is readable by real uid/gid. -W File is writable by real uid/gid. -X File is executable by real uid/gid. -O File is owned by real uid.
-e File exists. -z File has zero size (is empty). -s File has nonzero size (returns size in bytes).
-f File is a plain file. -d File is a directory. -l File is a symbolic link. -p File is a named pipe (FIFO), or Filehandle is a pipe. -S File is a socket. -b File is a block special file. -c File is a character special file. -t Filehandle is opened to a tty.
-u File has setuid bit set. -g File has setgid bit set. -k File has sticky bit set.
-T File is an ASCII text file (heuristic guess). -B File is a "binary" file (opposite of -T).
-M Script start time minus file modification time, in days. -A Same for access time. -C Same for inode change time (Unix, may differ for other platforms)
while (<>) { chomp; next unless -f $_; # ignore specials #... }
print "Can do.\n" if -r $a ⎪⎪ -w _ ⎪⎪ -x _;
stat($filename); print "Readable\n" if -r _; print "Writable\n" if -w _; print "Executable\n" if -x _; print "Setuid\n" if -u _; print "Setgid\n" if -g _; print "Sticky\n" if -k _; print "Text\n" if -T _; print "Binary\n" if -B _;
- abs VALUE
- abs
- Returns the absolute value of its argument. If VALUE is omitted, uses $_.
- accept NEWSOCKET,GENERICSOCKET
- Accepts an incoming socket connect, just as the
accept(2) system call does. Returns the packed address if it
succeeded, false otherwise. See the example in "Sockets:
Client/Server Communication" in perlipc.
- alarm SECONDS
- alarm
- Arranges to have a SIGALRM delivered to this process after
the specified number of wallclock seconds have elapsed. If SECONDS is not
specified, the value stored in $_ is used. (On some machines,
unfortunately, the elapsed time may be up to one second less or more than
you specified because of how seconds are counted, and process scheduling
may delay the delivery of the signal even further.)
eval { local $SIG{ALRM} = sub { die "alarm\n" }; # NB: \n required alarm $timeout; $nread = sysread SOCKET, $buffer, $size; alarm 0; }; if ($@) { die unless $@ eq "alarm\n"; # propagate unexpected errors # timed out } else { # didn't }
- atan2 Y,X
- Returns the arctangent of Y/X in the range -PI to PI.
sub tan { sin($_[0]) / cos($_[0]) }
- bind SOCKET,NAME
- Binds a network address to a socket, just as the bind system call does. Returns true if it succeeded, false otherwise. NAME should be a packed address of the appropriate type for the socket. See the examples in "Sockets: Client/Server Communication" in perlipc.
- binmode FILEHANDLE, LAYER
- binmode FILEHANDLE
- Arranges for FILEHANDLE to be read or written in
"binary" or "text" mode on systems where the run-time
libraries distinguish between binary and text files. If FILEHANDLE is an
expression, the value is taken as the name of the filehandle. Returns true
on success, otherwise it returns "undef" and sets $! (errno).
- bless REF,CLASSNAME
- bless REF
- This function tells the thingy referenced by REF that it is
now an object in the CLASSNAME package. If CLASSNAME is omitted, the
current package is used. Because a "bless" is often the last
thing in a constructor, it returns the reference for convenience. Always
use the two-argument version if the function doing the blessing might be
inherited by a derived class. See perltoot and perlobj for more about the
blessing (and blessings) of objects.
- caller EXPR
- caller
- Returns the context of the current subroutine call. In
scalar context, returns the caller's package name if there is a caller,
that is, if we're in a subroutine or "eval" or
"require", and the undefined value otherwise. In list context,
returns
($package, $filename, $line) = caller;
($package, $filename, $line, $subroutine, $hasargs, $wantarray, $evaltext, $is_require, $hints, $bitmask) = caller($i);
- chdir EXPR
- Changes the working directory to EXPR, if possible. If EXPR is omitted, changes to the directory specified by $ENV{HOME}, if set; if not, changes to the directory specified by $ENV{LOGDIR}. (Under VMS, the variable $ENV{SYS$LOGIN} is also checked, and used if it is set.) If neither is set, "chdir" does nothing. It returns true upon success, false otherwise. See the example under "die".
- chmod LIST
- Changes the permissions of a list of files. The first
element of the list must be the numerical mode, which should probably be
an octal number, and which definitely should not a string of octal
digits: 0644 is okay, '0644' is not. Returns the number of files
successfully changed. See also "oct", if all you have is a
string.
$cnt = chmod 0755, 'foo', 'bar'; chmod 0755, @executables; $mode = '0644'; chmod $mode, 'foo'; # !!! sets mode to # --w----r-T $mode = '0644'; chmod oct($mode), 'foo'; # this is better $mode = 0644; chmod $mode, 'foo'; # this is best
use Fcntl ':mode';
chmod S_IRWXU⎪S_IRGRP⎪S_IXGRP⎪S_IROTH⎪S_IXOTH, @executables; # This is identical to the chmod 0755 of the above example.
- chomp VARIABLE
- chomp( LIST )
- chomp
- This safer version of "chop" removes any trailing
string that corresponds to the current value of $/ (also known as
$INPUT_RECORD_SEPARATOR in the "English" module). It returns the
total number of characters removed from all its arguments. It's often used
to remove the newline from the end of an input record when you're worried
that the final record may be missing its newline. When in paragraph mode
("$/ = """), it removes all trailing newlines from the
string. When in slurp mode ("$/ = undef") or fixed-length record
mode ($/ is a reference to an integer or the like, see perlvar)
chomp() won't remove anything. If VARIABLE is omitted, it chomps
$_. Example:
while (<>) { chomp; # avoid \n on last field @array = split(/:/); # ... }
chomp($cwd = `pwd`); chomp($answer = <STDIN>);
- chop VARIABLE
- chop( LIST )
- chop
- Chops off the last character of a string and returns the
character chopped. It is much more efficient than "s/.$//s"
because it neither scans nor copies the string. If VARIABLE is omitted,
chops $_. If VARIABLE is a hash, it chops the hash's values, but not its
keys.
- chown LIST
- Changes the owner (and group) of a list of files. The first
two elements of the list must be the numeric uid and gid, in that
order. A value of -1 in either position is interpreted by most systems to
leave that value unchanged. Returns the number of files successfully
changed.
$cnt = chown $uid, $gid, 'foo', 'bar'; chown $uid, $gid, @filenames;
print "User: "; chomp($user = <STDIN>); print "Files: "; chomp($pattern = <STDIN>);
($login,$pass,$uid,$gid) = getpwnam($user) or die "$user not in passwd file";
@ary = glob($pattern); # expand filenames chown $uid, $gid, @ary;
use POSIX qw(sysconf _PC_CHOWN_RESTRICTED); $can_chown_giveaway = not sysconf(_PC_CHOWN_RESTRICTED);
- chr NUMBER
- chr
- Returns the character represented by that NUMBER in the
character set. For example, "chr(65)" is "A" in either
ASCII or Unicode, and chr(0x263a) is a Unicode smiley face. Note that
characters from 128 to 255 (inclusive) are by default not encoded in UTF-8
Unicode for backward compatibility reasons (but see encoding).
- chroot FILENAME
- chroot
- This function works like the system call by the same name: it makes the named directory the new root directory for all further pathnames that begin with a "/" by your process and all its children. (It doesn't change your current working directory, which is unaffected.) For security reasons, this call is restricted to the superuser. If FILENAME is omitted, does a "chroot" to $_.
- close FILEHANDLE
- close
- Closes the file or pipe associated with the file handle,
returning true only if IO buffers are successfully flushed and closes the
system file descriptor. Closes the currently selected filehandle if the
argument is omitted.
open(OUTPUT, '⎪sort >foo') # pipe to sort or die "Can't start sort: $!"; #... # print stuff to output close OUTPUT # wait for sort to finish or warn $! ? "Error closing sort pipe: $!" : "Exit status $? from sort"; open(INPUT, 'foo') # get sort's results or die "Can't open 'foo' for input: $!";
- closedir DIRHANDLE
- Closes a directory opened by "opendir" and returns the success of that system call.
- connect SOCKET,NAME
- Attempts to connect to a remote socket, just as the connect system call does. Returns true if it succeeded, false otherwise. NAME should be a packed address of the appropriate type for the socket. See the examples in "Sockets: Client/Server Communication" in perlipc.
- continue BLOCK
- Actually a flow control statement rather than a function.
If there is a "continue" BLOCK attached to a BLOCK (typically in
a "while" or "foreach"), it is always executed just
before the conditional is about to be evaluated again, just like the third
part of a "for" loop in C. Thus it can be used to increment a
loop variable, even when the loop has been continued via the
"next" statement (which is similar to the C "continue"
statement).
while (EXPR) { ### redo always comes here do_something; } continue { ### next always comes here do_something_else; # then back the top to re-check EXPR } ### last always comes here
- cos EXPR
- cos
- Returns the cosine of EXPR (expressed in radians). If EXPR
is omitted, takes cosine of $_.
sub acos { atan2( sqrt(1 - $_[0] * $_[0]), $_[0] ) }
- crypt PLAINTEXT,SALT
- Encrypts a string exactly like the crypt(3) function
in the C library (assuming that you actually have a version there that has
not been extirpated as a potential munition). This can prove useful for
checking the password file for lousy passwords, amongst other things. Only
the guys wearing white hats should do this.
$pwd = (getpwuid($<))[1];
system "stty -echo"; print "Password: "; chomp($word = <STDIN>); print "\n"; system "stty echo";
if (crypt($word, $pwd) ne $pwd) { die "Sorry...\n"; } else { print "ok\n"; }
- dbmclose HASH
- [This function has been largely superseded by the
"untie" function.]
- dbmopen HASH,DBNAME,MASK
- [This function has been largely superseded by the
"tie" function.]
# 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);
use DB_File; dbmopen(%NS_Hist, "$ENV{HOME}/.netscape/history.db") or die "Can't open netscape history file: $!";
- defined EXPR
- defined
- Returns a Boolean value telling whether EXPR has a value
other than the undefined value "undef". If EXPR is not present,
$_ will be checked.
if (@an_array) { print "has array elements\n" } if (%a_hash) { print "has hash members\n" }
print if defined $switch{'D'}; print "$val\n" while defined($val = pop(@ary)); die "Can't readlink $sym: $!" unless defined($value = readlink $sym); sub foo { defined &$bar ? &$bar(@_) : die "No bar"; } $debugging = 0 unless defined $debugging;
"ab" =~ /a(.*)b/;
- delete EXPR
- Given an expression that specifies a hash element, array
element, hash slice, or array slice, deletes the specified element(s) from
the hash or array. In the case of an array, if the array elements happen
to be at the end, the size of the array will shrink to the highest element
that tests true for exists() (or 0 if no such element exists).
foreach $key (keys %HASH) { delete $HASH{$key}; }
foreach $index (0 .. $#ARRAY) { delete $ARRAY[$index]; }
delete @HASH{keys %HASH};
delete @ARRAY[0 .. $#ARRAY];
%HASH = (); # completely empty %HASH undef %HASH; # forget %HASH ever existed
@ARRAY = (); # completely empty @ARRAY undef @ARRAY; # forget @ARRAY ever existed
delete $ref->[$x][$y]{$key}; delete @{$ref->[$x][$y]}{$key1, $key2, @morekeys};
delete $ref->[$x][$y][$index]; delete @{$ref->[$x][$y]}[$index1, $index2, @moreindices];
- die LIST
- Outside an "eval", prints the value of LIST to
"STDERR" and exits with the current value of $! (errno). If $!
is 0, exits with the value of "($? >> 8)" (backtick
`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. This makes
"die" the way to raise an exception.
die "Can't cd to spool: $!\n" unless chdir '/usr/spool/news'; chdir '/usr/spool/news' or die "Can't cd to spool: $!\n"
die "/etc/games is no good"; die "/etc/games is no good, stopped";
/etc/games is no good at canasta line 123. /etc/games is no good, stopped at canasta line 123.
eval { ... }; die unless $@ =~ /Expected exception/;
eval { ... ; die Some::Module::Exception->new( FOO => "bar" ) }; if ($@) { if (ref($@) && UNIVERSAL::isa($@,"Some::Module::Exception")) { # handle Some::Module::Exception } else { # handle all other possible exceptions } }
die @_ if $^S;
- do BLOCK
- Not really a function. 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.)
- do SUBROUTINE(LIST)
- A deprecated form of subroutine call. See perlsub.
- do EXPR
- Uses the value of EXPR as a filename and executes the
contents of the file as a Perl script. Its primary use is to include
subroutines from a Perl subroutine library.
do 'stat.pl';
eval `cat stat.pl`;
# read in config files: system first, then user for $file ("/share/prog/defaults.rc", "$ENV{HOME}/.someprogrc") { unless ($return = do $file) { warn "couldn't parse $file: $@" if $@; warn "couldn't do $file: $!" unless defined $return; warn "couldn't run $file" unless $return; } }
- dump LABEL
- dump
- This function causes an immediate core dump. See also the
-u command-line switch in perlrun, which does the same thing.
Primarily this is so that you can use the undump program (not
supplied) 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.
- each HASH
- When called in list context, returns a 2-element list
consisting of the key and value for the next element of a hash, so that
you can iterate over it. When called in scalar context, returns only the
key for the next element in the hash.
while (($key, $value) = each %hash) { print $key, "\n"; delete $hash{$key}; # This is safe }
while (($key,$value) = each %ENV) { print "$key=$value\n"; }
- 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. (Note that this function actually reads a
character and then "ungetc"s it, so isn't very useful in an
interactive context.) Do not read from a terminal file (or call
"eof(FILEHANDLE)" on it) after end-of-file is reached. File
types such as terminals may lose the end-of-file condition if you do.
# reset line numbering on each input file while (<>) { next if /^\s*#/; # skip comments print "$.\t$_"; } continue { close ARGV if eof; # Not eof()! }
# insert dashes just before last line of last file while (<>) { if (eof()) { # check for end of last file print "--------------\n"; } print; last if eof(); # needed if we're reading from a terminal }
- eval EXPR
- eval BLOCK
- In the first form, the return value of EXPR is parsed and
executed as if it were a little Perl program. The value of the expression
(which is itself determined within scalar context) is first parsed, and if
there weren't any errors, executed in the lexical context of the current
Perl program, so that any variable settings or subroutine and format
definitions remain afterwards. Note that the value is parsed every time
the eval executes. If EXPR is omitted, evaluates $_. This form is
typically used to delay parsing and subsequent execution of the text of
EXPR until run time.
# make divide-by-zero nonfatal eval { $answer = $a / $b; }; warn $@ if $@;
# same thing, but less efficient eval '$answer = $a / $b'; warn $@ if $@;
# a compile-time error eval { $answer = }; # WRONG
# a run-time error eval '$answer ='; # sets $@
# a very private exception trap for divide-by-zero eval { local $SIG{'__DIE__'}; $answer = $a / $b; }; warn $@ if $@;
# __DIE__ hooks may modify error messages { local $SIG{'__DIE__'} = sub { (my $x = $_[0]) =~ s/foo/bar/g; die $x }; eval { die "foo lives here" }; print $@ if $@; # prints "bar lives here" }
eval $x; # CASE 1 eval "$x"; # CASE 2
eval '$x'; # CASE 3 eval { $x }; # CASE 4
eval "\$$x++"; # CASE 5 $$x++; # CASE 6
- exec LIST
- exec PROGRAM LIST
- The "exec" function executes a system command
and never returns-- use "system" instead of
"exec" if you want it to return. It fails and returns false only
if the command does not exist and it is executed directly instead
of via your system's command shell (see below).
exec ('foo') or print STDERR "couldn't exec foo: $!"; { exec ('foo') }; print STDERR "couldn't exec foo: $!";
exec '/bin/echo', 'Your arguments are: ', @ARGV; exec "sort $outfile ⎪ uniq";
$shell = '/bin/csh'; exec $shell '-sh'; # pretend it's a login shell
exec {'/bin/csh'} '-sh'; # pretend it's a login shell
@args = ( "echo surprise" );
exec @args; # subject to shell escapes # if @args == 1 exec { $args[0] } @args; # safe even with one-arg list
- exists EXPR
- Given an expression that specifies a hash element or array
element, returns true if the specified element in the hash or array has
ever been initialized, even if the corresponding value is undefined. The
element is not autovivified if it doesn't exist.
print "Exists\n" if exists $hash{$key}; print "Defined\n" if defined $hash{$key}; print "True\n" if $hash{$key};
print "Exists\n" if exists $array[$index]; print "Defined\n" if defined $array[$index]; print "True\n" if $array[$index];
print "Exists\n" if exists &subroutine; print "Defined\n" if defined &subroutine;
if (exists $ref->{A}->{B}->{$key}) { } if (exists $hash{A}{B}{$key}) { }
if (exists $ref->{A}->{B}->[$ix]) { } if (exists $hash{A}{B}[$ix]) { }
if (exists &{$ref->{A}{B}{$key}}) { }
undef $ref; if (exists $ref->{"Some key"}) { } print $ref; # prints HASH(0x80d3d5c)
exists ⊂ # OK exists &sub(); # Error
- exit EXPR
- Evaluates EXPR and exits immediately with that value.
Example:
$ans = <STDIN>; exit 0 if $ans =~ /^[Xx]/;
- exp EXPR
- exp
- Returns e (the natural logarithm base) to the power of EXPR. If EXPR is omitted, gives "exp($_)".
- fcntl FILEHANDLE,FUNCTION,SCALAR
- Implements the fcntl(2) function. You'll probably
have to say
use Fcntl;
use Fcntl; fcntl($filehandle, F_GETFL, $packed_return_buffer) or die "can't fcntl F_GETFL: $!";
- fileno FILEHANDLE
- Returns the file descriptor for a filehandle, or undefined
if the filehandle is not open. This is mainly useful for constructing
bitmaps for "select" and low-level POSIX tty-handling
operations. If FILEHANDLE is an expression, the value is taken as an
indirect filehandle, generally its name.
if (fileno(THIS) == fileno(THAT)) { print "THIS and THAT are dups\n"; }
- flock FILEHANDLE,OPERATION
- Calls flock(2), or an emulation of it, on
FILEHANDLE. Returns true for success, false on failure. Produces a fatal
error if used on a machine that doesn't implement flock(2),
fcntl(2) locking, or lockf(3). "flock" is Perl's
portable file locking interface, although it locks only entire files, not
records.
use Fcntl ':flock'; # import LOCK_* constants
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'}") or die "Can't open mailbox: $!";
lock(); print MBOX $msg,"\n\n"; unlock();
- fork
- Does a fork(2) system call to create a new process
running the same program at the same point. It returns the child pid to
the parent process, 0 to the child process, or "undef" if the
fork is unsuccessful. File descriptors (and sometimes locks on those
descriptors) are shared, while everything else is copied. On most systems
supporting fork(), great care has gone into making it extremely
efficient (for example, using copy-on-write technology on data pages),
making it the dominant paradigm for multitasking over the last few
decades.
- format
- Declare a picture format for use by the "write"
function. For example:
format Something = Test: @<<<<<<<< @⎪⎪⎪⎪⎪ @>>>>> $str, $%, '$' . int($num) .
$str = "widget"; $num = $cost/$quantity; $~ = 'Something'; write;
- formline PICTURE,LIST
- This is an internal function used by "format"s,
though you may call it, too. It formats (see perlform) a list of values
according to the contents of PICTURE, placing the output into the format
output accumulator, $^A (or $ACCUMULATOR in English). Eventually, when a
"write" is done, the contents of $^A are written to some
filehandle, but you could also read $^A yourself and then set $^A back to
"". Note that a format typically does one "formline"
per line of form, but the "formline" function itself doesn't
care how many newlines are embedded in the PICTURE. This means that the
"~" and "~~" tokens will treat the entire PICTURE as a
single line. You may therefore need to use multiple formlines to implement
a single record format, just like the format compiler.
- getc FILEHANDLE
- getc
- Returns the next character from the input file attached to
FILEHANDLE, or the undefined value at end of file, or if there was an
error (in the latter case $! is set). If FILEHANDLE is omitted, reads from
STDIN. This is not particularly efficient. However, it cannot be used by
itself to fetch single characters without waiting for the user to hit
enter. For that, try something more like:
if ($BSD_STYLE) { system "stty cbreak </dev/tty >/dev/tty 2>&1"; } else { system "stty", '-icanon', 'eol', "\001"; }
$key = getc(STDIN);
if ($BSD_STYLE) { system "stty -cbreak </dev/tty >/dev/tty 2>&1"; } else { system "stty", 'icanon', 'eol', '^@'; # ASCII null } print "\n";
- getlogin
- Implements the C library function of the same name, which
on most systems returns the current login from /etc/utmp, if any.
If null, use "getpwuid".
$login = getlogin ⎪⎪ getpwuid($<) ⎪⎪ "Kilroy";
- getpeername SOCKET
- Returns the packed sockaddr address of other end of the
SOCKET connection.
use Socket; $hersockaddr = getpeername(SOCK); ($port, $iaddr) = sockaddr_in($hersockaddr); $herhostname = gethostbyaddr($iaddr, AF_INET); $herstraddr = inet_ntoa($iaddr);
- getpgrp PID
- Returns the current process group for the specified PID. Use a PID of 0 to get the current process group for the current process. Will raise an exception if used on a machine that doesn't implement getpgrp(2). If PID is omitted, returns process group of current process. Note that the POSIX version of "getpgrp" does not accept a PID argument, so only "PID==0" is truly portable.
- getppid
- Returns the process id of the parent process.
- getpriority WHICH,WHO
- Returns the current priority for a process, a process group, or a user. (See getpriority(2).) Will raise a fatal exception if used on a machine that doesn't implement getpriority(2).
- getpwnam NAME
- getgrnam NAME
- gethostbyname NAME
- getnetbyname NAME
- getprotobyname NAME
- getpwuid UID
- getgrgid GID
- getservbyname NAME,PROTO
- gethostbyaddr ADDR,ADDRTYPE
- getnetbyaddr ADDR,ADDRTYPE
- getprotobynumber NUMBER
- getservbyport PORT,PROTO
- getpwent
- getgrent
- gethostent
- getnetent
- getprotoent
- getservent
- setpwent
- setgrent
- sethostent STAYOPEN
- setnetent STAYOPEN
- setprotoent STAYOPEN
- setservent STAYOPEN
- endpwent
- endgrent
- endhostent
- endnetent
- endprotoent
- endservent
- These routines perform the same functions as their
counterparts in the system library. In list context, the return values
from the various get routines are as follows:
($name,$passwd,$uid,$gid, $quota,$comment,$gcos,$dir,$shell,$expire) = getpw* ($name,$passwd,$gid,$members) = getgr* ($name,$aliases,$addrtype,$length,@addrs) = gethost* ($name,$aliases,$addrtype,$net) = getnet* ($name,$aliases,$proto) = getproto* ($name,$aliases,$port,$proto) = getserv*
$uid = getpwnam($name); $name = getpwuid($num); $name = getpwent(); $gid = getgrnam($name); $name = getgrgid($num); $name = getgrent(); #etc.
($a,$b,$c,$d) = unpack('C4',$addr[0]);
use Socket; $iaddr = inet_aton("127.1"); # or whatever address $name = gethostbyaddr($iaddr, AF_INET);
# or going the other way $straddr = inet_ntoa($iaddr);
use File::stat; use User::pwent; $is_his = (stat($filename)->uid == pwent($whoever)->uid);
- getsockname SOCKET
- Returns the packed sockaddr address of this end of the
SOCKET connection, in case you don't know the address because you have
several different IPs that the connection might have come in on.
use Socket; $mysockaddr = getsockname(SOCK); ($port, $myaddr) = sockaddr_in($mysockaddr); printf "Connect to %s [%s]\n", scalar gethostbyaddr($myaddr, AF_INET), inet_ntoa($myaddr);
- getsockopt SOCKET,LEVEL,OPTNAME
- Returns the socket option requested, or undef if there is an error.
- glob EXPR
- glob
- In list context, returns a (possibly empty) list of
filename expansions on the value of EXPR such as the standard Unix shell
/bin/csh would do. In scalar context, glob iterates through such
filename expansions, returning undef when the list is exhausted. This is
the internal function implementing the "<*.c>" operator,
but you can use it directly. If EXPR is omitted, $_ is used. The
"<*.c>" operator is discussed in more detail in "I/O
Operators" in perlop.
- gmtime EXPR
- Converts a time as returned by the time function to an
8-element list with the time localized for the standard Greenwich time
zone. Typically used as follows:
# 0 1 2 3 4 5 6 7 ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday) = gmtime(time);
$year += 1900;
$year = sprintf("%02d", $year % 100);
$now_string = gmtime; # e.g., "Thu Oct 13 04:54:34 1994"
use POSIX qw(strftime); $now_string = strftime "%a %b %e %H:%M:%S %Y", gmtime;
- goto LABEL
- goto EXPR
- goto &NAME
- The "goto-LABEL" form finds the statement labeled
with LABEL and resumes execution there. It may not be used to go into any
construct that requires initialization, such as a subroutine or a
"foreach" loop. It also can't be used to go into a construct
that is optimized away, or to get out of a block or subroutine given to
"sort". It can be used to go almost anywhere else within the
dynamic scope, including out of subroutines, but it's usually better to
use some other construct such as "last" or "die". The
author of Perl has never felt the need to use this form of
"goto" (in Perl, that is--C is another matter). (The difference
being that C does not offer named loops combined with loop control. Perl
does, and this replaces most structured uses of "goto" in other
languages.)
goto ("FOO", "BAR", "GLARCH")[$i];
- grep BLOCK LIST
- grep EXPR,LIST
- This is similar in spirit to, but not the same as,
grep(1) and its relatives. In particular, it is not limited to
using regular expressions.
@foo = grep(!/^#/, @bar); # weed out comments
@foo = grep {!/^#/} @bar; # weed out comments
- hex EXPR
- hex
- Interprets EXPR as a hex string and returns the
corresponding value. (To convert strings that might start with either 0,
0x, or 0b, see "oct".) If EXPR is omitted, uses $_.
print hex '0xAf'; # prints '175' print hex 'aF'; # same
- import
- There is no builtin "import" function. It is just an ordinary method (subroutine) defined (or inherited) by modules that wish to export names to another module. The "use" function calls the "import" method for the package used. See also "use", perlmod, and Exporter.
- index STR,SUBSTR,POSITION
- index STR,SUBSTR
- The index function searches for one string within another, but without the wildcard-like behavior of a full regular-expression pattern match. It returns the position of the first occurrence of SUBSTR in STR at or after POSITION. If POSITION is omitted, starts searching from the beginning of the string. The return value is based at 0 (or whatever you've set the $[ variable to--but don't do that). If the substring is not found, returns one less than the base, ordinarily "-1".
- int EXPR
- int
- Returns the integer portion of EXPR. If EXPR is omitted, uses $_. You should not use this function for rounding: one because it truncates towards 0, and two because machine representations of floating point numbers can sometimes produce counterintuitive results. For example, "int(-6.725/0.025)" produces -268 rather than the correct -269; that's because it's really more like -268.99999999999994315658 instead. Usually, the "sprintf", "printf", or the "POSIX::floor" and "POSIX::ceil" functions will serve you better than will int().
- ioctl FILEHANDLE,FUNCTION,SCALAR
- Implements the ioctl(2) function. You'll probably
first have to say
require "ioctl.ph"; # probably in /usr/local/lib/perl/ioctl.ph
if OS returns: then Perl returns: -1 undefined value 0 string "0 but true" anything else that number
$retval = ioctl(...) ⎪⎪ -1; printf "System returned %d\n", $retval;
use Fcntl qw(F_GETFL F_SETFL O_NONBLOCK);
$flags = fcntl(REMOTE, F_GETFL, 0) or die "Can't get flags for the socket: $!\n";
$flags = fcntl(REMOTE, F_SETFL, $flags ⎪ O_NONBLOCK) or die "Can't set flags for the socket: $!\n";
- join EXPR,LIST
- Joins the separate strings of LIST into a single string
with fields separated by the value of EXPR, and returns that new string.
Example:
$rec = join(':', $login,$passwd,$uid,$gid,$gcos,$home,$shell);
- keys HASH
- Returns a list consisting of all the keys of the named
hash. (In scalar context, returns the number of keys.)
@keys = keys %ENV; @values = values %ENV; while (@keys) { print pop(@keys), '=', pop(@values), "\n"; }
foreach $key (sort(keys %ENV)) { print $key, '=', $ENV{$key}, "\n"; }
foreach $key (sort { $hash{$b} <=> $hash{$a} } keys %hash) { printf "%4d %s\n", $hash{$key}, $key; }
keys %hash = 200;
- kill SIGNAL, LIST
- Sends a signal to a list of processes. Returns the number
of processes successfully signaled (which is not necessarily the same as
the number actually killed).
$cnt = kill 1, $child1, $child2; kill 9, @goners;
- last LABEL
- last
- The "last" command is like the "break"
statement in C (as used in loops); it immediately exits the loop in
question. If the LABEL is omitted, the command refers to the innermost
enclosing loop. The "continue" block, if any, is not executed:
LINE: while (<STDIN>) { last LINE if /^$/; # exit when done with header #... }
- lc EXPR
- lc
- Returns a lowercased version of EXPR. This is the internal
function implementing the "\L" escape in double-quoted strings.
Respects current LC_CTYPE locale if "use locale" in force. See
perllocale and perlunicode for more details about locale and Unicode
support.
- lcfirst EXPR
- lcfirst
- Returns the value of EXPR with the first character
lowercased. This is the internal function implementing the "\l"
escape in double-quoted strings. Respects current LC_CTYPE locale if
"use locale" in force. See perllocale and perlunicode for more
details about locale and Unicode support.
- length EXPR
- length
- Returns the length in characters of the value of
EXPR. If EXPR is omitted, returns length of $_. Note that this cannot be
used on an entire array or hash to find out how many elements these have.
For that, use "scalar @array" and "scalar keys %hash"
respectively.
- link OLDFILE,NEWFILE
- Creates a new filename linked to the old filename. Returns true for success, false otherwise.
- listen SOCKET,QUEUESIZE
- Does the same thing that the listen system call does. Returns true if it succeeded, false otherwise. See the example in "Sockets: Client/Server Communication" in perlipc.
- local EXPR
- You really probably want to be using "my"
instead, because "local" isn't what most people think of as
"local". See "Private Variables via my()" in
perlsub for details.
- localtime EXPR
- Converts a time as returned by the time function to a
9-element list with the time analyzed for the local time zone. Typically
used as follows:
# 0 1 2 3 4 5 6 7 8 ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) = localtime(time);
$year += 1900;
$year = sprintf("%02d", $year % 100);
$now_string = localtime; # e.g., "Thu Oct 13 04:54:34 1994"
use POSIX qw(strftime); $now_string = strftime "%a %b %e %H:%M:%S %Y", localtime;
- lock THING
- This function places an advisory lock on a shared variable,
or referenced object contained in THING until the lock goes out of
scope.
- log EXPR
- log
- Returns the natural logarithm (base e) of EXPR. If
EXPR is omitted, returns log of $_. To get the log of another base, use
basic algebra: The base-N log of a number is equal to the natural log of
that number divided by the natural log of N. For example:
sub log10 { my $n = shift; return log($n)/log(10); }
- lstat EXPR
- lstat
- Does the same thing as the "stat" function
(including setting the special "_" filehandle) but stats a
symbolic link instead of the file the symbolic link points to. If symbolic
links are unimplemented on your system, a normal "stat" is done.
For much more detailed information, please see the documentation for
"stat".
- m//
- The match operator. See perlop.
- map BLOCK LIST
- map EXPR,LIST
- Evaluates the BLOCK or EXPR for each element of LIST
(locally setting $_ to each element) and returns the list value composed
of the results of each such evaluation. In scalar context, returns the
total number of elements so generated. Evaluates BLOCK or EXPR in list
context, so each element of LIST may produce zero, one, or more elements
in the returned value.
@chars = map(chr, @nums);
%hash = map { getkey($_) => $_ } @array;
%hash = (); foreach $_ (@array) { $hash{getkey($_)} = $_; }
%hash = map { "\L$_", 1 } @array # perl guesses EXPR. wrong %hash = map { +"\L$_", 1 } @array # perl guesses BLOCK. right %hash = map { ("\L$_", 1) } @array # this also works %hash = map { lc($_), 1 } @array # as does this. %hash = map +( lc($_), 1 ), @array # this is EXPR and works!
%hash = map ( lc($_), 1 ), @array # evaluates to (1, @array)
@hashes = map +{ lc($_), 1 }, @array # EXPR, so needs , at end
- mkdir FILENAME,MASK
- mkdir FILENAME
- Creates the directory specified by FILENAME, with
permissions specified by MASK (as modified by "umask"). If it
succeeds it returns true, otherwise it returns false and sets $! (errno).
If omitted, MASK defaults to 0777.
- msgctl ID,CMD,ARG
- Calls the System V IPC function msgctl(2). You'll
probably have to say
use IPC::SysV;
- msgget KEY,FLAGS
- Calls the System V IPC function msgget(2). Returns the message queue id, or the undefined value if there is an error. See also "SysV IPC" in perlipc and "IPC::SysV" and "IPC::Msg" documentation.
- msgrcv ID,VAR,SIZE,TYPE,FLAGS
- Calls the System V IPC function msgrcv to receive a message from message queue ID into variable VAR with a maximum message size of SIZE. Note that when a message is received, the message type as a native long integer will be the first thing in VAR, followed by the actual message. This packing may be opened with "unpack("l! a*")". Taints the variable. Returns true if successful, or false if there is an error. See also "SysV IPC" in perlipc, "IPC::SysV", and "IPC::SysV::Msg" documentation.
- msgsnd ID,MSG,FLAGS
- Calls the System V IPC function msgsnd to send the message MSG to the message queue ID. MSG must begin with the native long integer message type, and be followed by the length of the actual message, and finally the message itself. This kind of packing can be achieved with "pack("l! a*", $type, $message)". Returns true if successful, or false if there is an error. See also "IPC::SysV" and "IPC::SysV::Msg" documentation.
- my EXPR
- my TYPE EXPR
- my EXPR : ATTRS
- my TYPE EXPR : ATTRS
- A "my" declares the listed variables to be local
(lexically) to the enclosing block, file, or "eval". If more
than one value is listed, the list must be placed in parentheses.
- next LABEL
- next
- The "next" command is like the
"continue" statement in C; it starts the next iteration of the
loop:
LINE: while (<STDIN>) { next LINE if /^#/; # discard comments #... }
- no Module VERSION LIST
- no Module VERSION
- no Module LIST
- no Module
- See the "use" function, which "no" is the opposite of.
- oct EXPR
- oct
- Interprets EXPR as an octal string and returns the
corresponding value. (If EXPR happens to start off with "0x",
interprets it as a hex string. If EXPR starts off with "0b", it
is interpreted as a binary string. Leading whitespace is ignored in all
three cases.) The following will handle decimal, binary, octal, and hex in
the standard Perl or C notation:
$val = oct($val) if $val =~ /^0/;
$perms = (stat("filename"))[2] & 07777; $oct_perms = sprintf "%lo", $perms;
- open FILEHANDLE,EXPR
- open FILEHANDLE,MODE,EXPR
- open FILEHANDLE,MODE,EXPR,LIST
- open FILEHANDLE,MODE,REFERENCE
- open FILEHANDLE
- Opens the file whose filename is given by EXPR, and
associates it with FILEHANDLE.
open(FH, "<:utf8", "file")
open(TMP, "+>", undef) or die ...
open($fh, '>', \$variable) ⎪⎪ ..
close STDOUT; open STDOUT, '>', \$variable or die "Can't open STDOUT: $!";
$ARTICLE = 100; open ARTICLE or die "Can't find article $ARTICLE: $!\n"; while (<ARTICLE>) {...
open(LOG, '>>/usr/spool/news/twitlog'); # (log is reserved) # if the open fails, output is discarded
open(DBASE, '+<', 'dbase.mine') # open for update or die "Can't open 'dbase.mine' for update: $!";
open(DBASE, '+<dbase.mine') # ditto or die "Can't open 'dbase.mine' for update: $!";
open(ARTICLE, '-⎪', "caesar <$article") # decrypt article or die "Can't start caesar: $!";
open(ARTICLE, "caesar <$article ⎪") # ditto or die "Can't start caesar: $!";
open(EXTRACT, "⎪sort >/tmp/Tmp$$") # $$ is our process id or die "Can't start sort: $!";
# in memory files open(MEMORY,'>', \$var) or die "Can't open memory file: $!"; print MEMORY "foo!\n"; # output will end up in $var
# process argument list of files along with any includes
foreach $file (@ARGV) { process($file, 'fh00'); }
sub process { my($filename, $input) = @_; $input++; # this is a string increment unless (open($input, $filename)) { print STDERR "Can't open $filename: $!\n"; return; }
local $_; while (<$input>) { # note use of indirection if (/^#include "(.*)"/) { process($1, $input); next; } #... # whatever } }
#!/usr/bin/perl open my $oldout, ">&STDOUT" or die "Can't dup STDOUT: $!"; open OLDERR, ">&", \*STDERR or die "Can't dup STDERR: $!";
open STDOUT, '>', "foo.out" or die "Can't redirect STDOUT: $!"; open STDERR, ">&STDOUT" or 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, ">&", $oldout or die "Can't dup \$oldout: $!"; open STDERR, ">&OLDERR" or die "Can't dup OLDERR: $!";
print STDOUT "stdout 2\n"; print STDERR "stderr 2\n";
# open for input, reusing the fileno of $fd open(FILEHANDLE, "<&=$fd")
open(FILEHANDLE, "<&=", $fd)
# open for append, using the fileno of OLDFH open(FH, ">>&=", OLDFH)
open(FH, ">>&=OLDFH")
open(FOO, "⎪tr '[a-z]' '[A-Z]'"); open(FOO, '⎪-', "tr '[a-z]' '[A-Z]'"); open(FOO, '⎪-') ⎪⎪ exec 'tr', '[a-z]', '[A-Z]'; open(FOO, '⎪-', "tr", '[a-z]', '[A-Z]');
open(FOO, "cat -n '$file'⎪"); open(FOO, '-⎪', "cat -n '$file'"); open(FOO, '-⎪') ⎪⎪ exec 'cat', '-n', $file; open(FOO, '-⎪', "cat", '-n', $file);
$filename =~ s/(.*\.gz)\s*$/gzip -dc < $1⎪/; open(FH, $filename) or die "Can't open $filename: $!";
open(FOO, '<', $file);
$file =~ s#^(\s)#./$1#; open(FOO, "< $file\0");
open IN, $ARGV[0];
open IN, '<', $ARGV[0];
use IO::Handle; sysopen(HANDLE, $path, O_RDWR⎪O_CREAT⎪O_EXCL) or die "sysopen $path: $!"; $oldfh = select(HANDLE); $⎪ = 1; select($oldfh); print HANDLE "stuff $$\n"; seek(HANDLE, 0, 0); print "File contains: ", <HANDLE>;
use IO::File; #... sub read_myfile_munged { my $ALL = shift; my $handle = new IO::File; open($handle, "myfile") or die "myfile: $!"; $first = <$handle> or return (); # Automatically closed here. mung $first or die "mung failed"; # Or here. return $first, <$handle> if $ALL; # Or here. $first; # Or here. }
- opendir DIRHANDLE,EXPR
- Opens a directory named EXPR for processing by "readdir", "telldir", "seekdir", "rewinddir", and "closedir". Returns true if successful. DIRHANDLE may be an expression whose value can be used as an indirect dirhandle, usually the real dirhandle name. If DIRHANDLE is an undefined scalar variable (or array or hash element), the variable is assigned a reference to a new anonymous dirhandle. DIRHANDLEs have their own namespace separate from FILEHANDLEs.
- ord EXPR
- ord
- Returns the numeric (the native 8-bit encoding, like ASCII
or EBCDIC, or Unicode) value of the first character of EXPR. If EXPR is
omitted, uses $_.
- our EXPR
- our EXPR TYPE
- our EXPR : ATTRS
- our TYPE EXPR : ATTRS
- An "our" declares the listed variables to be
valid globals within the enclosing block, file, or "eval". That
is, it has the same scoping rules as a "my" declaration, but
does not create a local variable. If more than one value is listed, the
list must be placed in parentheses. The "our" declaration has no
semantic effect unless "use strict vars" is in effect, in which
case it lets you use the declared global variable without qualifying it
with a package name. (But only within the lexical scope of the
"our" declaration. In this it differs from "use vars",
which is package scoped.)
package Foo; our $bar; # declares $Foo::bar for rest of lexical scope $bar = 20;
package Bar; print $bar; # prints 20
use warnings; package Foo; our $bar; # declares $Foo::bar for rest of lexical scope $bar = 20;
package Bar; our $bar = 30; # declares $Bar::bar for rest of lexical scope print $bar; # prints 30
our $bar; # emits warning
our @EXPORT : unique = qw(foo); our %EXPORT_TAGS : unique = (bar => [qw(aa bb cc)]); our $VERSION : unique = "1.00";
- pack TEMPLATE,LIST
- Takes a LIST of values and converts it into a string using
the rules given by the TEMPLATE. The resulting string is the concatenation
of the converted values. Typically, each converted value looks like its
machine-level representation. For example, on 32-bit machines a converted
integer may be represented by a sequence of 4 bytes.
a A string with arbitrary binary data, will be null padded. A A text (ASCII) string, will be space padded. Z A null terminated (ASCIZ) string, will be null padded.
b A bit string (ascending bit order inside each byte, like vec()). B A bit string (descending bit order inside each byte). h A hex string (low nybble first). H A hex string (high nybble first).
c A signed char value. C An unsigned char value. Only does bytes. See U for Unicode.
s A signed short value. S An unsigned short value. (This 'short' is _exactly_ 16 bits, which may differ from what a local C compiler calls 'short'. If you want native-length shorts, use the '!' suffix.)
i A signed integer value. I An unsigned integer value. (This 'integer' is _at_least_ 32 bits wide. Its exact size depends on what a local C compiler calls 'int', and may even be larger than the 'long' described in the next item.)
l A signed long value. L An unsigned long value. (This 'long' is _exactly_ 32 bits, which may differ from what a local C compiler calls 'long'. If you want native-length longs, use the '!' suffix.)
n An unsigned short in "network" (big-endian) order. N An unsigned long in "network" (big-endian) order. v An unsigned short in "VAX" (little-endian) order. V An unsigned long in "VAX" (little-endian) order. (These 'shorts' and 'longs' are _exactly_ 16 bits and _exactly_ 32 bits, respectively.)
q A signed quad (64-bit) value. Q An unsigned quad value. (Quads are available only if your system supports 64-bit integer values _and_ if Perl has been compiled to support those. Causes a fatal error otherwise.)
j A signed integer value (a Perl internal integer, IV). J An unsigned integer value (a Perl internal unsigned integer, UV).
f A single-precision float in the native format. d A double-precision float in the native format.
F A floating point value in the native native format (a Perl internal floating point value, NV). D A long double-precision float in the native format. (Long doubles are available only if your system supports long double values _and_ if Perl has been compiled to support those. Causes a fatal error otherwise.)
p A pointer to a null-terminated string. P A pointer to a structure (fixed-length string).
u A uuencoded string. U A Unicode character number. Encodes to UTF-8 internally (or UTF-EBCDIC in EBCDIC platforms).
w A BER compressed integer. Its bytes represent an unsigned integer in base 128, most significant digit first, with as few digits as possible. Bit eight (the high bit) is set on each byte except the last.
x A null byte. X Back up a byte. @ Null fill to absolute position, counted from the start of the innermost ()-group. ( Start of a ()-group.
- *
- Each letter may optionally be followed by a number giving a
repeat count. With all types except "a", "A",
"Z", "b", "B", "h", "H",
"@", "x", "X" and "P" the pack
function will gobble up that many values from the LIST. A "*"
for the repeat count means to use however many items are left, except for
"@", "x", "X", where it is equivalent to 0,
and "u", where it is equivalent to 1 (or 45, what is the same).
A numeric repeat count may optionally be enclosed in brackets, as in
"pack 'C[80]', @arr".
- *
- The "a", "A", and "Z" types
gobble just one value, but pack it as a string of length count, padding
with nulls or spaces as necessary. When unpacking, "A" strips
trailing spaces and nulls, "Z" strips everything after the first
null, and "a" returns data verbatim. When packing,
"a", and "Z" are equivalent.
- *
- Likewise, the "b" and "B" fields pack a
string that many bits long. Each byte of the input field of pack()
generates 1 bit of the result. Each result bit is based on the
least-significant bit of the corresponding input byte, i.e., on
"ord($byte)%2". In particular, bytes "0" and
"1" generate bits 0 and 1, as do bytes "\0" and
"\1".
- *
- The "h" and "H" fields pack a string
that many nybbles (4-bit groups, representable as hexadecimal digits,
0-9a-f) long.
- *
- The "p" type packs a pointer to a null-terminated string. You are responsible for ensuring the string is not a temporary value (which can potentially get deallocated before you get around to using the packed result). The "P" type packs a pointer to a structure of the size indicated by the length. A NULL pointer is created if the corresponding value for "p" or "P" is "undef", similarly for unpack().
- *
- The "/" template character allows packing and
unpacking of strings where the packed structure contains a byte count
followed by the string itself. You write
length-item"/"string-item.
unpack 'C/a', "\04Gurusamy"; gives 'Guru' unpack 'a3/A* A*', '007 Bond J '; gives (' Bond','J') pack 'n/a* w/a*','hello,','world'; gives "\000\006hello,\005world"
- *
- The integer types "s", "S",
"l", and "L" may be immediately followed by a
"!" suffix to signify native shorts or longs--as you can see
from above for example a bare "l" does mean exactly 32 bits, the
native "long" (as seen by the local C compiler) may be larger.
This is an issue mainly in 64-bit platforms. You can see whether using
"!" makes any difference by
print length(pack("s")), " ", length(pack("s!")), "\n"; print length(pack("l")), " ", length(pack("l!")), "\n";
use Config; print $Config{shortsize}, "\n"; print $Config{intsize}, "\n"; print $Config{longsize}, "\n"; print $Config{longlongsize}, "\n";
- *
- The integer formats "s", "S",
"i", "I", "l", "L", "j",
and "J" are inherently non-portable between processors and
operating systems because they obey the native byteorder and endianness.
For example a 4-byte integer 0x12345678 (305419896 decimal) would be
ordered natively (arranged in and handled by the CPU registers) into bytes
as
0x12 0x34 0x56 0x78 # big-endian 0x78 0x56 0x34 0x12 # little-endian
0x56 0x78 0x12 0x34 0x34 0x12 0x78 0x56
print join(" ", map { sprintf "%#02x", $_ } unpack("C*",pack("L",0x12345678))), "\n";
use Config; print $Config{byteorder}, "\n";
- *
- Real numbers (floats and doubles) are in the native machine
format only; due to the multiplicity of floating formats around, and the
lack of a standard "network" representation, no facility for
interchange has been made. This means that packed floating point data
written on one machine may not be readable on another - even if both use
IEEE floating point arithmetic (as the endian-ness of the memory
representation is not part of the IEEE spec). See also perlport.
- *
- If the pattern begins with a "U", the resulting string will be treated as UTF-8-encoded Unicode. You can force UTF-8 encoding on in a string with an initial "U0", and the bytes that follow will be interpreted as Unicode characters. If you don't want this to happen, you can begin your pattern with "C0" (or anything else) to force Perl not to UTF-8 encode your string, and then follow this with a "U*" somewhere in your pattern.
- *
- You must yourself do any alignment or padding by inserting for example enough 'x'es while packing. There is no way to pack() and unpack() could know where the bytes are going to or coming from. Therefore "pack" (and "unpack") handle their output and input as flat sequences of bytes.
- *
- A ()-group is a sub-TEMPLATE enclosed in parentheses. A
group may take a repeat count, both as postfix, and for unpack()
also via the "/" template character. Within each repetition of a
group, positioning with "@" starts again at 0. Therefore, the
result of
pack( '@1A((@2A)@3A)', 'a', 'b', 'c' )
- *
- "x" and "X" accept "!"
modifier. In this case they act as alignment commands: they jump
forward/back to the closest position aligned at a multiple of
"count" bytes. For example, to pack() or unpack()
C's "struct {char c; double d; char cc[2]}" one may need to use
the template "C x![d] d C[2]"; this assumes that doubles must be
aligned on the double's size.
- *
- A comment in a TEMPLATE starts with "#" and goes to the end of line. White space may be used to separate pack codes from each other, but a "!" modifier and a repeat count must follow immediately.
- *
- If TEMPLATE requires more arguments to pack() than actually given, pack() assumes additional "" arguments. If TEMPLATE requires less arguments to pack() than actually given, extra arguments are ignored.
$foo = pack("CCCC",65,66,67,68); # foo eq "ABCD" $foo = pack("C4",65,66,67,68); # same thing $foo = pack("U4",0x24b6,0x24b7,0x24b8,0x24b9); # same thing with Unicode circled letters
$foo = pack("ccxxcc",65,66,67,68); # foo eq "AB\0\0CD"
# note: the above examples featuring "C" and "c" are true # only on ASCII and ASCII-derived systems such as ISO Latin 1 # and UTF-8. In EBCDIC the first example would be # $foo = pack("CCCC",193,194,195,196);
$foo = pack("s2",1,2); # "\1\0\2\0" on little-endian # "\0\1\0\2" on big-endian
$foo = pack("a4","abcd","x","y","z"); # "abcd"
$foo = pack("aaaa","abcd","x","y","z"); # "axyz"
$foo = pack("a14","abcdefg"); # "abcdefg\0\0\0\0\0\0\0"
$foo = pack("i9pl", gmtime); # a real struct tm (on my system anyway)
$utmp_template = "Z8 Z8 Z16 L"; $utmp = pack($utmp_template, @utmp1); # a struct utmp (BSDish)
@utmp2 = unpack($utmp_template, $utmp); # "@utmp1" eq "@utmp2"
sub bintodec { unpack("N", pack("B32", substr("0" x 32 . shift, -32))); }
$foo = pack('sx2l', 12, 34); # short 12, two zero bytes padding, long 34 $bar = pack('s@4l', 12, 34); # short 12, zero fill to position 4, long 34 # $foo eq $bar
- package NAMESPACE
- package
- Declares the compilation unit as being in the given
namespace. The scope of the package declaration is from the declaration
itself through the end of the enclosing block, file, or eval (the same as
the "my" operator). All further unqualified dynamic identifiers
will be in this namespace. A package statement affects only dynamic
variables--including those you've used "local" on--but
not lexical variables, which are created with "my".
Typically it would be the first declaration in a file to be included by
the "require" or "use" operator. You can switch into a
package in more than one place; it merely influences which symbol table is
used by the compiler for the rest of that block. You can refer to
variables and filehandles in other packages by prefixing the identifier
with the package name and a double colon: $Package::Variable. If the
package name is null, the "main" package as assumed. That is,
$::sail is equivalent to $main::sail (as well as to $main'sail, still seen
in older code).
- 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 IO buffering, so you may need to set $⎪ to flush your
WRITEHANDLE after each command, depending on the application.
- pop ARRAY
- pop
- Pops and returns the last value of the array, shortening
the array by one element. Has an effect similar to
$ARRAY[$#ARRAY--]
- pos SCALAR
- pos
- Returns the offset of where the last "m//g" search left off for the variable in question ($_ is used when the variable is not specified). May be modified to change that offset. Such modification will also influence the "\G" zero-width assertion in regular expressions. See perlre and perlop.
- print FILEHANDLE LIST
- print LIST
- Prints a string or a list of strings. Returns true if
successful. FILEHANDLE may be a scalar variable name, in which case the
variable contains the name of or a reference to 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 parentheses 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 the currently selected output channel. To
set the default output channel to something other than STDOUT use the
select operation. The current value of $, (if any) is printed between each
LIST item. The current value of "$\" (if any) is printed after
the entire LIST has been printed. Because print takes a LIST, anything in
the LIST is evaluated in list context, and any subroutine that you call
will have one or more of its expressions evaluated in list 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 parentheses around all the
arguments.
print { $files[$i] } "stuff\n"; print { $OK ? STDOUT : STDERR } "stuff\n";
- printf FILEHANDLE FORMAT, LIST
- printf FORMAT, LIST
- Equivalent to "print FILEHANDLE sprintf(FORMAT,
LIST)", except that "$\" (the output record separator) is
not appended. The first argument of the list will be interpreted as the
"printf" format. See "sprintf" for an explanation of
the format argument. If "use locale" is in effect, the character
used for the decimal point in formatted real numbers is affected by the
LC_NUMERIC locale. See perllocale.
- prototype FUNCTION
- Returns the prototype of a function as a string (or
"undef" if the function has no prototype). FUNCTION is a
reference to, or the name of, the function whose prototype you want to
retrieve.
- push ARRAY,LIST
- Treats ARRAY as a stack, and pushes the values of LIST onto
the end of ARRAY. The length of ARRAY increases by the length of LIST. Has
the same effect as
for $value (LIST) { $ARRAY[++$#ARRAY] = $value; }
- q/STRING/
- qq/STRING/
- qr/STRING/
- qx/STRING/
- qw/STRING/
- Generalized quotes. See "Regexp Quote-Like Operators" in perlop.
- quotemeta EXPR
- quotemeta
- Returns the value of EXPR with all non-"word"
characters backslashed. (That is, all characters not matching
"/[A-Za-z_0-9]/" will be preceded by a backslash in the returned
string, regardless of any locale settings.) This is the internal function
implementing the "\Q" escape in double-quoted strings.
- rand EXPR
- rand
- Returns a random fractional number greater than or equal to
0 and less than the value of EXPR. (EXPR should be positive.) If EXPR is
omitted, the value 1 is used. Currently EXPR with the value 0 is also
special-cased as 1 - this has not been documented before perl 5.8.0 and is
subject to change in future versions of perl. Automatically calls
"srand" unless "srand" has already been called. See
also "srand".
int(rand(10))
- read FILEHANDLE,SCALAR,LENGTH,OFFSET
- read FILEHANDLE,SCALAR,LENGTH
- Attempts to read LENGTH characters of data into
variable SCALAR from the specified FILEHANDLE. Returns the number of
characters actually read, 0 at end of file, or undef if there was an error
(in the latter case $! is also set). SCALAR will be grown or shrunk so
that the last character actually read is the last character of the scalar
after the read.
- readdir DIRHANDLE
- Returns the next directory entry for a directory opened by
"opendir". If used in list context, returns all the rest of the
entries in the directory. If there are no more entries, returns an
undefined value in scalar context or a null list in list context.
opendir(DIR, $some_dir) ⎪⎪ die "can't opendir $some_dir: $!"; @dots = grep { /^\./ && -f "$some_dir/$_" } readdir(DIR); closedir DIR;
- readline EXPR
- Reads from the filehandle whose typeglob is contained in
EXPR. In scalar context, each call reads and returns the next line, until
end-of-file is reached, whereupon the subsequent call returns undef. In
list context, reads until end-of-file is reached and returns a list of
lines. Note that the notion of "line" used here is however you
may have defined it with $/ or $INPUT_RECORD_SEPARATOR). See
"$/" in perlvar.
$line = <STDIN>; $line = readline(*STDIN); # same thing
for (;;) { undef $!; unless (defined( $line = <> )) { die $! if $!; last; # reached EOF } # ... }
- readlink EXPR
- readlink
- Returns the value of a symbolic link, if symbolic links are implemented. If not, gives a fatal error. If there is some system error, returns the undefined value and sets $! (errno). If EXPR is omitted, uses $_.
- readpipe EXPR
- EXPR is executed as a system command. The collected standard output of the command is returned. In scalar context, it comes back as a single (potentially multi-line) string. In list context, returns a list of lines (however you've defined lines with $/ or $INPUT_RECORD_SEPARATOR). This is the internal function implementing the "qx/EXPR/" operator, but you can use it directly. The "qx/EXPR/" operator is discussed in more detail in "I/O Operators" in perlop.
- recv SOCKET,SCALAR,LENGTH,FLAGS
- Receives a message on a socket. Attempts to receive LENGTH
characters of data into variable SCALAR from the specified SOCKET
filehandle. SCALAR will be grown or shrunk to the length actually read.
Takes the same flags as the system call of the same name. Returns the
address of the sender if SOCKET's protocol supports this; returns an empty
string otherwise. If there's an error, returns the undefined value. This
call is actually implemented in terms of recvfrom(2) system call.
See "UDP: Message Passing" in perlipc for examples.
- redo LABEL
- redo
- The "redo" command restarts the loop block
without evaluating the conditional again. The "continue" block,
if any, is not executed. If the LABEL is omitted, the command refers to
the innermost enclosing loop. This command is normally used by programs
that want to lie to themselves about what was just input:
# a simpleminded Pascal comment stripper # (warning: assumes no { or } in strings) LINE: while (<STDIN>) { while (s⎪({.*}.*){.*}⎪$1 ⎪) {} s⎪{.*}⎪ ⎪; if (s⎪{.*⎪ ⎪) { $front = $_; while (<STDIN>) { if (/}/) { # end of comment? s⎪^⎪$front\{⎪; redo LINE; } } } print; }
- ref EXPR
- ref
- Returns a true value if EXPR is a reference, false
otherwise. If EXPR is not specified, $_ will be used. The value returned
depends on the type of thing the reference is a reference to. Builtin
types include:
SCALAR ARRAY HASH CODE REF GLOB LVALUE
if (ref($r) eq "HASH") { print "r is a reference to a hash.\n"; } unless (ref($r)) { print "r is not a reference at all.\n"; } if (UNIVERSAL::isa($r, "HASH")) { # for subclassing print "r is a reference to something that isa hash.\n"; }
- rename OLDNAME,NEWNAME
- Changes the name of a file; an existing file NEWNAME will
be clobbered. Returns true for success, false otherwise.
- require VERSION
- require EXPR
- require
- Demands a version of Perl specified by VERSION, or demands
some semantics specified by EXPR or by $_ if EXPR is not supplied.
require v5.6.1; # run time version check require 5.6.1; # ditto require 5.006_001; # ditto; preferred for backwards compatibility
sub require { my($filename) = @_; return 1 if $INC{$filename}; my($realfilename,$result); ITER: { foreach $prefix (@INC) { $realfilename = "$prefix/$filename"; if (-f $realfilename) { $INC{$filename} = $realfilename; $result = do $realfilename; last ITER; } } die "Can't find $filename in \@INC"; } delete $INC{$filename} if $@ ⎪⎪ !$result; die $@ if $@; die "$filename did not return true value" unless $result; return $result; }
require Foo::Bar; # a splendid bareword
$class = 'Foo::Bar'; require $class; # $class is not a bareword #or require "Foo::Bar"; # not a bareword because of the ""
eval "require $class";
push @INC, \&my_sub; sub my_sub { my ($coderef, $filename) = @_; # $coderef is \&my_sub ... }
push @INC, [ \&my_sub, $x, $y, ... ]; sub my_sub { my ($arrayref, $filename) = @_; # Retrieve $x, $y, ... my @parameters = @$arrayref[1..$#$arrayref]; ... }
# In Foo.pm package Foo; sub new { ... } sub Foo::INC { my ($self, $filename) = @_; ... }
# In the main program push @INC, new Foo(...);
- reset EXPR
- reset
- Generally used in a "continue" block at the end
of a loop to clear variables and reset "??" searches so that
they work again. The expression is interpreted as a list of single
characters (hyphens allowed for ranges). All variables and arrays
beginning with one of those letters are reset to their pristine state. If
the expression is omitted, one-match searches ("?pattern?") are
reset to match again. Resets only variables or searches in the current
package. Always returns 1. Examples:
reset 'X'; # reset all X variables reset 'a-z'; # reset lower case variables reset; # just reset ?one-time? searches
- return EXPR
- return
- Returns from a subroutine, "eval", or "do
FILE" with the value given in EXPR. Evaluation of EXPR may be in
list, scalar, or void context, depending on how the return value will be
used, and the context may vary from one execution to the next (see
"wantarray"). If no EXPR is given, returns an empty list in list
context, the undefined value in scalar context, and (of course) nothing at
all in a void context.
- reverse LIST
- In list context, returns a list value consisting of the
elements of LIST in the opposite order. In scalar context, concatenates
the elements of LIST and returns a string value with all characters in the
opposite order.
print reverse <>; # line tac, last line first
undef $/; # for efficiency of <> print scalar reverse <>; # character tac, last line tsrif
%by_name = reverse %by_address; # Invert the hash
- rewinddir DIRHANDLE
- Sets the current position to the beginning of the directory for the "readdir" routine on DIRHANDLE.
- rindex STR,SUBSTR,POSITION
- rindex STR,SUBSTR
- Works just like index() except that it returns the position of the LAST occurrence of SUBSTR in STR. If POSITION is specified, returns the last occurrence at or before that position.
- rmdir FILENAME
- rmdir
- Deletes the directory specified by FILENAME if that directory is empty. If it succeeds it returns true, otherwise it returns false and sets $! (errno). If FILENAME is omitted, uses $_.
- s///
- The substitution operator. See perlop.
- scalar EXPR
- Forces EXPR to be interpreted in scalar context and returns
the value of EXPR.
@counts = ( scalar @a, scalar @b, scalar @c );
print uc(scalar(&foo,$bar)),$baz;
&foo; print(uc($bar),$baz);
- seek FILEHANDLE,POSITION,WHENCE
- Sets FILEHANDLE's position, just like the "fseek"
call of "stdio". FILEHANDLE may be an expression whose value
gives the name of the filehandle. The values for WHENCE are 0 to set the
new position in bytes to POSITION, 1 to set it to the current
position plus POSITION, and 2 to set it to EOF plus POSITION (typically
negative). For WHENCE you may use the constants "SEEK_SET",
"SEEK_CUR", and "SEEK_END" (start of the file, current
position, end of the file) from the Fcntl module. Returns 1 upon success,
0 otherwise.
seek(TEST,0,1);
for (;;) { for ($curpos = tell(FILE); $_ = <FILE>; $curpos = tell(FILE)) { # search for some stuff and put it into files } sleep($for_a_while); seek(FILE, $curpos, 0); }
- seekdir DIRHANDLE,POS
- Sets the current position for the "readdir" routine on DIRHANDLE. POS must be a value returned by "telldir". Has the same caveats about possible directory compaction as the corresponding system library routine.
- 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';
$oldfh = select(STDERR); $⎪ = 1; select($oldfh);
use IO::Handle; STDERR->autoflush(1);
- select RBITS,WBITS,EBITS,TIMEOUT
- This calls the select(2) system call with the bit
masks specified, which can be constructed using "fileno" and
"vec", along these lines:
$rin = $win = $ein = ''; vec($rin,fileno(STDIN),1) = 1; vec($win,fileno(STDOUT),1) = 1; $ein = $rin ⎪ $win;
sub fhbits { my(@fhlist) = split(' ',$_[0]); my($bits); for (@fhlist) { vec($bits,fileno($_),1) = 1; } $bits; } $rin = fhbits('STDIN TTY SOCK');
($nfound,$timeleft) = select($rout=$rin, $wout=$win, $eout=$ein, $timeout);
$nfound = select($rout=$rin, $wout=$win, $eout=$ein, undef);
select(undef, undef, undef, 0.25);
- semctl ID,SEMNUM,CMD,ARG
- Calls the System V IPC function "semctl". You'll
probably have to say
use IPC::SysV;
- semget KEY,NSEMS,FLAGS
- Calls the System V IPC function semget. Returns the semaphore id, or the undefined value if there is an error. See also "SysV IPC" in perlipc, "IPC::SysV", "IPC::SysV::Semaphore" documentation.
- semop KEY,OPSTRING
- Calls the System V IPC function semop to perform semaphore
operations such as signalling and waiting. OPSTRING must be a packed array
of semop structures. Each semop structure can be generated with
"pack("s!3", $semnum, $semop, $semflag)". The number
of semaphore operations is implied by the length of OPSTRING. Returns true
if successful, or false if there is an error. As an example, the following
code waits on semaphore $semnum of semaphore id $semid:
$semop = pack("s!3", $semnum, -1, 0); die "Semaphore trouble: $!\n" unless semop($semid, $semop);
- send SOCKET,MSG,FLAGS,TO
- send SOCKET,MSG,FLAGS
- Sends a message on a socket. Attempts to send the scalar
MSG to the SOCKET filehandle. Takes the same flags as the system call of
the same name. On unconnected sockets you must specify a destination to
send TO, in which case it does a C "sendto". Returns the number
of characters sent, or the undefined value if there is an error. The C
system call sendmsg(2) is currently unimplemented. See "UDP:
Message Passing" in perlipc for examples.
- setpgrp PID,PGRP
- Sets the current process group for the specified PID, 0 for the current process. Will produce a fatal error if used on a machine that doesn't implement POSIX setpgid(2) or BSD setpgrp(2). If the arguments are omitted, it defaults to "0,0". Note that the BSD 4.2 version of "setpgrp" does not accept any arguments, so only "setpgrp(0,0)" is portable. See also "POSIX::setsid()".
- setpriority WHICH,WHO,PRIORITY
- Sets the current priority for a process, a process group, or a user. (See setpriority(2).) Will produce a fatal error if used on a machine that doesn't implement setpriority(2).
- setsockopt SOCKET,LEVEL,OPTNAME,OPTVAL
- Sets the socket option requested. Returns undefined if there is an error. OPTVAL may be specified as "undef" if you don't want to pass an argument.
- shift ARRAY
- shift
- Shifts the first value of the array off and returns it,
shortening the array by 1 and moving everything down. If there are no
elements in the array, returns the undefined value. If ARRAY is omitted,
shifts the @_ array within the lexical scope of subroutines and formats,
and the @ARGV array at file scopes or within the lexical scopes
established by the "eval ''", "BEGIN {}", "INIT
{}", "CHECK {}", and "END {}" constructs.
- shmctl ID,CMD,ARG
- Calls the System V IPC function shmctl. You'll probably
have to say
use IPC::SysV;
- shmget KEY,SIZE,FLAGS
- Calls the System V IPC function shmget. Returns the shared memory segment id, or the undefined value if there is an error. See also "SysV IPC" in perlipc and "IPC::SysV" documentation.
- shmread ID,VAR,POS,SIZE
- shmwrite ID,STRING,POS,SIZE
- Reads or writes the System V shared memory segment ID starting at position POS for size SIZE by attaching to it, copying in/out, and detaching from it. When reading, VAR must be a variable that will hold the data read. When writing, if STRING is too long, only SIZE bytes are used; if STRING is too short, nulls are written to fill out SIZE bytes. Return true if successful, or false if there is an error. shmread() taints the variable. See also "SysV IPC" in perlipc, "IPC::SysV" documentation, and the "IPC::Shareable" module from CPAN.
- shutdown SOCKET,HOW
- Shuts down a socket connection in the manner indicated by
HOW, which has the same interpretation as in the system call of the same
name.
shutdown(SOCKET, 0); # I/we have stopped reading data shutdown(SOCKET, 1); # I/we have stopped writing data shutdown(SOCKET, 2); # I/we have stopped using this socket
- sin EXPR
- sin
- Returns the sine of EXPR (expressed in radians). If EXPR is
omitted, returns sine of $_.
sub asin { atan2($_[0], sqrt(1 - $_[0] * $_[0])) }
- sleep EXPR
- sleep
- Causes the script to sleep for EXPR seconds, or forever if
no EXPR. May be interrupted if the process receives a signal such as
"SIGALRM". Returns the number of seconds actually slept. You
probably cannot mix "alarm" and "sleep" calls, because
"sleep" is often implemented using "alarm".
- socket SOCKET,DOMAIN,TYPE,PROTOCOL
- Opens a socket of the specified kind and attaches it to
filehandle SOCKET. DOMAIN, TYPE, and PROTOCOL are specified the same as
for the system call of the same name. You should "use Socket"
first to get the proper definitions imported. See the examples in
"Sockets: Client/Server Communication" in perlipc.
- socketpair SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL
- Creates an unnamed pair of sockets in the specified domain,
of the specified type. DOMAIN, TYPE, and PROTOCOL are specified the same
as for the system call of the same name. If unimplemented, yields a fatal
error. Returns true if successful.
use Socket; socketpair(Rdr, Wtr, AF_UNIX, SOCK_STREAM, PF_UNSPEC); shutdown(Rdr, 1); # no more writing for reader shutdown(Wtr, 0); # no more reading for writer
- sort SUBNAME LIST
- sort BLOCK LIST
- sort LIST
- In list context, this sorts the LIST and returns the sorted
list value. In scalar context, the behaviour of "sort()" is
undefined.
# sort lexically @articles = sort @files;
# same thing, but with explicit sort routine @articles = sort {$a cmp $b} @files;
# now case-insensitively @articles = sort {uc($a) cmp uc($b)} @files;
# same thing in reversed order @articles = sort {$b cmp $a} @files;
# sort numerically ascending @articles = sort {$a <=> $b} @files;
# sort numerically descending @articles = sort {$b <=> $a} @files;
# this sorts the %age hash by value instead of key # using an in-line function @eldest = sort { $age{$b} <=> $age{$a} } keys %age;
# sort using explicit subroutine name sub byage { $age{$a} <=> $age{$b}; # presuming numeric } @sortedclass = sort byage @class;
sub backwards { $b cmp $a } @harry = qw(dog cat x Cain Abel); @george = qw(gone chased yz Punished Axed); print sort @harry; # prints AbelCaincatdogx print sort backwards @harry; # prints xdogcatCainAbel print sort @george, 'to', @harry; # prints AbelAxedCainPunishedcatchaseddoggonetoxyz
# inefficiently sort by descending numeric compare using # the first integer after the first = sign, or the # whole record case-insensitively otherwise
@new = sort { ($b =~ /=(\d+)/)[0] <=> ($a =~ /=(\d+)/)[0] ⎪⎪ uc($a) cmp uc($b) } @old;
# same thing, but much more efficiently; # we'll build auxiliary indices instead # for speed @nums = @caps = (); for (@old) { push @nums, /=(\d+)/; push @caps, uc($_); }
@new = @old[ sort { $nums[$b] <=> $nums[$a] ⎪⎪ $caps[$a] cmp $caps[$b] } 0..$#old ];
# same thing, but without any temps @new = map { $_->[0] } sort { $b->[1] <=> $a->[1] ⎪⎪ $a->[2] cmp $b->[2] } map { [$_, /=(\d+)/, uc($_)] } @old;
# using a prototype allows you to use any comparison subroutine # as a sort subroutine (including other package's subroutines) package other; sub backwards ($$) { $_[1] cmp $_[0]; } # $a and $b are not set here
package main; @new = sort other::backwards @old;
# guarantee stability, regardless of algorithm use sort 'stable'; @new = sort { substr($a, 3, 5) cmp substr($b, 3, 5) } @old;
# force use of mergesort (not portable outside Perl 5.8) use sort '_mergesort'; # note discouraging _ @new = sort { substr($a, 3, 5) cmp substr($b, 3, 5) } @old;
@articles = sort {$b <=> $a} @files;
@articles = sort {$FooPack::b <=> $FooPack::a} @files;
@result = sort { $a <=> $b } grep { $_ == $_ } @input;
- splice ARRAY,OFFSET,LENGTH,LIST
- splice ARRAY,OFFSET,LENGTH
- splice ARRAY,OFFSET
- splice ARRAY
- Removes the elements designated by OFFSET and LENGTH from
an array, and replaces them with the elements of LIST, if any. In list
context, returns the elements removed from the array. In scalar context,
returns the last element removed, or "undef" if no elements are
removed. The array grows or shrinks as necessary. If OFFSET is negative
then it starts that far from the end of the array. If LENGTH is omitted,
removes everything from OFFSET onward. If LENGTH is negative, removes the
elements from OFFSET onward except for -LENGTH elements at the end of the
array. If both OFFSET and LENGTH are omitted, removes everything. If
OFFSET is past the end of the array, perl issues a warning, and splices at
the end of the array.
push(@a,$x,$y) splice(@a,@a,0,$x,$y) pop(@a) splice(@a,-1) shift(@a) splice(@a,0,1) unshift(@a,$x,$y) splice(@a,0,0,$x,$y) $a[$i] = $y splice(@a,$i,1,$y)
sub aeq { # compare two list values my(@a) = splice(@_,0,shift); my(@b) = splice(@_,0,shift); return 0 unless @a == @b; # same len? while (@a) { return 0 if pop(@a) ne pop(@b); } return 1; } if (&aeq($len,@foo[1..$len],0+@bar,@bar)) { ... }
- split /PATTERN/,EXPR,LIMIT
- split /PATTERN/,EXPR
- split /PATTERN/
- split
- Splits a string into a list of strings and returns that
list. By default, empty leading fields are preserved, and empty trailing
ones are deleted.
print join(':', split(/ */, 'hi there'));
print join(':', split(/(?=\w)/, 'hi there!'));
($login, $passwd, $remainder) = split(/:/, $_, 3);
split(/([,-])/, "1-10,20", 3);
(1, '-', 10, ',', 20)
$header =~ s/\n\s+/ /g; # fix continuation lines %hdrs = (UNIX_FROM => split /^(\S*?):\s*/m, $header);
open(PASSWD, '/etc/passwd'); while (<PASSWD>) { chomp; ($login, $passwd, $uid, $gid, $gcos, $home, $shell) = split(/:/); #... }
@fields = split /(A)⎪B/, "1A2B3"; # @fields is (1, 'A', 2, undef, 3)
- sprintf FORMAT, LIST
- Returns a string formatted by the usual "printf"
conventions of the C library function "sprintf". See below for
more details and see sprintf(3) or printf(3) on your system
for an explanation of the general principles.
# Format number with up to 8 leading zeroes $result = sprintf("%08d", $number);
# Round number to 3 digits after decimal point $rounded = sprintf("%.3f", $number);
%% a percent sign %c a character with the given number %s a string %d a signed integer, in decimal %u an unsigned integer, in decimal %o an unsigned integer, in octal %x an unsigned integer, in hexadecimal %e a floating-point number, in scientific notation %f a floating-point number, in fixed decimal notation %g a floating-point number, in %e or %f notation
%X like %x, but using upper-case letters %E like %e, but using an upper-case "E" %G like %g, but with an upper-case "E" (if applicable) %b an unsigned integer, in binary %p a pointer (outputs the Perl value's address in hexadecimal) %n special: *stores* the number of characters output so far into the next variable in the parameter list
%i a synonym for %d %D a synonym for %ld %U a synonym for %lu %O a synonym for %lo %F a synonym for %f
- format parameter index
- An explicit format parameter index, such as "2$".
By default sprintf will format the next unused argument in the list, but
this allows you to take the arguments out of order. Eg:
printf '%2$d %1$d', 12, 34; # prints "34 12" printf '%3$d %d %1$d', 1, 2, 3; # prints "3 1 1"
- flags
- one or more of:
space prefix positive number with a space
+ prefix positive number with a plus sign
- left-justify within the field
0 use zeros, not spaces, to right-justify
# prefix non-zero octal with "0", non-zero hex with "0x",
non-zero binary with "0b"printf '<% d>', 12; # prints "< 12>" printf '<%+d>', 12; # prints "<+12>" printf '<%6s>', 12; # prints "< 12>" printf '<%-6s>', 12; # prints "<12 >" printf '<%06s>', 12; # prints "<000012>" printf '<%#x>', 12; # prints "<0xc>"
- vector flag
- The vector flag "v", optionally specifying the
join string to use. This flag tells perl to interpret the supplied string
as a vector of integers, one for each character in the string, separated
by a given string (a dot "." by default). This can be useful for
displaying ordinal values of characters in arbitrary strings:
printf "version is v%vd\n", $^V; # Perl's version
printf "address is %*vX\n", ":", $addr; # IPv6 address printf "bits are %0*v8b\n", " ", $bits; # random bitstring
printf '%*4$vX %*4$vX %*4$vX', @addr[1..3], ":"; # 3 IPv6 addresses
- (minimum) width
- Arguments are usually formatted to be only as wide as
required to display the given value. You can override the width by putting
a number here, or get the width from the next argument (with
"*") or from a specified argument (with eg "*2$"):
printf '<%s>', "a"; # prints "<a>" printf '<%6s>', "a"; # prints "< a>" printf '<%*s>', 6, "a"; # prints "< a>" printf '<%*2$s>', "a", 6; # prints "< a>" printf '<%2s>', "long"; # prints "<long>" (does not truncate)
- precision, or maximum width
- You can specify a precision (for numeric conversions) or a
maximum width (for string conversions) by specifying a "."
followed by a number. For floating point formats, with the exception of
'g' and 'G', this specifies the number of decimal places to show (the
default being 6), eg:
# these examples are subject to system-specific variation printf '<%f>', 1; # prints "<1.000000>" printf '<%.1f>', 1; # prints "<1.0>" printf '<%.0f>', 1; # prints "<1>" printf '<%e>', 10; # prints "<1.000000e+01>" printf '<%.1e>', 10; # prints "<1.0e+01>"
# these examples are subject to system-specific variation printf '<%g>', 1; # prints "<1>" printf '<%.10g>', 1; # prints "<1>" printf '<%g>', 100; # prints "<100>" printf '<%.1g>', 100; # prints "<1e+02>" printf '<%.2g>', 100.01; # prints "<1e+02>" printf '<%.5g>', 100.01; # prints "<100.01>" printf '<%.4g>', 100.01; # prints "<100>"
printf '<%.6x>', 1; # prints "<000001>" printf '<%#.6x>', 1; # prints "<0x000001>" printf '<%-10.6x>', 1; # prints "<000001 >"
printf '<%.5s>', "truncated"; # prints "<trunc>" printf '<%10.5s>', "truncated"; # prints "< trunc>"
printf '<%.6x>', 1; # prints "<000001>" printf '<%.*x>', 6, 1; # prints "<000001>"
printf '<%.*2$x>', 1, 6; # INVALID, but in future will print "<000001>"
- size
- For numeric conversions, you can specify the size to
interpret the number as using "l", "h", "V",
"q", "L", or "ll". For integer conversions
("d u o x X b i D U O"), numbers are usually assumed to be
whatever the default integer size is on your platform (usually 32 or 64
bits), but you can override this to use instead one of the standard C
types, as supported by the compiler used to build Perl:
l interpret integer as C type "long" or "unsigned long" h interpret integer as C type "short" or "unsigned short" q, L or ll interpret integer as C type "long long", "unsigned long long". or "quads" (typically 64-bit integers)
use Config; ($Config{use64bitint} eq 'define' ⎪⎪ $Config{longsize} >= 8) && print "quads\n";
use Config; $Config{d_longdbl} eq 'define' && print "long doubles\n";
use Config; ($Config{uselongdouble} eq 'define') && print "long doubles by default\n";
use Config; ($Config{doublesize} == $Config{longdblsize}) && print "doubles are long doubles\n";
- order of arguments
- Normally, sprintf takes the next unused argument as the
value to format for each format specification. If the format specification
uses "*" to require additional arguments, these are consumed
from the argument list in the order in which they appear in the format
specification before the value to format. Where an argument is
specified using an explicit index, this does not affect the normal order
for the arguments (even when the explicitly specified index would have
been the next argument in any case).
printf '<%*.*s>', $a, $b, $c;
print '<%*1$.*s>', $a, $b;
printf "%2\$d %d\n", 12, 34; # will print "34 12\n" printf "%2\$d %d %d\n", 12, 34; # will print "34 12 34\n" printf "%3\$d %d %d\n", 12, 34, 56; # will print "56 12 34\n" printf "%2\$*3\$d %d\n", 12, 34, 3; # will print " 34 12\n"
- sqrt EXPR
- sqrt
- Return the square root of EXPR. If EXPR is omitted, returns
square root of $_. Only works on non-negative operands, unless you've
loaded the standard Math::Complex module.
use Math::Complex; print sqrt(-2); # prints 1.4142135623731i
- srand EXPR
- srand
- Sets the random number seed for the "rand"
operator.
srand (time ^ $$ ^ unpack "%L*", `ps axww ⎪ gzip`);
time ^ $$
a^b == (a+1)^(b+1)
- stat FILEHANDLE
- stat EXPR
- stat
- Returns a 13-element list giving the status info for a
file, either the file opened via FILEHANDLE, or named by EXPR. If EXPR is
omitted, it stats $_. Returns a null list if the stat fails. Typically
used as follows:
($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size, $atime,$mtime,$ctime,$blksize,$blocks) = stat($filename);
0 dev device number of filesystem 1 ino inode number 2 mode file mode (type and permissions) 3 nlink number of (hard) links to the file 4 uid numeric user ID of file's owner 5 gid numeric group ID of file's owner 6 rdev the device identifier (special files only) 7 size total size of file, in bytes 8 atime last access time in seconds since the epoch 9 mtime last modify time in seconds since the epoch 10 ctime inode change time in seconds since the epoch (*) 11 blksize preferred block size for file system I/O 12 blocks actual number of blocks allocated
if (-x $file && (($d) = stat(_)) && $d < 0) { print "$file is executable NFS file\n"; }
$mode = (stat($filename))[2]; printf "Permissions are %04o\n", $mode & 07777;
use File::stat; $sb = stat($filename); printf "File is %s, size is %s, perm %04o, mtime %s\n", $filename, $sb->size, $sb->mode & 07777, scalar localtime $sb->mtime;
use Fcntl ':mode';
$mode = (stat($filename))[2];
$user_rwx = ($mode & S_IRWXU) >> 6; $group_read = ($mode & S_IRGRP) >> 3; $other_execute = $mode & S_IXOTH;
printf "Permissions are %04o\n", S_IMODE($mode), "\n";
$is_setuid = $mode & S_ISUID; $is_setgid = S_ISDIR($mode);
# Permissions: read, write, execute, for user, group, others.
S_IRWXU S_IRUSR S_IWUSR S_IXUSR S_IRWXG S_IRGRP S_IWGRP S_IXGRP S_IRWXO S_IROTH S_IWOTH S_IXOTH
# Setuid/Setgid/Stickiness/SaveText. # Note that the exact meaning of these is system dependent.
S_ISUID S_ISGID S_ISVTX S_ISTXT
# File types. Not necessarily all are available on your system.
S_IFREG S_IFDIR S_IFLNK S_IFBLK S_ISCHR S_IFIFO S_IFSOCK S_IFWHT S_ENFMT
# The following are compatibility aliases for S_IRUSR, S_IWUSR, S_IXUSR.
S_IREAD S_IWRITE S_IEXEC
S_IMODE($mode) the part of $mode containing the permission bits and the setuid/setgid/sticky bits
S_IFMT($mode) the part of $mode containing the file type which can be bit-anded with e.g. S_IFREG or with the following functions
# The operators -f, -d, -l, -b, -c, -p, and -s.
S_ISREG($mode) S_ISDIR($mode) S_ISLNK($mode) S_ISBLK($mode) S_ISCHR($mode) S_ISFIFO($mode) S_ISSOCK($mode)
# No direct -X operator counterpart, but for the first one # the -g operator is often equivalent. The ENFMT stands for # record flocking enforcement, a platform-dependent feature.
S_ISENFMT($mode) S_ISWHT($mode)
- study SCALAR
- study
- Takes extra time to study SCALAR ($_ if unspecified) in
anticipation of doing many pattern matches on the string before it is next
modified. This may or may not save time, depending on the nature and
number of patterns you are searching on, and on the distribution of
character frequencies in the string to be searched--you probably want to
compare run times with and without it to see which runs faster. Those
loops which scan for many short constant strings (including the constant
parts of more complex patterns) will benefit most. You may have only one
"study" active at a time--if you study a different scalar the
first is "unstudied". (The way "study" works is this:
a linked list of every character in the string to be searched is made, so
we know, for example, where all the 'k' characters are. From each search
string, the rarest character is selected, based on some static frequency
tables constructed from some C programs and English text. Only those
places that contain this "rarest" character are examined.)
while (<>) { study; print ".IX foo\n" if /\bfoo\b/; print ".IX bar\n" if /\bbar\b/; print ".IX blurfl\n" if /\bblurfl\b/; # ... print; }
$search = 'while (<>) { study;'; foreach $word (@words) { $search .= "++\$seen{\$ARGV} if /\\b$word\\b/;\n"; } $search .= "}"; @ARGV = @files; undef $/; eval $search; # this screams $/ = "\n"; # put back to normal input delimiter foreach $file (sort keys(%seen)) { print $file, "\n"; }
- sub NAME BLOCK
- sub NAME (PROTO) BLOCK
- sub NAME : ATTRS BLOCK
- sub NAME (PROTO) : ATTRS BLOCK
- This is subroutine definition, not a real function per
se. Without a BLOCK it's just a forward declaration. Without a NAME,
it's an anonymous function declaration, and does actually return a value:
the CODE ref of the closure you just created.
- substr EXPR,OFFSET,LENGTH,REPLACEMENT
- substr EXPR,OFFSET,LENGTH
- substr EXPR,OFFSET
- Extracts a substring out of EXPR and returns it. First
character is at offset 0, or whatever you've set $[ to (but don't do
that). If OFFSET is negative (or more precisely, less than $[), starts
that far from the end of the string. If LENGTH is omitted, returns
everything to the end of the string. If LENGTH is negative, leaves that
many characters off the end of the string.
my $name = 'fred'; substr($name, 4) = 'dy'; # $name is now 'freddy' my $null = substr $name, 6, 2; # returns '' (no warning) my $oops = substr $name, 7; # returns undef, with warning substr($name, 7) = 'gap'; # fatal error
- symlink OLDFILE,NEWFILE
- Creates a new filename symbolically linked to the old
filename. Returns 1 for success, 0 otherwise. On systems that don't
support symbolic links, produces a fatal error at run time. To check for
that, use eval:
$symlink_exists = eval { symlink("",""); 1 };
- syscall NUMBER, LIST
- Calls the system call specified as the first element of the
list, passing the remaining elements as arguments to the system call. If
unimplemented, produces a fatal error. The arguments are interpreted as
follows: if a given argument is numeric, the argument is passed as an int.
If not, the pointer to the string value is passed. You are responsible to
make sure a string is pre-extended long enough to receive any result that
might be written into a string. You can't use a string literal (or other
read-only string) as an argument to "syscall" because Perl has
to assume that any string pointer might be written through. If your
integer arguments are not literals and have never been interpreted in a
numeric context, you may need to add 0 to them to force them to look like
numbers. This emulates the "syswrite" function (or vice versa):
require 'syscall.ph'; # may need to run h2ph $s = "hi there\n"; syscall(&SYS_write, fileno(STDOUT), $s, length $s);
- sysopen FILEHANDLE,FILENAME,MODE
- sysopen FILEHANDLE,FILENAME,MODE,PERMS
- Opens the file whose filename is given by FILENAME, and
associates it with FILEHANDLE. If FILEHANDLE is an expression, its value
is used as the name of the real filehandle wanted. This function calls the
underlying operating system's "open" function with the
parameters FILENAME, MODE, PERMS.
- 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 buffered IO, so mixing this with other kinds of reads,
"print", "write", "seek", "tell",
or "eof" can cause confusion because the perlio or stdio layers
usually buffers data. Returns the number of bytes actually read, 0 at end
of file, or undef if there was an error (in the latter case $! is also
set). SCALAR will be grown or shrunk so that the last byte actually read
is the last byte of the scalar after the read.
- sysseek FILEHANDLE,POSITION,WHENCE
- Sets FILEHANDLE's system position in bytes using the system
call lseek(2). FILEHANDLE may be an expression whose value gives
the name of the filehandle. The values for WHENCE are 0 to set the new
position to POSITION, 1 to set the it to the current position plus
POSITION, and 2 to set it to EOF plus POSITION (typically negative).
use Fcntl 'SEEK_CUR'; sub systell { sysseek($_[0], 0, SEEK_CUR) }
- system LIST
- system PROGRAM LIST
- Does exactly the same thing as "exec LIST",
except that a fork is done first, and the parent process waits for the
child process to complete. Note that argument processing varies depending
on the number of arguments. If there is more than one argument in LIST, or
if LIST is an array with more than one value, starts the program given by
the first element of the list with arguments given by the rest of the
list. If there is only one scalar argument, the argument is checked for
shell metacharacters, and if there are any, the entire argument is passed
to the system's command shell for parsing (this is "/bin/sh -c"
on Unix platforms, but varies on other platforms). If there are no shell
metacharacters in the argument, it is split into words and passed directly
to "execvp", which is more efficient.
@args = ("command", "arg1", "arg2"); system(@args) == 0 or die "system @args failed: $?"
if ($? == -1) { print "failed to execute: $!\n"; } elsif ($? & 127) { printf "child died with signal %d, %s coredump\n", ($? & 127), ($? & 128) ? 'with' : 'without'; } else { printf "child exited with value %d\n", $? >> 8; }
- syswrite FILEHANDLE,SCALAR,LENGTH,OFFSET
- syswrite FILEHANDLE,SCALAR,LENGTH
- syswrite FILEHANDLE,SCALAR
- Attempts to write LENGTH bytes of data from variable SCALAR
to the specified FILEHANDLE, using the system call write(2). If
LENGTH is not specified, writes whole SCALAR. It bypasses buffered IO, so
mixing this with reads (other than sysread()), "print",
"write", "seek", "tell", or "eof"
may cause confusion because the perlio and stdio layers usually buffers
data. Returns the number of bytes actually written, or "undef"
if there was an error (in this case the errno variable $! is also set). If
the LENGTH is greater than the available data in the SCALAR after the
OFFSET, only as much data as is available will be written.
- tell FILEHANDLE
- tell
- Returns the current position in bytes for
FILEHANDLE, or -1 on error. FILEHANDLE may be an expression whose value
gives the name of the actual filehandle. If FILEHANDLE is omitted, assumes
the file last read.
- telldir DIRHANDLE
- Returns the current position of the "readdir" routines on DIRHANDLE. Value may be given to "seekdir" to access a particular location in a directory. Has the same caveats about possible directory compaction as the corresponding system library routine.
- tie VARIABLE,CLASSNAME,LIST
- This function binds a variable to a package class that will
provide the implementation for the variable. VARIABLE is the name of the
variable to be enchanted. CLASSNAME is the name of a class implementing
objects of correct type. Any additional arguments are passed to the
"new" method of the class (meaning "TIESCALAR",
"TIEHANDLE", "TIEARRAY", or "TIEHASH").
Typically these are arguments such as might be passed to the
"dbm_open()" function of C. The object returned by the
"new" method is also returned by the "tie" function,
which would be useful if you want to access other methods in CLASSNAME.
# print out history file offsets use NDBM_File; tie(%HIST, 'NDBM_File', '/usr/lib/news/history', 1, 0); while (($key,$val) = each %HIST) { print $key, ' = ', unpack('L',$val), "\n"; } untie(%HIST);
TIEHASH classname, LIST FETCH this, key STORE this, key, value DELETE this, key CLEAR this EXISTS this, key FIRSTKEY this NEXTKEY this, lastkey DESTROY this UNTIE this
TIEARRAY classname, LIST FETCH this, key STORE this, key, value FETCHSIZE this STORESIZE this, count CLEAR this PUSH this, LIST POP this SHIFT this UNSHIFT this, LIST SPLICE this, offset, length, LIST EXTEND this, count DESTROY this UNTIE this
TIEHANDLE classname, LIST READ this, scalar, length, offset READLINE this GETC this WRITE this, scalar, length, offset PRINT this, LIST PRINTF this, format, LIST BINMODE this EOF this FILENO this SEEK this, position, whence TELL this OPEN this, mode, LIST CLOSE this DESTROY this UNTIE this
TIESCALAR classname, LIST FETCH this, STORE this, value DESTROY this UNTIE this
- tied VARIABLE
- Returns a reference to the object underlying VARIABLE (the same value that was originally returned by the "tie" call that bound the variable to a package.) Returns the undefined value if VARIABLE isn't tied to a package.
- time
- Returns the number of non-leap seconds since whatever time
the system considers to be the epoch (that's 00:00:00, January 1, 1904 for
Mac OS, and 00:00:00 UTC, January 1, 1970 for most other systems).
Suitable for feeding to "gmtime" and "localtime".
- times
- Returns a four-element list giving the user and system
times, in seconds, for this process and the children of this process.
($user,$system,$cuser,$csystem) = times;
- tr///
- The transliteration operator. Same as "y///". See perlop.
- truncate FILEHANDLE,LENGTH
- truncate EXPR,LENGTH
- Truncates the file opened on FILEHANDLE, or named by EXPR,
to the specified length. Produces a fatal error if truncate isn't
implemented on your system. Returns true if successful, the undefined
value otherwise.
- uc EXPR
- uc
- Returns an uppercased version of EXPR. This is the internal
function implementing the "\U" escape in double-quoted strings.
Respects current LC_CTYPE locale if "use locale" in force. See
perllocale and perlunicode for more details about locale and Unicode
support. It does not attempt to do titlecase mapping on initial letters.
See "ucfirst" for that.
- ucfirst EXPR
- ucfirst
- Returns the value of EXPR with the first character in
uppercase (titlecase in Unicode). This is the internal function
implementing the "\u" escape in double-quoted strings. Respects
current LC_CTYPE locale if "use locale" in force. See perllocale
and perlunicode for more details about locale and Unicode support.
- umask EXPR
- umask
- Sets the umask for the process to EXPR and returns the
previous value. If EXPR is omitted, merely returns the current umask.
- undef EXPR
- undef
- Undefines the value of EXPR, which must be an lvalue. Use
only on a scalar value, an array (using "@"), a hash (using
"%"), a subroutine (using "&"), or a typeglob
(using "*"). (Saying "undef $hash{$key}" will probably
not do what you expect on most predefined variables or DBM list values, so
don't do that; see delete.) Always returns the undefined value. You can
omit the EXPR, in which case nothing is undefined, but you still get an
undefined value that you could, for instance, return from a subroutine,
assign to a variable or pass as a parameter. Examples:
undef $foo; undef $bar{'blurfl'}; # Compare to: delete $bar{'blurfl'}; undef @ary; undef %hash; undef &mysub; undef *xyz; # destroys $xyz, @xyz, %xyz, &xyz, etc. return (wantarray ? (undef, $errmsg) : undef) if $they_blew_it; select undef, undef, undef, 0.25; ($a, $b, undef, $c) = &foo; # Ignore third value returned
- unlink LIST
- unlink
- Deletes a list of files. Returns the number of files
successfully deleted.
$cnt = unlink 'a', 'b', 'c'; unlink @goners; unlink <*.bak>;
- unpack TEMPLATE,EXPR
- "unpack" does the reverse of "pack": it
takes a string and expands it out into a list of values. (In scalar
context, it returns merely the first value produced.)
sub substr { my($what,$where,$howmuch) = @_; unpack("x$where a$howmuch", $what); }
sub ordinal { unpack("c",$_[0]); } # same as ord()
$checksum = do { local $/; # slurp! unpack("%32C*",<>) % 65535; };
$setbits = unpack("%32b*", $selectmask);
- untie VARIABLE
- Breaks the binding between a variable and a package. (See "tie".) Has no effect if the variable is not tied.
- unshift ARRAY,LIST
- Does the opposite of a "shift". Or the opposite
of a "push", depending on how you look at it. Prepends list to
the front of the array, and returns the new number of elements in the
array.
unshift(@ARGV, '-e') unless $ARGV[0] =~ /^-/;
- use Module VERSION LIST
- use Module VERSION
- use Module LIST
- use Module
- use VERSION
- Imports some semantics into the current package from the
named module, generally by aliasing certain subroutine or variable names
into your package. It is exactly equivalent to
BEGIN { require Module; import Module LIST; }
use v5.6.1; # compile time version check use 5.6.1; # ditto use 5.006_001; # ditto; preferred for backwards compatibility
use Module ();
BEGIN { require Module }
use constant; use diagnostics; use integer; use sigtrap qw(SEGV BUS); use strict qw(subs vars refs); use subs qw(afunc blurfl); use warnings qw(all); use sort qw(stable _quicksort _mergesort);
no integer; no strict 'refs'; no warnings;
- utime LIST
- Changes the access and modification times on each file of a
list of files. The first two elements of the list must be the NUMERICAL
access and modification times, in that order. Returns the number of files
successfully changed. The inode change time of each file is set to the
current time. For example, this code has the same effect as the Unix
touch(1) command when the files already exist.
#!/usr/bin/perl $now = time; utime $now, $now, @ARGV;
utime undef, undef, @ARGV;
- values HASH
- Returns a list consisting of all the values of the named
hash. (In a scalar context, returns the number of values.)
for (values %hash) { s/foo/bar/g } # modifies %hash values for (@hash{keys %hash}) { s/foo/bar/g } # same
- vec EXPR,OFFSET,BITS
- Treats the string in EXPR as a bit vector made up of
elements of width BITS, and returns the value of the element specified by
OFFSET as an unsigned integer. BITS therefore specifies the number of bits
that are reserved for each element in the bit vector. This must be a power
of two from 1 to 32 (or 64, if your platform supports that).
vec($image, $max_x * $x + $y, 8) = 3;
my $foo = ''; vec($foo, 0, 32) = 0x5065726C; # 'Perl'
# $foo eq "Perl" eq "\x50\x65\x72\x6C", 32 bits print vec($foo, 0, 8); # prints 80 == 0x50 == ord('P')
vec($foo, 2, 16) = 0x5065; # 'PerlPe' vec($foo, 3, 16) = 0x726C; # 'PerlPerl' vec($foo, 8, 8) = 0x50; # 'PerlPerlP' vec($foo, 9, 8) = 0x65; # 'PerlPerlPe' vec($foo, 20, 4) = 2; # 'PerlPerlPe' . "\x02" vec($foo, 21, 4) = 7; # 'PerlPerlPer' # 'r' is "\x72" vec($foo, 45, 2) = 3; # 'PerlPerlPer' . "\x0c" vec($foo, 93, 1) = 1; # 'PerlPerlPer' . "\x2c" vec($foo, 94, 1) = 1; # 'PerlPerlPerl' # 'l' is "\x6c"
$bits = unpack("b*", $vector); @bits = split(//, unpack("b*", $vector));
#!/usr/bin/perl -wl
print <<'EOT'; 0 1 2 3 unpack("V",$_) 01234567890123456789012345678901 ------------------------------------------------------------------ EOT
for $w (0..3) { $width = 2**$w; for ($shift=0; $shift < $width; ++$shift) { for ($off=0; $off < 32/$width; ++$off) { $str = pack("B*", "0"x32); $bits = (1<<$shift); vec($str, $off, $width) = $bits; $res = unpack("b*",$str); $val = unpack("V", $str); write; } } }
format STDOUT = vec($_,@#,@#) = @<< == @######### @>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> $off, $width, $bits, $val, $res . __END__
0 1 2 3 unpack("V",$_) 01234567890123456789012345678901 ------------------------------------------------------------------ vec($_, 0, 1) = 1 == 1 10000000000000000000000000000000 vec($_, 1, 1) = 1 == 2 01000000000000000000000000000000 vec($_, 2, 1) = 1 == 4 00100000000000000000000000000000 vec($_, 3, 1) = 1 == 8 00010000000000000000000000000000 vec($_, 4, 1) = 1 == 16 00001000000000000000000000000000 vec($_, 5, 1) = 1 == 32 00000100000000000000000000000000 vec($_, 6, 1) = 1 == 64 00000010000000000000000000000000 vec($_, 7, 1) = 1 == 128 00000001000000000000000000000000 vec($_, 8, 1) = 1 == 256 00000000100000000000000000000000 vec($_, 9, 1) = 1 == 512 00000000010000000000000000000000 vec($_,10, 1) = 1 == 1024 00000000001000000000000000000000 vec($_,11, 1) = 1 == 2048 00000000000100000000000000000000 vec($_,12, 1) = 1 == 4096 00000000000010000000000000000000 vec($_,13, 1) = 1 == 8192 00000000000001000000000000000000 vec($_,14, 1) = 1 == 16384 00000000000000100000000000000000 vec($_,15, 1) = 1 == 32768 00000000000000010000000000000000 vec($_,16, 1) = 1 == 65536 00000000000000001000000000000000 vec($_,17, 1) = 1 == 131072 00000000000000000100000000000000 vec($_,18, 1) = 1 == 262144 00000000000000000010000000000000 vec($_,19, 1) = 1 == 524288 00000000000000000001000000000000 vec($_,20, 1) = 1 == 1048576 00000000000000000000100000000000 vec($_,21, 1) = 1 == 2097152 00000000000000000000010000000000 vec($_,22, 1) = 1 == 4194304 00000000000000000000001000000000 vec($_,23, 1) = 1 == 8388608 00000000000000000000000100000000 vec($_,24, 1) = 1 == 16777216 00000000000000000000000010000000 vec($_,25, 1) = 1 == 33554432 00000000000000000000000001000000 vec($_,26, 1) = 1 == 67108864 00000000000000000000000000100000 vec($_,27, 1) = 1 == 134217728 00000000000000000000000000010000 vec($_,28, 1) = 1 == 268435456 00000000000000000000000000001000 vec($_,29, 1) = 1 == 536870912 00000000000000000000000000000100 vec($_,30, 1) = 1 == 1073741824 00000000000000000000000000000010 vec($_,31, 1) = 1 == 2147483648 00000000000000000000000000000001 vec($_, 0, 2) = 1 == 1 10000000000000000000000000000000 vec($_, 1, 2) = 1 == 4 00100000000000000000000000000000 vec($_, 2, 2) = 1 == 16 00001000000000000000000000000000 vec($_, 3, 2) = 1 == 64 00000010000000000000000000000000 vec($_, 4, 2) = 1 == 256 00000000100000000000000000000000 vec($_, 5, 2) = 1 == 1024 00000000001000000000000000000000 vec($_, 6, 2) = 1 == 4096 00000000000010000000000000000000 vec($_, 7, 2) = 1 == 16384 00000000000000100000000000000000 vec($_, 8, 2) = 1 == 65536 00000000000000001000000000000000 vec($_, 9, 2) = 1 == 262144 00000000000000000010000000000000 vec($_,10, 2) = 1 == 1048576 00000000000000000000100000000000 vec($_,11, 2) = 1 == 4194304 00000000000000000000001000000000 vec($_,12, 2) = 1 == 16777216 00000000000000000000000010000000 vec($_,13, 2) = 1 == 67108864 00000000000000000000000000100000 vec($_,14, 2) = 1 == 268435456 00000000000000000000000000001000 vec($_,15, 2) = 1 == 1073741824 00000000000000000000000000000010 vec($_, 0, 2) = 2 == 2 01000000000000000000000000000000 vec($_, 1, 2) = 2 == 8 00010000000000000000000000000000 vec($_, 2, 2) = 2 == 32 00000100000000000000000000000000 vec($_, 3, 2) = 2 == 128 00000001000000000000000000000000 vec($_, 4, 2) = 2 == 512 00000000010000000000000000000000 vec($_, 5, 2) = 2 == 2048 00000000000100000000000000000000 vec($_, 6, 2) = 2 == 8192 00000000000001000000000000000000 vec($_, 7, 2) = 2 == 32768 00000000000000010000000000000000 vec($_, 8, 2) = 2 == 131072 00000000000000000100000000000000 vec($_, 9, 2) = 2 == 524288 00000000000000000001000000000000 vec($_,10, 2) = 2 == 2097152 00000000000000000000010000000000 vec($_,11, 2) = 2 == 8388608 00000000000000000000000100000000 vec($_,12, 2) = 2 == 33554432 00000000000000000000000001000000 vec($_,13, 2) = 2 == 134217728 00000000000000000000000000010000 vec($_,14, 2) = 2 == 536870912 00000000000000000000000000000100 vec($_,15, 2) = 2 == 2147483648 00000000000000000000000000000001 vec($_, 0, 4) = 1 == 1 10000000000000000000000000000000 vec($_, 1, 4) = 1 == 16 00001000000000000000000000000000 vec($_, 2, 4) = 1 == 256 00000000100000000000000000000000 vec($_, 3, 4) = 1 == 4096 00000000000010000000000000000000 vec($_, 4, 4) = 1 == 65536 00000000000000001000000000000000 vec($_, 5, 4) = 1 == 1048576 00000000000000000000100000000000 vec($_, 6, 4) = 1 == 16777216 00000000000000000000000010000000 vec($_, 7, 4) = 1 == 268435456 00000000000000000000000000001000 vec($_, 0, 4) = 2 == 2 01000000000000000000000000000000 vec($_, 1, 4) = 2 == 32 00000100000000000000000000000000 vec($_, 2, 4) = 2 == 512 00000000010000000000000000000000 vec($_, 3, 4) = 2 == 8192 00000000000001000000000000000000 vec($_, 4, 4) = 2 == 131072 00000000000000000100000000000000 vec($_, 5, 4) = 2 == 2097152 00000000000000000000010000000000 vec($_, 6, 4) = 2 == 33554432 00000000000000000000000001000000 vec($_, 7, 4) = 2 == 536870912 00000000000000000000000000000100 vec($_, 0, 4) = 4 == 4 00100000000000000000000000000000 vec($_, 1, 4) = 4 == 64 00000010000000000000000000000000 vec($_, 2, 4) = 4 == 1024 00000000001000000000000000000000 vec($_, 3, 4) = 4 == 16384 00000000000000100000000000000000 vec($_, 4, 4) = 4 == 262144 00000000000000000010000000000000 vec($_, 5, 4) = 4 == 4194304 00000000000000000000001000000000 vec($_, 6, 4) = 4 == 67108864 00000000000000000000000000100000 vec($_, 7, 4) = 4 == 1073741824 00000000000000000000000000000010 vec($_, 0, 4) = 8 == 8 00010000000000000000000000000000 vec($_, 1, 4) = 8 == 128 00000001000000000000000000000000 vec($_, 2, 4) = 8 == 2048 00000000000100000000000000000000 vec($_, 3, 4) = 8 == 32768 00000000000000010000000000000000 vec($_, 4, 4) = 8 == 524288 00000000000000000001000000000000 vec($_, 5, 4) = 8 == 8388608 00000000000000000000000100000000 vec($_, 6, 4) = 8 == 134217728 00000000000000000000000000010000 vec($_, 7, 4) = 8 == 2147483648 00000000000000000000000000000001 vec($_, 0, 8) = 1 == 1 10000000000000000000000000000000 vec($_, 1, 8) = 1 == 256 00000000100000000000000000000000 vec($_, 2, 8) = 1 == 65536 00000000000000001000000000000000 vec($_, 3, 8) = 1 == 16777216 00000000000000000000000010000000 vec($_, 0, 8) = 2 == 2 01000000000000000000000000000000 vec($_, 1, 8) = 2 == 512 00000000010000000000000000000000 vec($_, 2, 8) = 2 == 131072 00000000000000000100000000000000 vec($_, 3, 8) = 2 == 33554432 00000000000000000000000001000000 vec($_, 0, 8) = 4 == 4 00100000000000000000000000000000 vec($_, 1, 8) = 4 == 1024 00000000001000000000000000000000 vec($_, 2, 8) = 4 == 262144 00000000000000000010000000000000 vec($_, 3, 8) = 4 == 67108864 00000000000000000000000000100000 vec($_, 0, 8) = 8 == 8 00010000000000000000000000000000 vec($_, 1, 8) = 8 == 2048 00000000000100000000000000000000 vec($_, 2, 8) = 8 == 524288 00000000000000000001000000000000 vec($_, 3, 8) = 8 == 134217728 00000000000000000000000000010000 vec($_, 0, 8) = 16 == 16 00001000000000000000000000000000 vec($_, 1, 8) = 16 == 4096 00000000000010000000000000000000 vec($_, 2, 8) = 16 == 1048576 00000000000000000000100000000000 vec($_, 3, 8) = 16 == 268435456 00000000000000000000000000001000 vec($_, 0, 8) = 32 == 32 00000100000000000000000000000000 vec($_, 1, 8) = 32 == 8192 00000000000001000000000000000000 vec($_, 2, 8) = 32 == 2097152 00000000000000000000010000000000 vec($_, 3, 8) = 32 == 536870912 00000000000000000000000000000100 vec($_, 0, 8) = 64 == 64 00000010000000000000000000000000 vec($_, 1, 8) = 64 == 16384 00000000000000100000000000000000 vec($_, 2, 8) = 64 == 4194304 00000000000000000000001000000000 vec($_, 3, 8) = 64 == 1073741824 00000000000000000000000000000010 vec($_, 0, 8) = 128 == 128 00000001000000000000000000000000 vec($_, 1, 8) = 128 == 32768 00000000000000010000000000000000 vec($_, 2, 8) = 128 == 8388608 00000000000000000000000100000000 vec($_, 3, 8) = 128 == 2147483648 00000000000000000000000000000001
- wait
- Behaves like the wait(2) system call on your system: it waits for a child process to terminate and returns the pid of the deceased process, or "-1" if there are no child processes. The status is returned in $?. Note that a return value of "-1" could mean that child processes are being automatically reaped, as described in perlipc.
- waitpid PID,FLAGS
- Waits for a particular child process to terminate and
returns the pid of the deceased process, or "-1" if there is no
such child process. On some systems, a value of 0 indicates that there are
processes still running. The status is returned in $?. If you say
use POSIX ":sys_wait_h"; #... do { $kid = waitpid(-1, WNOHANG); } until $kid > 0;
- wantarray
- Returns true if the context of the currently executing
subroutine is looking for a list value. Returns false if the context is
looking for a scalar. Returns the undefined value if the context is
looking for no value (void context).
return unless defined wantarray; # don't bother doing more my @a = complex_calculation(); return wantarray ? @a : "@a";
- warn LIST
- Produces a message on STDERR just like "die", but
doesn't exit or throw an exception.
# wipe out *all* compile-time warnings BEGIN { $SIG{'__WARN__'} = sub { warn $_[0] if $DOWARN } } my $foo = 10; my $foo = 20; # no warning about duplicate my $foo, # but hey, you asked for it! # no compile-time or run-time warnings before here $DOWARN = 1;
# run-time warnings enabled after here warn "\$foo is alive and $foo!"; # does show up
- write FILEHANDLE
- write EXPR
- write
- Writes a formatted record (possibly multi-line) to the
specified FILEHANDLE, using the format associated with that file. By
default the format for a file is the one having the same name as the
filehandle, but the format for the current output channel (see the
"select" function) may be set explicitly by assigning the name
of the format to the $~ variable.
- y///
- The transliteration operator. Same as "tr///". See perlop.
2003-09-02 | perl v5.8.1 |