diff options
Diffstat (limited to 'tests/examplefiles/perlfunc.1')
| -rw-r--r-- | tests/examplefiles/perlfunc.1 | 856 |
1 files changed, 0 insertions, 856 deletions
diff --git a/tests/examplefiles/perlfunc.1 b/tests/examplefiles/perlfunc.1 deleted file mode 100644 index 5f80f0d0..00000000 --- a/tests/examplefiles/perlfunc.1 +++ /dev/null @@ -1,856 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "PERLFUNC 1" -.TH PERLFUNC 1 "2006-01-07" "perl v5.8.8" "Perl Programmers Reference Guide" -.SH "NAME" -.IX Xref "function" -perlfunc \- Perl builtin functions -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -The functions in this section can serve as terms in an expression. -They fall into two major categories: list operators and named unary -operators. These differ in their precedence relationship with a -following comma. (See the precedence table in perlop.) List -operators take more than one argument, while unary operators can never -take more than one argument. Thus, a comma terminates the argument of -a unary operator, but merely separates the arguments of a list -operator. A unary operator generally provides a scalar context to its -argument, while a list operator may provide either scalar or list -contexts for its arguments. If it does both, the scalar arguments will -be first, and the list argument will follow. (Note that there can ever -be only one such list argument.) For instance, \fIsplice()\fR has three scalar -arguments followed by a list, whereas \fIgethostbyname()\fR has four scalar -arguments. -.PP -In the syntax descriptions that follow, list operators that expect a -list (and provide list context for the elements of the list) are shown -with \s-1LIST\s0 as an argument. Such a list may consist of any combination -of scalar arguments or list values; the list values will be included -in the list as if each individual element were interpolated at that -point in the list, forming a longer single-dimensional list value. -Commas should separate elements of the \s-1LIST\s0. -.PP -Any function in the list below may be used either with or without -parentheses around its arguments. (The syntax descriptions omit the -parentheses.) If you use the parentheses, the simple (but occasionally -surprising) rule is this: It \fIlooks\fR like a function, therefore it \fIis\fR a -function, and precedence doesn't matter. Otherwise it's a list -operator or unary operator, and precedence does matter. And whitespace -between the function and left parenthesis doesn't count\*(--so you need to -be careful sometimes: -.PP -.Vb 5 -\& 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. -.Ve -.PP -If you run Perl with the \fB\-w\fR switch it can warn you about this. For -example, the third line above produces: -.PP -.Vb 2 -\& print (...) interpreted as function at - line 1. -\& Useless use of integer addition in void context at - line 1. -.Ve -.PP -A few functions take no arguments at all, and therefore work as neither -unary nor list operators. These include such functions as \f(CW\*(C`time\*(C'\fR -and \f(CW\*(C`endpwent\*(C'\fR. For example, \f(CW\*(C`time+86_400\*(C'\fR always means -\&\f(CW\*(C`time() + 86_400\*(C'\fR. -.PP -For functions that can be used in either a scalar or list context, -nonabortive failure is generally indicated in a scalar context by -returning the undefined value, and in a list context by returning the -null list. -.PP -Remember the following important rule: There is \fBno rule\fR that relates -the behavior of an expression in list context to its behavior in scalar -context, or vice versa. It might do two totally different things. -Each operator and function decides which sort of value it would be most -appropriate to return in scalar context. Some operators return the -length of the list that would have been returned in list context. Some -operators return the first value in the list. Some operators return the -last value in the list. Some operators return a count of successful -operations. In general, they do what you want, unless you want -consistency. -.IX Xref "context" -.PP -A named array in scalar context is quite different from what would at -first glance appear to be a list in scalar context. You can't get a list -like \f(CW\*(C`(1,2,3)\*(C'\fR into being in scalar context, because the compiler knows -the context at compile time. It would generate the scalar comma operator -there, not the list construction version of the comma. That means it -was never a list to start with. -.PP -In general, functions in Perl that serve as wrappers for system calls -of the same name (like \fIchown\fR\|(2), \fIfork\fR\|(2), \fIclosedir\fR\|(2), etc.) all return -true when they succeed and \f(CW\*(C`undef\*(C'\fR otherwise, as is usually mentioned -in the descriptions below. This is different from the C interfaces, -which return \f(CW\*(C`\-1\*(C'\fR on failure. Exceptions to this rule are \f(CW\*(C`wait\*(C'\fR, -\&\f(CW\*(C`waitpid\*(C'\fR, and \f(CW\*(C`syscall\*(C'\fR. System calls also set the special \f(CW$!\fR -variable on failure. Other functions do not, except accidentally. -.Sh "Perl Functions by Category" -.IX Xref "function" -.IX Subsection "Perl Functions by Category" -Here are Perl's functions (including things that look like -functions, like some keywords and named operators) -arranged by category. Some functions appear in more -than one place. -.IP "Functions for SCALARs or strings" 4 -.IX Xref "scalar string character" -.IX Item "Functions for SCALARs or strings" -\&\f(CW\*(C`chomp\*(C'\fR, \f(CW\*(C`chop\*(C'\fR, \f(CW\*(C`chr\*(C'\fR, \f(CW\*(C`crypt\*(C'\fR, \f(CW\*(C`hex\*(C'\fR, \f(CW\*(C`index\*(C'\fR, \f(CW\*(C`lc\*(C'\fR, \f(CW\*(C`lcfirst\*(C'\fR, -\&\f(CW\*(C`length\*(C'\fR, \f(CW\*(C`oct\*(C'\fR, \f(CW\*(C`ord\*(C'\fR, \f(CW\*(C`pack\*(C'\fR, \f(CW\*(C`q/STRING/\*(C'\fR, \f(CW\*(C`qq/STRING/\*(C'\fR, \f(CW\*(C`reverse\*(C'\fR, -\&\f(CW\*(C`rindex\*(C'\fR, \f(CW\*(C`sprintf\*(C'\fR, \f(CW\*(C`substr\*(C'\fR, \f(CW\*(C`tr///\*(C'\fR, \f(CW\*(C`uc\*(C'\fR, \f(CW\*(C`ucfirst\*(C'\fR, \f(CW\*(C`y///\*(C'\fR -.IP "Regular expressions and pattern matching" 4 -.IX Xref "regular expression regex regexp" -.IX Item "Regular expressions and pattern matching" -\&\f(CW\*(C`m//\*(C'\fR, \f(CW\*(C`pos\*(C'\fR, \f(CW\*(C`quotemeta\*(C'\fR, \f(CW\*(C`s///\*(C'\fR, \f(CW\*(C`split\*(C'\fR, \f(CW\*(C`study\*(C'\fR, \f(CW\*(C`qr//\*(C'\fR -.IP "Numeric functions" 4 -.IX Xref "numeric number trigonometric trigonometry" -.IX Item "Numeric functions" -\&\f(CW\*(C`abs\*(C'\fR, \f(CW\*(C`atan2\*(C'\fR, \f(CW\*(C`cos\*(C'\fR, \f(CW\*(C`exp\*(C'\fR, \f(CW\*(C`hex\*(C'\fR, \f(CW\*(C`int\*(C'\fR, \f(CW\*(C`log\*(C'\fR, \f(CW\*(C`oct\*(C'\fR, \f(CW\*(C`rand\*(C'\fR, -\&\f(CW\*(C`sin\*(C'\fR, \f(CW\*(C`sqrt\*(C'\fR, \f(CW\*(C`srand\*(C'\fR -.ie n .IP "Functions for real @ARRAYs" 4 -.el .IP "Functions for real \f(CW@ARRAYs\fR" 4 -.IX Xref "array" -.IX Item "Functions for real @ARRAYs" -\&\f(CW\*(C`pop\*(C'\fR, \f(CW\*(C`push\*(C'\fR, \f(CW\*(C`shift\*(C'\fR, \f(CW\*(C`splice\*(C'\fR, \f(CW\*(C`unshift\*(C'\fR -.IP "Functions for list data" 4 -.IX Xref "list" -.IX Item "Functions for list data" -\&\f(CW\*(C`grep\*(C'\fR, \f(CW\*(C`join\*(C'\fR, \f(CW\*(C`map\*(C'\fR, \f(CW\*(C`qw/STRING/\*(C'\fR, \f(CW\*(C`reverse\*(C'\fR, \f(CW\*(C`sort\*(C'\fR, \f(CW\*(C`unpack\*(C'\fR -.ie n .IP "Functions for real %HASHes" 4 -.el .IP "Functions for real \f(CW%HASHes\fR" 4 -.IX Xref "hash" -.IX Item "Functions for real %HASHes" -\&\f(CW\*(C`delete\*(C'\fR, \f(CW\*(C`each\*(C'\fR, \f(CW\*(C`exists\*(C'\fR, \f(CW\*(C`keys\*(C'\fR, \f(CW\*(C`values\*(C'\fR -.IP "Input and output functions" 4 -.IX Xref "I O input output dbm" -.IX Item "Input and output functions" -\&\f(CW\*(C`binmode\*(C'\fR, \f(CW\*(C`close\*(C'\fR, \f(CW\*(C`closedir\*(C'\fR, \f(CW\*(C`dbmclose\*(C'\fR, \f(CW\*(C`dbmopen\*(C'\fR, \f(CW\*(C`die\*(C'\fR, \f(CW\*(C`eof\*(C'\fR, -\&\f(CW\*(C`fileno\*(C'\fR, \f(CW\*(C`flock\*(C'\fR, \f(CW\*(C`format\*(C'\fR, \f(CW\*(C`getc\*(C'\fR, \f(CW\*(C`print\*(C'\fR, \f(CW\*(C`printf\*(C'\fR, \f(CW\*(C`read\*(C'\fR, -\&\f(CW\*(C`readdir\*(C'\fR, \f(CW\*(C`rewinddir\*(C'\fR, \f(CW\*(C`seek\*(C'\fR, \f(CW\*(C`seekdir\*(C'\fR, \f(CW\*(C`select\*(C'\fR, \f(CW\*(C`syscall\*(C'\fR, -\&\f(CW\*(C`sysread\*(C'\fR, \f(CW\*(C`sysseek\*(C'\fR, \f(CW\*(C`syswrite\*(C'\fR, \f(CW\*(C`tell\*(C'\fR, \f(CW\*(C`telldir\*(C'\fR, \f(CW\*(C`truncate\*(C'\fR, -\&\f(CW\*(C`warn\*(C'\fR, \f(CW\*(C`write\*(C'\fR -.IP "Functions for fixed length data or records" 4 -.IX Item "Functions for fixed length data or records" -\&\f(CW\*(C`pack\*(C'\fR, \f(CW\*(C`read\*(C'\fR, \f(CW\*(C`syscall\*(C'\fR, \f(CW\*(C`sysread\*(C'\fR, \f(CW\*(C`syswrite\*(C'\fR, \f(CW\*(C`unpack\*(C'\fR, \f(CW\*(C`vec\*(C'\fR -.IP "Functions for filehandles, files, or directories" 4 -.IX Xref "file filehandle directory pipe link symlink" -.IX Item "Functions for filehandles, files, or directories" -\&\f(CW\*(C`\-\f(CIX\f(CW\*(C'\fR, \f(CW\*(C`chdir\*(C'\fR, \f(CW\*(C`chmod\*(C'\fR, \f(CW\*(C`chown\*(C'\fR, \f(CW\*(C`chroot\*(C'\fR, \f(CW\*(C`fcntl\*(C'\fR, \f(CW\*(C`glob\*(C'\fR, -\&\f(CW\*(C`ioctl\*(C'\fR, \f(CW\*(C`link\*(C'\fR, \f(CW\*(C`lstat\*(C'\fR, \f(CW\*(C`mkdir\*(C'\fR, \f(CW\*(C`open\*(C'\fR, \f(CW\*(C`opendir\*(C'\fR, -\&\f(CW\*(C`readlink\*(C'\fR, \f(CW\*(C`rename\*(C'\fR, \f(CW\*(C`rmdir\*(C'\fR, \f(CW\*(C`stat\*(C'\fR, \f(CW\*(C`symlink\*(C'\fR, \f(CW\*(C`sysopen\*(C'\fR, -\&\f(CW\*(C`umask\*(C'\fR, \f(CW\*(C`unlink\*(C'\fR, \f(CW\*(C`utime\*(C'\fR -.IP "Keywords related to the control flow of your Perl program" 4 -.IX Xref "control flow" -.IX Item "Keywords related to the control flow of your Perl program" -\&\f(CW\*(C`caller\*(C'\fR, \f(CW\*(C`continue\*(C'\fR, \f(CW\*(C`die\*(C'\fR, \f(CW\*(C`do\*(C'\fR, \f(CW\*(C`dump\*(C'\fR, \f(CW\*(C`eval\*(C'\fR, \f(CW\*(C`exit\*(C'\fR, -\&\f(CW\*(C`goto\*(C'\fR, \f(CW\*(C`last\*(C'\fR, \f(CW\*(C`next\*(C'\fR, \f(CW\*(C`redo\*(C'\fR, \f(CW\*(C`return\*(C'\fR, \f(CW\*(C`sub\*(C'\fR, \f(CW\*(C`wantarray\*(C'\fR -.IP "Keywords related to scoping" 4 -.IX Item "Keywords related to scoping" -\&\f(CW\*(C`caller\*(C'\fR, \f(CW\*(C`import\*(C'\fR, \f(CW\*(C`local\*(C'\fR, \f(CW\*(C`my\*(C'\fR, \f(CW\*(C`our\*(C'\fR, \f(CW\*(C`package\*(C'\fR, \f(CW\*(C`use\*(C'\fR -.IP "Miscellaneous functions" 4 -.IX Item "Miscellaneous functions" -\&\f(CW\*(C`defined\*(C'\fR, \f(CW\*(C`dump\*(C'\fR, \f(CW\*(C`eval\*(C'\fR, \f(CW\*(C`formline\*(C'\fR, \f(CW\*(C`local\*(C'\fR, \f(CW\*(C`my\*(C'\fR, \f(CW\*(C`our\*(C'\fR, \f(CW\*(C`reset\*(C'\fR, -\&\f(CW\*(C`scalar\*(C'\fR, \f(CW\*(C`undef\*(C'\fR, \f(CW\*(C`wantarray\*(C'\fR -.IP "Functions for processes and process groups" 4 -.IX Xref "process pid process id" -.IX Item "Functions for processes and process groups" -\&\f(CW\*(C`alarm\*(C'\fR, \f(CW\*(C`exec\*(C'\fR, \f(CW\*(C`fork\*(C'\fR, \f(CW\*(C`getpgrp\*(C'\fR, \f(CW\*(C`getppid\*(C'\fR, \f(CW\*(C`getpriority\*(C'\fR, \f(CW\*(C`kill\*(C'\fR, -\&\f(CW\*(C`pipe\*(C'\fR, \f(CW\*(C`qx/STRING/\*(C'\fR, \f(CW\*(C`setpgrp\*(C'\fR, \f(CW\*(C`setpriority\*(C'\fR, \f(CW\*(C`sleep\*(C'\fR, \f(CW\*(C`system\*(C'\fR, -\&\f(CW\*(C`times\*(C'\fR, \f(CW\*(C`wait\*(C'\fR, \f(CW\*(C`waitpid\*(C'\fR -.IP "Keywords related to perl modules" 4 -.IX Xref "module" -.IX Item "Keywords related to perl modules" -\&\f(CW\*(C`do\*(C'\fR, \f(CW\*(C`import\*(C'\fR, \f(CW\*(C`no\*(C'\fR, \f(CW\*(C`package\*(C'\fR, \f(CW\*(C`require\*(C'\fR, \f(CW\*(C`use\*(C'\fR -.IP "Keywords related to classes and object-orientedness" 4 -.IX Xref "object class package" -.IX Item "Keywords related to classes and object-orientedness" -\&\f(CW\*(C`bless\*(C'\fR, \f(CW\*(C`dbmclose\*(C'\fR, \f(CW\*(C`dbmopen\*(C'\fR, \f(CW\*(C`package\*(C'\fR, \f(CW\*(C`ref\*(C'\fR, \f(CW\*(C`tie\*(C'\fR, \f(CW\*(C`tied\*(C'\fR, -\&\f(CW\*(C`untie\*(C'\fR, \f(CW\*(C`use\*(C'\fR -.IP "Low-level socket functions" 4 -.IX Xref "socket sock" -.IX Item "Low-level socket functions" -\&\f(CW\*(C`accept\*(C'\fR, \f(CW\*(C`bind\*(C'\fR, \f(CW\*(C`connect\*(C'\fR, \f(CW\*(C`getpeername\*(C'\fR, \f(CW\*(C`getsockname\*(C'\fR, -\&\f(CW\*(C`getsockopt\*(C'\fR, \f(CW\*(C`listen\*(C'\fR, \f(CW\*(C`recv\*(C'\fR, \f(CW\*(C`send\*(C'\fR, \f(CW\*(C`setsockopt\*(C'\fR, \f(CW\*(C`shutdown\*(C'\fR, -\&\f(CW\*(C`socket\*(C'\fR, \f(CW\*(C`socketpair\*(C'\fR -.IP "System V interprocess communication functions" 4 -.IX Xref "IPC System V semaphore shared memory memory message" -.IX Item "System V interprocess communication functions" -\&\f(CW\*(C`msgctl\*(C'\fR, \f(CW\*(C`msgget\*(C'\fR, \f(CW\*(C`msgrcv\*(C'\fR, \f(CW\*(C`msgsnd\*(C'\fR, \f(CW\*(C`semctl\*(C'\fR, \f(CW\*(C`semget\*(C'\fR, \f(CW\*(C`semop\*(C'\fR, -\&\f(CW\*(C`shmctl\*(C'\fR, \f(CW\*(C`shmget\*(C'\fR, \f(CW\*(C`shmread\*(C'\fR, \f(CW\*(C`shmwrite\*(C'\fR -.IP "Fetching user and group info" 4 -.IX Xref "user group password uid gid passwd etc passwd" -.IX Item "Fetching user and group info" -\&\f(CW\*(C`endgrent\*(C'\fR, \f(CW\*(C`endhostent\*(C'\fR, \f(CW\*(C`endnetent\*(C'\fR, \f(CW\*(C`endpwent\*(C'\fR, \f(CW\*(C`getgrent\*(C'\fR, -\&\f(CW\*(C`getgrgid\*(C'\fR, \f(CW\*(C`getgrnam\*(C'\fR, \f(CW\*(C`getlogin\*(C'\fR, \f(CW\*(C`getpwent\*(C'\fR, \f(CW\*(C`getpwnam\*(C'\fR, -\&\f(CW\*(C`getpwuid\*(C'\fR, \f(CW\*(C`setgrent\*(C'\fR, \f(CW\*(C`setpwent\*(C'\fR -.IP "Fetching network info" 4 -.IX Xref "network protocol host hostname IP address service" -.IX Item "Fetching network info" -\&\f(CW\*(C`endprotoent\*(C'\fR, \f(CW\*(C`endservent\*(C'\fR, \f(CW\*(C`gethostbyaddr\*(C'\fR, \f(CW\*(C`gethostbyname\*(C'\fR, -\&\f(CW\*(C`gethostent\*(C'\fR, \f(CW\*(C`getnetbyaddr\*(C'\fR, \f(CW\*(C`getnetbyname\*(C'\fR, \f(CW\*(C`getnetent\*(C'\fR, -\&\f(CW\*(C`getprotobyname\*(C'\fR, \f(CW\*(C`getprotobynumber\*(C'\fR, \f(CW\*(C`getprotoent\*(C'\fR, -\&\f(CW\*(C`getservbyname\*(C'\fR, \f(CW\*(C`getservbyport\*(C'\fR, \f(CW\*(C`getservent\*(C'\fR, \f(CW\*(C`sethostent\*(C'\fR, -\&\f(CW\*(C`setnetent\*(C'\fR, \f(CW\*(C`setprotoent\*(C'\fR, \f(CW\*(C`setservent\*(C'\fR -.IP "Time-related functions" 4 -.IX Xref "time date" -.IX Item "Time-related functions" -\&\f(CW\*(C`gmtime\*(C'\fR, \f(CW\*(C`localtime\*(C'\fR, \f(CW\*(C`time\*(C'\fR, \f(CW\*(C`times\*(C'\fR -.IP "Functions new in perl5" 4 -.IX Xref "perl5" -.IX Item "Functions new in perl5" -\&\f(CW\*(C`abs\*(C'\fR, \f(CW\*(C`bless\*(C'\fR, \f(CW\*(C`chomp\*(C'\fR, \f(CW\*(C`chr\*(C'\fR, \f(CW\*(C`exists\*(C'\fR, \f(CW\*(C`formline\*(C'\fR, \f(CW\*(C`glob\*(C'\fR, -\&\f(CW\*(C`import\*(C'\fR, \f(CW\*(C`lc\*(C'\fR, \f(CW\*(C`lcfirst\*(C'\fR, \f(CW\*(C`map\*(C'\fR, \f(CW\*(C`my\*(C'\fR, \f(CW\*(C`no\*(C'\fR, \f(CW\*(C`our\*(C'\fR, \f(CW\*(C`prototype\*(C'\fR, -\&\f(CW\*(C`qx\*(C'\fR, \f(CW\*(C`qw\*(C'\fR, \f(CW\*(C`readline\*(C'\fR, \f(CW\*(C`readpipe\*(C'\fR, \f(CW\*(C`ref\*(C'\fR, \f(CW\*(C`sub*\*(C'\fR, \f(CW\*(C`sysopen\*(C'\fR, \f(CW\*(C`tie\*(C'\fR, -\&\f(CW\*(C`tied\*(C'\fR, \f(CW\*(C`uc\*(C'\fR, \f(CW\*(C`ucfirst\*(C'\fR, \f(CW\*(C`untie\*(C'\fR, \f(CW\*(C`use\*(C'\fR -.Sp -* \- \f(CW\*(C`sub\*(C'\fR was a keyword in perl4, but in perl5 it is an -operator, which can be used in expressions. -.IP "Functions obsoleted in perl5" 4 -.IX Item "Functions obsoleted in perl5" -\&\f(CW\*(C`dbmclose\*(C'\fR, \f(CW\*(C`dbmopen\*(C'\fR -.Sh "Portability" -.IX Xref "portability Unix portable" -.IX Subsection "Portability" -Perl was born in Unix and can therefore access all common Unix -system calls. In non-Unix environments, the functionality of some -Unix system calls may not be available, or details of the available -functionality may differ slightly. The Perl functions affected -by this are: -.PP -\&\f(CW\*(C`\-X\*(C'\fR, \f(CW\*(C`binmode\*(C'\fR, \f(CW\*(C`chmod\*(C'\fR, \f(CW\*(C`chown\*(C'\fR, \f(CW\*(C`chroot\*(C'\fR, \f(CW\*(C`crypt\*(C'\fR, -\&\f(CW\*(C`dbmclose\*(C'\fR, \f(CW\*(C`dbmopen\*(C'\fR, \f(CW\*(C`dump\*(C'\fR, \f(CW\*(C`endgrent\*(C'\fR, \f(CW\*(C`endhostent\*(C'\fR, -\&\f(CW\*(C`endnetent\*(C'\fR, \f(CW\*(C`endprotoent\*(C'\fR, \f(CW\*(C`endpwent\*(C'\fR, \f(CW\*(C`endservent\*(C'\fR, \f(CW\*(C`exec\*(C'\fR, -\&\f(CW\*(C`fcntl\*(C'\fR, \f(CW\*(C`flock\*(C'\fR, \f(CW\*(C`fork\*(C'\fR, \f(CW\*(C`getgrent\*(C'\fR, \f(CW\*(C`getgrgid\*(C'\fR, \f(CW\*(C`gethostbyname\*(C'\fR, -\&\f(CW\*(C`gethostent\*(C'\fR, \f(CW\*(C`getlogin\*(C'\fR, \f(CW\*(C`getnetbyaddr\*(C'\fR, \f(CW\*(C`getnetbyname\*(C'\fR, \f(CW\*(C`getnetent\*(C'\fR, -\&\f(CW\*(C`getppid\*(C'\fR, \f(CW\*(C`getpgrp\*(C'\fR, \f(CW\*(C`getpriority\*(C'\fR, \f(CW\*(C`getprotobynumber\*(C'\fR, -\&\f(CW\*(C`getprotoent\*(C'\fR, \f(CW\*(C`getpwent\*(C'\fR, \f(CW\*(C`getpwnam\*(C'\fR, \f(CW\*(C`getpwuid\*(C'\fR, -\&\f(CW\*(C`getservbyport\*(C'\fR, \f(CW\*(C`getservent\*(C'\fR, \f(CW\*(C`getsockopt\*(C'\fR, \f(CW\*(C`glob\*(C'\fR, \f(CW\*(C`ioctl\*(C'\fR, -\&\f(CW\*(C`kill\*(C'\fR, \f(CW\*(C`link\*(C'\fR, \f(CW\*(C`lstat\*(C'\fR, \f(CW\*(C`msgctl\*(C'\fR, \f(CW\*(C`msgget\*(C'\fR, \f(CW\*(C`msgrcv\*(C'\fR, -\&\f(CW\*(C`msgsnd\*(C'\fR, \f(CW\*(C`open\*(C'\fR, \f(CW\*(C`pipe\*(C'\fR, \f(CW\*(C`readlink\*(C'\fR, \f(CW\*(C`rename\*(C'\fR, \f(CW\*(C`select\*(C'\fR, \f(CW\*(C`semctl\*(C'\fR, -\&\f(CW\*(C`semget\*(C'\fR, \f(CW\*(C`semop\*(C'\fR, \f(CW\*(C`setgrent\*(C'\fR, \f(CW\*(C`sethostent\*(C'\fR, \f(CW\*(C`setnetent\*(C'\fR, -\&\f(CW\*(C`setpgrp\*(C'\fR, \f(CW\*(C`setpriority\*(C'\fR, \f(CW\*(C`setprotoent\*(C'\fR, \f(CW\*(C`setpwent\*(C'\fR, -\&\f(CW\*(C`setservent\*(C'\fR, \f(CW\*(C`setsockopt\*(C'\fR, \f(CW\*(C`shmctl\*(C'\fR, \f(CW\*(C`shmget\*(C'\fR, \f(CW\*(C`shmread\*(C'\fR, -\&\f(CW\*(C`shmwrite\*(C'\fR, \f(CW\*(C`socket\*(C'\fR, \f(CW\*(C`socketpair\*(C'\fR, -\&\f(CW\*(C`stat\*(C'\fR, \f(CW\*(C`symlink\*(C'\fR, \f(CW\*(C`syscall\*(C'\fR, \f(CW\*(C`sysopen\*(C'\fR, \f(CW\*(C`system\*(C'\fR, -\&\f(CW\*(C`times\*(C'\fR, \f(CW\*(C`truncate\*(C'\fR, \f(CW\*(C`umask\*(C'\fR, \f(CW\*(C`unlink\*(C'\fR, -\&\f(CW\*(C`utime\*(C'\fR, \f(CW\*(C`wait\*(C'\fR, \f(CW\*(C`waitpid\*(C'\fR -.PP -For more information about the portability of these functions, see -perlport and other available platform-specific documentation. -.Sh "Alphabetical Listing of Perl Functions" -.IX Subsection "Alphabetical Listing of Perl Functions" -.IP "\-X \s-1FILEHANDLE\s0" 8 -.IX Xref "-r -w -x -o -R -W -X -O -e -z -s -f -d -l -p -S -b -c -t -u -g -k -T -B -M -A -C" -.IX Item "-X FILEHANDLE" -.PD 0 -.IP "\-X \s-1EXPR\s0" 8 -.IX Item "-X EXPR" -.IP "\-X" 8 -.IX Item "-X" -.PD -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 \f(CW$_\fR, except for \f(CW\*(C`\-t\*(C'\fR, which tests \s-1STDIN\s0. -Unless otherwise documented, it returns \f(CW1\fR for true and \f(CW''\fR 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: -.Sp -.Vb 4 -\& -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. -.Ve -.Sp -.Vb 4 -\& -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. -.Ve -.Sp -.Vb 3 -\& -e File exists. -\& -z File has zero size (is empty). -\& -s File has nonzero size (returns size in bytes). -.Ve -.Sp -.Vb 8 -\& -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. -.Ve -.Sp -.Vb 3 -\& -u File has setuid bit set. -\& -g File has setgid bit set. -\& -k File has sticky bit set. -.Ve -.Sp -.Vb 2 -\& -T File is an ASCII text file (heuristic guess). -\& -B File is a "binary" file (opposite of -T). -.Ve -.Sp -.Vb 3 -\& -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) -.Ve -.Sp -Example: -.Sp -.Vb 5 -\& while (<>) { -\& chomp; -\& next unless -f $_; # ignore specials -\& #... -\& } -.Ve -.Sp -The interpretation of the file permission operators \f(CW\*(C`\-r\*(C'\fR, \f(CW\*(C`\-R\*(C'\fR, -\&\f(CW\*(C`\-w\*(C'\fR, \f(CW\*(C`\-W\*(C'\fR, \f(CW\*(C`\-x\*(C'\fR, and \f(CW\*(C`\-X\*(C'\fR is by default based solely on the mode -of the file and the uids and gids of the user. There may be other -reasons you can't actually read, write, or execute the file. Such -reasons may be for example network filesystem access controls, ACLs -(access control lists), read-only filesystems, and unrecognized -executable formats. -.Sp -Also note that, for the superuser on the local filesystems, the \f(CW\*(C`\-r\*(C'\fR, -\&\f(CW\*(C`\-R\*(C'\fR, \f(CW\*(C`\-w\*(C'\fR, and \f(CW\*(C`\-W\*(C'\fR tests always return 1, and \f(CW\*(C`\-x\*(C'\fR and \f(CW\*(C`\-X\*(C'\fR return 1 -if any execute bit is set in the mode. Scripts run by the superuser -may thus need to do a \fIstat()\fR to determine the actual mode of the file, -or temporarily set their effective uid to something else. -.Sp -If you are using ACLs, there is a pragma called \f(CW\*(C`filetest\*(C'\fR that may -produce more accurate results than the bare \fIstat()\fR mode bits. -When under the \f(CW\*(C`use filetest 'access'\*(C'\fR the above-mentioned filetests -will test whether the permission can (not) be granted using the -\&\fIaccess()\fR family of system calls. Also note that the \f(CW\*(C`\-x\*(C'\fR and \f(CW\*(C`\-X\*(C'\fR may -under this pragma return true even if there are no execute permission -bits set (nor any extra execute permission ACLs). This strangeness is -due to the underlying system calls' definitions. Read the -documentation for the \f(CW\*(C`filetest\*(C'\fR pragma for more information. -.Sp -Note that \f(CW\*(C`\-s/a/b/\*(C'\fR does not do a negated substitution. Saying -\&\f(CW\*(C`\-exp($foo)\*(C'\fR still works as expected, however\*(--only single letters -following a minus are interpreted as file tests. -.Sp -The \f(CW\*(C`\-T\*(C'\fR and \f(CW\*(C`\-B\*(C'\fR switches work as follows. The first block or so of the -file is examined for odd characters such as strange control codes or -characters with the high bit set. If too many strange characters (>30%) -are found, it's a \f(CW\*(C`\-B\*(C'\fR file; otherwise it's a \f(CW\*(C`\-T\*(C'\fR file. Also, any file -containing null in the first block is considered a binary file. If \f(CW\*(C`\-T\*(C'\fR -or \f(CW\*(C`\-B\*(C'\fR is used on a filehandle, the current \s-1IO\s0 buffer is examined -rather than the first block. Both \f(CW\*(C`\-T\*(C'\fR and \f(CW\*(C`\-B\*(C'\fR return true on a null -file, or a file at \s-1EOF\s0 when testing a filehandle. Because you have to -read a file to do the \f(CW\*(C`\-T\*(C'\fR test, on most occasions you want to use a \f(CW\*(C`\-f\*(C'\fR -against the file first, as in \f(CW\*(C`next unless \-f $file && \-T $file\*(C'\fR. -.Sp -If any of the file tests (or either the \f(CW\*(C`stat\*(C'\fR or \f(CW\*(C`lstat\*(C'\fR operators) are given -the special filehandle consisting of a solitary underline, then the stat -structure of the previous file test (or stat operator) is used, saving -a system call. (This doesn't work with \f(CW\*(C`\-t\*(C'\fR, and you need to remember -that \fIlstat()\fR and \f(CW\*(C`\-l\*(C'\fR will leave values in the stat structure for the -symbolic link, not the real file.) (Also, if the stat buffer was filled by -an \f(CW\*(C`lstat\*(C'\fR call, \f(CW\*(C`\-T\*(C'\fR and \f(CW\*(C`\-B\*(C'\fR will reset it with the results of \f(CW\*(C`stat _\*(C'\fR). -Example: -.Sp -.Vb 1 -\& print "Can do.\en" if -r $a || -w _ || -x _; -.Ve -.Sp -.Vb 9 -\& stat($filename); -\& print "Readable\en" if -r _; -\& print "Writable\en" if -w _; -\& print "Executable\en" if -x _; -\& print "Setuid\en" if -u _; -\& print "Setgid\en" if -g _; -\& print "Sticky\en" if -k _; -\& print "Text\en" if -T _; -\& print "Binary\en" if -B _; -.Ve -.IP "abs \s-1VALUE\s0" 8 -.IX Xref "abs absolute" -.IX Item "abs VALUE" -.PD 0 -.IP "abs" 8 -.IX Item "abs" -.PD -Returns the absolute value of its argument. -If \s-1VALUE\s0 is omitted, uses \f(CW$_\fR. -.IP "accept \s-1NEWSOCKET\s0,GENERICSOCKET" 8 -.IX Xref "accept" -.IX Item "accept NEWSOCKET,GENERICSOCKET" -Accepts an incoming socket connect, just as the \fIaccept\fR\|(2) system call -does. Returns the packed address if it succeeded, false otherwise. -See the example in \*(L"Sockets: Client/Server Communication\*(R" in perlipc. -.Sp -On systems that support a close-on-exec flag on files, the flag will -be set for the newly opened file descriptor, as determined by the -value of $^F. See \*(L"$^F\*(R" in perlvar. -.IP "alarm \s-1SECONDS\s0" 8 -.IX Xref "alarm SIGALRM timer" -.IX Item "alarm SECONDS" -.PD 0 -.IP "alarm" 8 -.IX Item "alarm" -.PD -Arranges to have a \s-1SIGALRM\s0 delivered to this process after the -specified number of wallclock seconds has elapsed. If \s-1SECONDS\s0 is not -specified, the value stored in \f(CW$_\fR 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.) -.Sp -Only one timer may be counting at once. Each call disables the -previous timer, and an argument of \f(CW0\fR may be supplied to cancel the -previous timer without starting a new one. The returned value is the -amount of time remaining on the previous timer. -.Sp -For delays of finer granularity than one second, you may use Perl's -four-argument version of \fIselect()\fR leaving the first three arguments -undefined, or you might be able to use the \f(CW\*(C`syscall\*(C'\fR interface to -access \fIsetitimer\fR\|(2) if your system supports it. The Time::HiRes -module (from \s-1CPAN\s0, and starting from Perl 5.8 part of the standard -distribution) may also prove useful. -.Sp -It is usually a mistake to intermix \f(CW\*(C`alarm\*(C'\fR and \f(CW\*(C`sleep\*(C'\fR calls. -(\f(CW\*(C`sleep\*(C'\fR may be internally implemented in your system with \f(CW\*(C`alarm\*(C'\fR) -.Sp -If you want to use \f(CW\*(C`alarm\*(C'\fR to time out a system call you need to use an -\&\f(CW\*(C`eval\*(C'\fR/\f(CW\*(C`die\*(C'\fR pair. You can't rely on the alarm causing the system call to -fail with \f(CW$!\fR set to \f(CW\*(C`EINTR\*(C'\fR because Perl sets up signal handlers to -restart system calls on some systems. Using \f(CW\*(C`eval\*(C'\fR/\f(CW\*(C`die\*(C'\fR always works, -modulo the caveats given in \*(L"Signals\*(R" in perlipc. -.Sp -.Vb 13 -\& eval { -\& local $SIG{ALRM} = sub { die "alarm\en" }; # NB: \en required -\& alarm $timeout; -\& $nread = sysread SOCKET, $buffer, $size; -\& alarm 0; -\& }; -\& if ($@) { -\& die unless $@ eq "alarm\en"; # propagate unexpected errors -\& # timed out -\& } -\& else { -\& # didn't -\& } -.Ve -.Sp -For more information see perlipc. -.IP "atan2 Y,X" 8 -.IX Xref "atan2 arctangent tan tangent" -.IX Item "atan2 Y,X" -Returns the arctangent of Y/X in the range \-PI to \s-1PI\s0. -.Sp -For the tangent operation, you may use the \f(CW\*(C`Math::Trig::tan\*(C'\fR -function, or use the familiar relation: -.Sp -.Vb 1 -\& sub tan { sin($_[0]) / cos($_[0]) } -.Ve -.Sp -Note that atan2(0, 0) is not well\-defined. -.IP "bind \s-1SOCKET\s0,NAME" 8 -.IX Xref "bind" -.IX Item "bind SOCKET,NAME" -Binds a network address to a socket, just as the bind system call -does. Returns true if it succeeded, false otherwise. \s-1NAME\s0 should be a -packed address of the appropriate type for the socket. See the examples in -\&\*(L"Sockets: Client/Server Communication\*(R" in perlipc. -.IP "binmode \s-1FILEHANDLE\s0, \s-1LAYER\s0" 8 -.IX Xref "binmode binary text DOS Windows" -.IX Item "binmode FILEHANDLE, LAYER" -.PD 0 -.IP "binmode \s-1FILEHANDLE\s0" 8 -.IX Item "binmode FILEHANDLE" -.PD -Arranges for \s-1FILEHANDLE\s0 to be read or written in \*(L"binary\*(R" or \*(L"text\*(R" -mode on systems where the run-time libraries distinguish between -binary and text files. If \s-1FILEHANDLE\s0 is an expression, the value is -taken as the name of the filehandle. Returns true on success, -otherwise it returns \f(CW\*(C`undef\*(C'\fR and sets \f(CW$!\fR (errno). -.Sp -On some systems (in general, \s-1DOS\s0 and Windows-based systems) \fIbinmode()\fR -is necessary when you're not working with a text file. For the sake -of portability it is a good idea to always use it when appropriate, -and to never use it when it isn't appropriate. Also, people can -set their I/O to be by default \s-1UTF\-8\s0 encoded Unicode, not bytes. -.Sp -In other words: regardless of platform, use \fIbinmode()\fR on binary data, -like for example images. -.Sp -If \s-1LAYER\s0 is present it is a single string, but may contain multiple -directives. The directives alter the behaviour of the file handle. -When \s-1LAYER\s0 is present using binmode on text file makes sense. -.Sp -If \s-1LAYER\s0 is omitted or specified as \f(CW\*(C`:raw\*(C'\fR the filehandle is made -suitable for passing binary data. This includes turning off possible \s-1CRLF\s0 -translation and marking it as bytes (as opposed to Unicode characters). -Note that, despite what may be implied in \fI\*(L"Programming Perl\*(R"\fR (the -Camel) or elsewhere, \f(CW\*(C`:raw\*(C'\fR is \fInot\fR the simply inverse of \f(CW\*(C`:crlf\*(C'\fR -\&\*(-- other layers which would affect binary nature of the stream are -\&\fIalso\fR disabled. See PerlIO, perlrun and the discussion about the -\&\s-1PERLIO\s0 environment variable. -.Sp -The \f(CW\*(C`:bytes\*(C'\fR, \f(CW\*(C`:crlf\*(C'\fR, and \f(CW\*(C`:utf8\*(C'\fR, and any other directives of the -form \f(CW\*(C`:...\*(C'\fR, are called I/O \fIlayers\fR. The \f(CW\*(C`open\*(C'\fR pragma can be used to -establish default I/O layers. See open. -.Sp -\&\fIThe \s-1LAYER\s0 parameter of the \fIbinmode()\fI function is described as \*(L"\s-1DISCIPLINE\s0\*(R" -in \*(L"Programming Perl, 3rd Edition\*(R". However, since the publishing of this -book, by many known as \*(L"Camel \s-1III\s0\*(R", the consensus of the naming of this -functionality has moved from \*(L"discipline\*(R" to \*(L"layer\*(R". All documentation -of this version of Perl therefore refers to \*(L"layers\*(R" rather than to -\&\*(L"disciplines\*(R". Now back to the regularly scheduled documentation...\fR -.Sp -To mark \s-1FILEHANDLE\s0 as \s-1UTF\-8\s0, use \f(CW\*(C`:utf8\*(C'\fR. -.Sp -In general, \fIbinmode()\fR should be called after \fIopen()\fR but before any I/O -is done on the filehandle. Calling \fIbinmode()\fR will normally flush any -pending buffered output data (and perhaps pending input data) on the -handle. An exception to this is the \f(CW\*(C`:encoding\*(C'\fR layer that -changes the default character encoding of the handle, see open. -The \f(CW\*(C`:encoding\*(C'\fR layer sometimes needs to be called in -mid\-stream, and it doesn't flush the stream. The \f(CW\*(C`:encoding\*(C'\fR -also implicitly pushes on top of itself the \f(CW\*(C`:utf8\*(C'\fR layer because -internally Perl will operate on \s-1UTF\-8\s0 encoded Unicode characters. -.Sp -The operating system, device drivers, C libraries, and Perl run-time -system all work together to let the programmer treat a single -character (\f(CW\*(C`\en\*(C'\fR) as the line terminator, irrespective of the external -representation. On many operating systems, the native text file -representation matches the internal representation, but on some -platforms the external representation of \f(CW\*(C`\en\*(C'\fR is made up of more than -one character. -.Sp -Mac \s-1OS\s0, all variants of Unix, and Stream_LF files on \s-1VMS\s0 use a single -character to end each line in the external representation of text (even -though that single character is \s-1CARRIAGE\s0 \s-1RETURN\s0 on Mac \s-1OS\s0 and \s-1LINE\s0 \s-1FEED\s0 -on Unix and most \s-1VMS\s0 files). In other systems like \s-1OS/2\s0, \s-1DOS\s0 and the -various flavors of MS-Windows your program sees a \f(CW\*(C`\en\*(C'\fR as a simple \f(CW\*(C`\ecJ\*(C'\fR, -but what's stored in text files are the two characters \f(CW\*(C`\ecM\ecJ\*(C'\fR. That -means that, if you don't use \fIbinmode()\fR on these systems, \f(CW\*(C`\ecM\ecJ\*(C'\fR -sequences on disk will be converted to \f(CW\*(C`\en\*(C'\fR on input, and any \f(CW\*(C`\en\*(C'\fR in -your program will be converted back to \f(CW\*(C`\ecM\ecJ\*(C'\fR on output. This is what -you want for text files, but it can be disastrous for binary files. -.Sp -Another consequence of using \fIbinmode()\fR (on some systems) is that -special end-of-file markers will be seen as part of the data stream. -For systems from the Microsoft family this means that if your binary -data contains \f(CW\*(C`\ecZ\*(C'\fR, the I/O subsystem will regard it as the end of -the file, unless you use \fIbinmode()\fR. -.Sp -\&\fIbinmode()\fR is not only important for \fIreadline()\fR and \fIprint()\fR operations, -but also when using \fIread()\fR, \fIseek()\fR, \fIsysread()\fR, \fIsyswrite()\fR and \fItell()\fR -(see perlport for more details). See the \f(CW$/\fR and \f(CW\*(C`$\e\*(C'\fR variables -in perlvar for how to manually set your input and output -line-termination sequences. -.IP "bless \s-1REF\s0,CLASSNAME" 8 -.IX Xref "bless" -.IX Item "bless REF,CLASSNAME" -.PD 0 -.IP "bless \s-1REF\s0" 8 -.IX Item "bless REF" -.PD -This function tells the thingy referenced by \s-1REF\s0 that it is now an object -in the \s-1CLASSNAME\s0 package. If \s-1CLASSNAME\s0 is omitted, the current package -is used. Because a \f(CW\*(C`bless\*(C'\fR is often the last thing in a constructor, -it returns the reference for convenience. Always use the two-argument -version if a derived class might inherit the function doing the blessing. -See perltoot and perlobj for more about the blessing (and blessings) -of objects. -.Sp -Consider always blessing objects in CLASSNAMEs that are mixed case. -Namespaces with all lowercase names are considered reserved for -Perl pragmata. Builtin types have all uppercase names. To prevent -confusion, you may wish to avoid such package names as well. Make sure -that \s-1CLASSNAME\s0 is a true value. -.Sp -See \*(L"Perl Modules\*(R" in perlmod. -.IP "caller \s-1EXPR\s0" 8 -.IX Xref "caller call stack stack stack trace" -.IX Item "caller EXPR" -.PD 0 -.IP "caller" 8 -.IX Item "caller" -.PD -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 \f(CW\*(C`eval\*(C'\fR or \f(CW\*(C`require\*(C'\fR, and the undefined value -otherwise. In list context, returns -.Sp -.Vb 1 -\& ($package, $filename, $line) = caller; -.Ve -.Sp -With \s-1EXPR\s0, it returns some extra information that the debugger uses to -print a stack trace. The value of \s-1EXPR\s0 indicates how many call frames -to go back before the current one. -.Sp -.Vb 2 -\& ($package, $filename, $line, $subroutine, $hasargs, -\& $wantarray, $evaltext, $is_require, $hints, $bitmask) = caller($i); -.Ve -.Sp -Here \f(CW$subroutine\fR may be \f(CW\*(C`(eval)\*(C'\fR if the frame is not a subroutine -call, but an \f(CW\*(C`eval\*(C'\fR. In such a case additional elements \f(CW$evaltext\fR and -\&\f(CW$is_require\fR are set: \f(CW$is_require\fR is true if the frame is created by a -\&\f(CW\*(C`require\*(C'\fR or \f(CW\*(C`use\*(C'\fR statement, \f(CW$evaltext\fR contains the text of the -\&\f(CW\*(C`eval EXPR\*(C'\fR statement. In particular, for an \f(CW\*(C`eval BLOCK\*(C'\fR statement, -\&\f(CW$filename\fR is \f(CW\*(C`(eval)\*(C'\fR, but \f(CW$evaltext\fR is undefined. (Note also that -each \f(CW\*(C`use\*(C'\fR statement creates a \f(CW\*(C`require\*(C'\fR frame inside an \f(CW\*(C`eval EXPR\*(C'\fR -frame.) \f(CW$subroutine\fR may also be \f(CW\*(C`(unknown)\*(C'\fR if this particular -subroutine happens to have been deleted from the symbol table. -\&\f(CW$hasargs\fR is true if a new instance of \f(CW@_\fR was set up for the frame. -\&\f(CW$hints\fR and \f(CW$bitmask\fR contain pragmatic hints that the caller was -compiled with. The \f(CW$hints\fR and \f(CW$bitmask\fR values are subject to change -between versions of Perl, and are not meant for external use. -.Sp -Furthermore, when called from within the \s-1DB\s0 package, caller returns more -detailed information: it sets the list variable \f(CW@DB::args\fR to be the -arguments with which the subroutine was invoked. -.Sp -Be aware that the optimizer might have optimized call frames away before -\&\f(CW\*(C`caller\*(C'\fR had a chance to get the information. That means that \f(CWcaller(N)\fR -might not return information about the call frame you expect it do, for -\&\f(CW\*(C`N > 1\*(C'\fR. In particular, \f(CW@DB::args\fR might have information from the -previous time \f(CW\*(C`caller\*(C'\fR was called. -.IP "chdir \s-1EXPR\s0" 8 -.IX Xref "chdir cd" -.IX Item "chdir EXPR" -.PD 0 -.IP "chdir \s-1FILEHANDLE\s0" 8 -.IX Item "chdir FILEHANDLE" -.IP "chdir \s-1DIRHANDLE\s0" 8 -.IX Item "chdir DIRHANDLE" -.IP "chdir" 8 -.IX Item "chdir" -.PD -Changes the working directory to \s-1EXPR\s0, if possible. If \s-1EXPR\s0 is omitted, -changes to the directory specified by \f(CW$ENV{HOME}\fR, if set; if not, -changes to the directory specified by \f(CW$ENV{LOGDIR}\fR. (Under \s-1VMS\s0, the -variable \f(CW$ENV{SYS$LOGIN}\fR is also checked, and used if it is set.) If -neither is set, \f(CW\*(C`chdir\*(C'\fR does nothing. It returns true upon success, -false otherwise. See the example under \f(CW\*(C`die\*(C'\fR. -.Sp -On systems that support fchdir, you might pass a file handle or -directory handle as argument. On systems that don't support fchdir, -passing handles produces a fatal error at run time. -.IP "chmod \s-1LIST\s0" 8 -.IX Xref "chmod permission mode" -.IX Item "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 \fInot\fR be a string of octal digits: -\&\f(CW0644\fR is okay, \f(CW'0644'\fR is not. Returns the number of files -successfully changed. See also \*(L"oct\*(R", if all you have is a string. -.Sp -.Vb 6 -\& $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 -.Ve -.Sp -On systems that support fchmod, you might pass file handles among the -files. On systems that don't support fchmod, passing file handles -produces a fatal error at run time. -.Sp -.Vb 3 -\& open(my $fh, "<", "foo"); -\& my $perm = (stat $fh)[2] & 07777; -\& chmod($perm | 0600, $fh); -.Ve -.Sp -You can also import the symbolic \f(CW\*(C`S_I*\*(C'\fR constants from the Fcntl -module: -.Sp -.Vb 1 -\& use Fcntl ':mode'; -.Ve -.Sp -.Vb 2 -\& chmod S_IRWXU|S_IRGRP|S_IXGRP|S_IROTH|S_IXOTH, @executables; -\& # This is identical to the chmod 0755 of the above example. -.Ve -.IP "chomp \s-1VARIABLE\s0" 8 -.IX Xref "chomp INPUT_RECORD_SEPARATOR $ newline eol" -.IX Item "chomp VARIABLE" -.PD 0 -.IP "chomp( \s-1LIST\s0 )" 8 -.IX Item "chomp( LIST )" -.IP "chomp" 8 -.IX Item "chomp" -.PD -This safer version of \*(L"chop\*(R" removes any trailing string -that corresponds to the current value of \f(CW$/\fR (also known as -\&\f(CW$INPUT_RECORD_SEPARATOR\fR in the \f(CW\*(C`English\*(C'\fR 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 (\f(CW\*(C`$/ = ""\*(C'\fR), it removes all trailing newlines from the string. -When in slurp mode (\f(CW\*(C`$/ = undef\*(C'\fR) or fixed-length record mode (\f(CW$/\fR is -a reference to an integer or the like, see perlvar) \fIchomp()\fR won't -remove anything. -If \s-1VARIABLE\s0 is omitted, it chomps \f(CW$_\fR. Example: -.Sp -.Vb 5 -\& while (<>) { -\& chomp; # avoid \en on last field -\& @array = split(/:/); -\& # ... -\& } -.Ve -.Sp -If \s-1VARIABLE\s0 is a hash, it chomps the hash's values, but not its keys. -.Sp - |