Path: utzoo!utgpu!news-server.csri.toronto.edu!mailrus!cs.utexas.edu!usc!apple!rutgers!mit-eddie!bloom-beacon!eru!luth!sunic!mcsun!hp4nl!mhres!jv
From: jv@mh.nl (Johan Vromans)
Newsgroups: comp.lang.perl
Subject: REPOST: texinfo version of perl refguide (2 of 3)
Message-ID: <JV.90Jun27103104@squirrel.mh.nl>
Date: 27 Jun 90 16:31:04 GMT
Sender: news@mhres.mh.nl
Reply-To: Johan Vromans <jv@mh.nl>
Organization: Multihouse Automation, the Netherlands
Lines: 604
X-Checksum-Snefru: 916689f5 7498db7e dbad7f41 78148ecf


Archive-name: perlref.texinfo/part02

---- Cut Here and unpack ----
#!/bin/sh
# this is xxx.02 (part 2 of perlref.texinfo)
# do not concatenate these parts, unpack them in order with /bin/sh
# file perlref.texinfo continued
#
if touch 2>&1 | fgrep '[-amc]' > /dev/null
 then TOUCH=touch
 else TOUCH=true
fi
if test ! -r shar3_seq_.tmp; then
	echo "Please unpack part 1 first!"
	exit 1
fi
(read Scheck
 if test "$Scheck" != 2; then
	echo "Please unpack part $Scheck next!"
	exit 1
 else
	exit 0
 fi
) < shar3_seq_.tmp || exit 1
echo "x - Continuing file perlref.texinfo"
sed 's/^X//' << 'SHAR_EOF' >> perlref.texinfo &&
X@var{ARRAY} increases by the length of @var{LIST}.@refill
X
X@item reverse(@var{LIST})*
XReturns the @var{LIST} in reverse order.
X
X@item shift[(@code{@@}@var{ARRAY})*]
XShifts the first value of the array off and returns it, shortening the
Xarray by 1 and moving everything down. If @code{@@}@var{ARRAY} is
Xomitted, shifts @code{@@ARGV} in main and @code{@@_} in
Xsubroutines.@refill
X
X@item sort([@var{SUBROUTINE}] @var{LIST})*
XSorts the @var{LIST} and returns the sorted array value. If
X@var{SUBROUTINE} is specified, gives the name of a subroutine that
Xreturns less than zero, zero, or greater than zero, depending on how the
Xelements of the array, available to the routine as @code{$a} and
X@code{$b}, are to be ordered.@refill
X
X@item splice(@code{@@}@var{ARRAY},@var{OFFSET}[,@var{LENGTH}[,@var{LIST}]])
XRemoves the elements of @code{@@}@var{ARRAY} designated by @var{OFFSET} and
X@var{LENGTH}, and replaces them with @var{LIST} (if specified).  Returns
Xthe elements removed.@refill
X
X@item split[(/@var{PATTERN}/[,@var{EXPR}*[,@var{LIMIT}]])]
XSplits a string into an array of strings, and returns it. If @var{LIMIT} is
Xspecified, splits in no more than that many fields. If @var{PATTERN} is
Xalso omitted, splits on whitespace (/[ \t\n]+/). If not in array
Xcontext: returns number of fields and splits to @code{@@_}.@refill
X
X@item unshift(@code{@@}@var{ARRAY},@var{LIST})
XPrepends list to the front of the array, and returns the number of
Xelements in the new array.@refill
X
X@item values(@code{%}@var{ARRAY})*
XReturns a normal array consisting of all the values of the named
Xassociative array.@refill
X@end table
X
X@c----------------------------------------------------------------
X@node File operations, Directory reading routines, Array and list functions, Top
X@chapter File operations
X
XFunctions operating on a list of files return the number of files
Xsuccessfully operated upon.@refill
X
X@table @code
X
X@item chmod(@var{LIST})*
XChanges the permissions of a list of files. The first element of the
Xlist must be the numerical mode.@refill
X
X@item chown(@var{LIST})*
XChanges the owner and group of a list of files. The first two
Xelements of the list must be the numerical uid and gid.@refill
X
X@item link(@var{OLDFILE},@var{NEWFILE})
XCreates a new filename linked to the old filename.
X
X@item lstat(@var{FILE})
XLike stat, but does not traverse a final symbolic link.
X
X@item mkdir(@var{DIR},@var{MODE})
XCreates a directory with given permissions. Sets @code{$!} on failure.@refill
X
X@item select(@var{RBITS},@var{WBITS},@var{NBITS},@var{TIMEOUT})
XPerforms a select(2) system call with the same parameters.@refill
X
X@item readlink(@var{EXPR}*)*
XReturns the value of a symbolic link.
X
X@item rename(@var{OLDNAME},@var{NEWNAME})
XChanges the name of a file.
X
X@item rmdir(@var{FILENAME}*)*
XDeletes the directory if it is empty. Sets @code{$!} on failure.@refill
X
X@item stat(@var{FILE})
XReturns a 13-element array @code{($dev, $ino, $mode, $nlink, $uid, $gid,
X$rdev, $size, $atime, $mtime, $ctime, $blksize, $blocks)}. @var{FILE}
Xcan be a filehandle, an expression evaluating to a filename, or @code{_}
Xto refer to the last file test operation. The parentheses may be omitted
Xif @var{FILE} is a filehandle, a variable, or @code{_}.@refill
X
X@item symlink(@var{OLDFILE},@var{NEWFILE})
XCreates a new filename symbolically linked to the old filename.
X
X@item unlink(@var{LIST})*
XDeletes a list of files.
X
X@item utime(@var{LIST})*
XChanges the access and modification times on each file of a list of
Xfiles. The first two elements of the list must be the numerical access
Xand modification times.@refill
X@end table
X
X@c----------------------------------------------------------------
X@node Directory reading routines, Input/Output, File operations, Top
X@chapter Directory reading routines
X
X@table @code
X
X@item closedir(@var{DIRHANDLE})*
XCloses a directory opened by opendir.
X
X@item opendir(@var{DIRHANDLE},@var{DIRNAME})
XOpens a directory on the handle specified.
X
X@item readdir(@var{DIRHANDLE})*
XReturns the next entry (or an array of entries) in the directory.
X
X@item rewinddir(@var{DIRHANDLE})*
XPositions the directory to the beginning.
X
X@item seekdir(@var{DIRHANDLE},@var{POS})
XSets position for readdir on the directory.
X
X@item telldir(@var{DIRHANDLE})*
XReturns the postion in the directory.
X@end table
X
X@c----------------------------------------------------------------
X@node Input/Output, Search and replace functions, Directory reading routines, Top
X@chapter Input/Output
X
XIn input/output operations, @var{FILEHANDLE} may be a filehandle as
Xopened by the @code{open} operator, or a scalar variable which evaluates
Xto the name of a filehandle to be used.@refill
X
X@table @code
X
X@c %%rjc%% MS-DOS properly capitalized
X@item binmode(@var{FILEHANDLE})*
XArranges for the file opened on @var{FILEHANDLE} to be read in
X@code{binary} mode as opposed to @code{text} mode (MS-DOS only).@refill
X
X@item close(@var{FILEHANDLE})*
XCloses the file or pipe associated with the file handle.
X
X@item dbmclose(@code{%}@var{ARRAY})*
XBreaks the binding between the array and the dbm file.
X
X@item dbmopen(@code{%}@var{ARRAY},@var{DBMNAME}, @var{MODE})
XBinds a dbm or ndbm file to the associative array. If the database
Xdoes not exist, it is created with the indicated mode.@refill
X
X@item eof(@var{FILEHANDLE})
XReturns 1 if the next read will return end of file, or if the file is not
Xopen.@refill
X
X@item eof
XReturns the eof status for the last file read.
X
X@item eof()
XIndicates eof on the pseudo file formed of the files listed on the
Xcommand line.@refill
X
X@item fcntl(@var{FILEHANDLE},@var{FUNCTION},@code{$}@var{VAR})
XImplements the fcntl(2) function. This function has non-standard
Xreturn values. See the manual for details.@refill
X
X@item fileno(@var{FILEHANDLE})*
XReturns the file descriptor for a given (open) file.
X
X@item flock(@var{FILEHANDLE},@var{OPERATION})
XCalls flock(2) on the file. @var{OPERATION} adds from 1 (shared), 2
X(exclusive), 4 (non-blocking) or 8 (unlock).@refill
X
X@item getc[(@var{FILEHANDLE})*]
XYields the next character from the file, or @var{NULL} on @var{EOF}. If
X@var{FILEHANDLE} is omitted, reads from @var{STDIN}.@refill
X
X@item ioctl(@var{FILEHANDLE},@var{FUNCTION},@code{$}@var{VAR})
Xperforms ioctl(2) on the file. This function has non-standard return
Xvalues. See the manual for details.@refill
X
X@item open(@var{FILEHANDLE}[,@var{FILENAME}])
XOpens a file and associates it with @var{FILEHANDLE}. If @var{FILENAME}
Xis omitted, the scalar variable of the same name as the @var{FILEHANDLE}
Xmust contain the filename.  The filename may be optionally preceded by
X@code{>}, @code{>>} or @code{<} to select output/append/input mode.
XDefault mode is input. Precede with @code{+} to select read/write
Xaccess. Use @code{&@dots{}} to connect to an already opened filehandle.
XPipes to/from commands may be opened with @code{|@dots{}} and
X@code{@dots{}|} . Open returns 1 upon success, undef otherwise, except
Xfor pipes. The parentheses may be omitted, if only a @var{FILEHANDLE} is
Xspecified.@refill
X
X@item pipe(@var{READHANDLE},@var{WRITEHANDLE})
XReturns a pair of connected pipes.
X
X@item print[([@var{FILEHANDLE}] @var{LIST}*)*]
XPrints a string or a comma-separated list of strings. If
X@var{FILEHANDLE} is omitted, prints by default to standard output (or
Xto the last selected output channel---see select(@dots{})).@refill
X
X@item printf[([@var{FILEHANDLE}] @var{LIST})*]
XEquivalent to @code{print @var{FILEHANDLE} sprintf(@var{LIST})}.@refill
X
X@item read(@var{FILEHANDLE},@code{$}@var{VAR},@var{LENGTH})
XRead @var{LENGTH} binary bytes from the file into the variable.
XReturns number of bytes actually read.@refill
X
X@item seek(@var{FILEHANDLE},@var{POSITION},@var{WHENCE})
XRandomly positions the file. Returns 1 upon success, 0 otherwise.@refill
X
X@item select(@var{FILEHANDLE})*
XSets the current default filehandle for output operations. Returns
Xthe previously selected filehandle.@refill
X
X@item sprintf(@var{FORMAT},@var{LIST})
XReturns a string formatted by (almost all of) the usual printf
Xconventions.@refill
X
X@item tell[(@var{FILEHANDLE})]*
XReturns the current file position for the file. If @var{FILEHANDLE} is
Xomitted, assumes the file last read.@refill
X
X@item write[(@var{FILEHANDLE})]*
XWrites a formatted record to the specified file, using the format
Xassociated with that file. See Formats.@refill
X@end table
X
X@c----------------------------------------------------------------
X@node Search and replace functions, System interaction, Input/Output, Top
X@chapter Search and replace functions
X
X@table @code
X
X@item [@var{EXPR} @code{=~}] [m]/@var{PATTERN}/[i][o]
XSearches a string for a pattern. If no string is specified via the @code{=~}
Xor @code{!~} operator, the @code{$_} string is searched. If you prepend
Xan @code{m} you can use any pair of characters as delimiters. If the
Xfinal delimiter is followed by the optional letter @code{i}, the
Xmatching is done in a case-insensitive manner. If you append @code{o},
Xvariables are interpolated only once. If used in a context that requires
Xan array value, a pattern match returns an array consisting of the
Xsubexpressions matched by the parentheses in pattern, i.e. @code{($1,
X$2, $3}@dots{}@code{)}.@refill
X
X@item ?@var{PATTERN}?
XThis is just like the /pattern/ search, except that it matches only
Xonce between calls to the reset operator.@refill
X
X@item [@code{$}@var{VAR} @code{=~}] s/@var{PATTERN}/REPLACEMENT/[g][i][e][o]
XSearches a string for a pattern, and if found, replaces that pattern
Xwith the replacement text and returns the number of substitutions made.
XOtherwise it returns false (0). Optional modifiers: @code{g} indicates
Xthat all occurrences of the pattern are to be replaced; @code{e}
Xindicates that the replacement string is to be interpreted as an
Xexpression, @code{i} and @code{o} as with /@var{PATTERN}/ matching. Any
Xdelimiter may replace the slashes; if single quotes are used, no
Xinterpretation is done on the replacement string.@refill
X
X@item study[(@code{$}@var{VAR}*)*]
XStudy the contents of @code{$}@var{VAR} in anticipation of doing many pattern
Xmatches on the contents before it is next modified.@refill
X
X@item [@code{$}@var{VAR} @code{=~}] tr/@var{SEARCHLIST}/@var{REPLACEMENTLIST}/
XTranslates all occurrences of the characters found in the search list
Xwith the corresponding character in the replacement list. It returns the
Xnumber of characters replaced. @code{y} may be used instead of
X@code{tr}.@refill
X@end table
X
X@c----------------------------------------------------------------
X@node System interaction, Networking, Search and replace functions, Top
X@chapter System interaction
X
X@table @code
X
X@item chdir [(@var{EXPR})*]
XChanges the working directory, @code{$HOME} if @var{EXPR} is omitted.
X
X@item chroot(@var{FILENAME}*)*
XChanges the root for the following commands.
X
X@item die(@var{LIST})*
XPrints the value of @var{LIST} to @var{STDERR} and exits with the current
Xvalue of @code{$!} (errno). If @code{$!} is 0, exits with the value of
X@code{($? >> 8)} (@code{`command`} status). If @code{($? >> 8)} is 0,
Xexits with 255.@refill
X
X@item exec(@var{LIST})*
XExecutes the system command in @var{LIST}.
X
X@item exit(@var{EXPR})*
XExits immediately with the value of @var{EXPR}.
X
X@item fork
XDoes a fork() call. Returns the child pid to the parent process and
Xzero to the child process.@refill
X
X@item getlogin
XReturns the current login name from @file{/etc/utmp}.
X
X@item getpgrp[(@var{PID})*]
XReturns the process group for process @var{PID} (0, or omitted, means
Xthe current process).@refill
X
X@item getppid
XReturns the process id of the parent process.
X
X@item getpriority(@var{WHICH},@var{WHO})
XReturns the current priority for a process, process group, or user.
X
X@item kill(@var{LIST})*
XSends a signal to a list of processes. The first element of the list
Xmust be the signal to send (numeric, or its name as a string).@refill
X
X@item setpgrp(@var{PID},@var{PGRP})
XSets the process group for the @var{PID} (0 = current process).
X
X@item setpriority(@var{WHICH},@var{WHO},@var{PRIO})
XSets the current priority for a process, process group or a user.
X
X@item sleep[(@var{EXPR})*]
XCauses the script to sleep for @var{EXPR} seconds, or forever if no
X@var{EXPR}. Returns the number of seconds actually slept.@refill
X
X@item syscall(@var{LIST})*
XCalls the system call specified in the first element of the list,
Xpassing the rest of the list as arguments to the call.@refill
X
X@item system(@var{LIST})*
XDoes exactly the same thing as @code{exec @var{LIST}} except that a fork is
Xdone first, and the parent process waits for the child process to
Xcomplete.@refill
X
X@item times
XReturns a 4-element array @code{($user, $system, $cuser, $csystem)}
Xgiving the user and system times, in seconds, for this process and the
Xchildren of this process.@refill
X
X@item umask[(@var{EXPR})*]
XSets the umask for the process and returns the old one. If @var{EXPR} is
Xomitted, returns current umask value.@refill
X
X@item wait
XWaits for a child process to terminate and returns the pid of the
Xdeceased process ($-1$ if none). The status is returned in @code{$?}.
X
X@item warn(@var{LIST})*
XPrints the message on @var{STDERR} like die(@dots{}), but doesn't exit.
X@end table
X
X@c----------------------------------------------------------------
X@node Networking, Miscellaneous, System interaction, Top
X@chapter Networking
X
X@table @code
X
X@item accept(@var{NEWSOCKET},@var{GENERICSOCKET})
XAccepts a new socket.
X
X@item bind(@var{SOCKET},@var{NAME})
XBinds the @var{NAME} to the @var{SOCKET}.
X
X@item connect(@var{SOCKET}, @var{NAME})
XConnects the @var{NAME} to the @var{SOCKET}.
X
X@item getpeername(@var{SOCKET})
XReturns the socket address of the other end of the @var{SOCKET}.
X
X@item getsockname(@var{SOCKET})
XReturns the name of the socket.
X
X@item getsockopt(@var{SOCKET},@var{LEVEL},@var{OPTNAME})
XReturns the socket options.
X
X@item listen(@var{SOCKET},@var{QUEUESIZE})
XStarts listening on the specified @var{SOCKET}.
X
X@item recv(@var{SOCKET},@var{SCALAR},@var{LENGTH},@var{FLAGS})
XReceives a message on @var{SOCKET}.
X
X@item send(@var{SOCKET},@var{MSG},@var{FLAGS}[,@var{TO}])
XSends a message on the @var{SOCKET}.
X
X@item setsockopt(@var{SOCKET},@var{LEVEL},@var{OPTNAME},@var{OPTVAL})
XSets the requested socket option.
X
X@item shutdown(@var{SOCKET},@var{HOW})
XShuts down a @var{SOCKET}.
X
X@item socket(@var{SOCKET},@var{DOMAIN},@var{TYPE},@var{PROTOCOL})
XCreates a @var{SOCKET} in @var{DOMAIN} with @var{TYPE} and @var{PROTOCOL}.
X
X@item socketpair(@var{SOCKET1},@var{SOCKET2},@var{DOMAIN},@var{TYPE},@var{PROTOCOL})
XAs socket, but creates a pair of bi-directional sockets.
X@end table
X
X@c----------------------------------------------------------------
X@node Miscellaneous, Info from system files, Networking, Top
X@chapter Miscellaneous
X
X@table @code
X
X@item defined(@var{EXPR})*
XTests whether the lvalue @var{EXPR} has a real value.
X
X@item dump [@var{LABEL}]
XImmediate core dump. When reincarnated, starts at @var{LABEL}.
X
X@item local(@var{LIST})
XDeclares the listed variables to be local to the enclosing block,
Xsubroutine or eval.
X
X@item package @var{NAME}
XDesignates the remainder of the current block as a package, having
Xa separate namespace.@refill
X
X@c %%rjc%% Changed "not omitted" to "supplied"
X@item reset [(@var{EXPR})*]
XResets @code{??} searches so that they work again. If @var{EXPR} is supplied,
Xit is interpreted as a list of single characters (hyphens allowed for
Xranges). All variables and arrays beginning with one of those letters
Xare reset to their pristine state.  Only affects the current
Xpackage.@refill
X
X@item sub @var{NAME} $\{$ @var{EXPR}; @dots{}\ $\}$
XDesignates @var{NAME} as a subroutine. Parameters are passed as array
X@code{@@_}. Returns the value of the last expression evaluated.@refill
X
X@item undef[(@var{LVALUE})*]
XUndefines the @var{LVALUE}. Always returns the undefined value.
X
X@item wantarray
XReturns true if the current context expects an array value.
X@end table
X
X@c----------------------------------------------------------------
X@node Info from system files, Regular expressions, Miscellaneous, Top
X@chapter Info from system files
X
X@file{/etc/passwd}.
XInfo is @code{($name, $passwd, $uid, $gid, $quota, $comment, $gcos, $dir, $shell)}.
X
X@table @code
X
X@item endpwent
XEnds lookup processing.
X
X@item getpwent
XGets next info.
X
X@item getpwnam(@var{NAME})
XGets info by name.
X
X@item getpwuid(@var{UID})
XGets info by uid.
X
X@item setpwent
XResets lookup processing.
X@end table
X
X@file{/etc/group}.
XInfo is a 4-item array: @code{($name, $passwd, $gid, $members)}.
X
X@table @code
X
X@item endgrent
XEnds lookup processing.
X
X@item getgrgid(@var{GID})
XGets info by group id.
X
X@item getgrnam(@var{NAME})
XGets info by name.
X
X@item getgrent
XGets next info.
X
X@item setgrent
XResets lookup processing.
X@end table
X
X@file{/etc/hosts}.
XInfo is @code{($name, $aliases, $addrtype, $length, @@addrs)}.
X
X@table @code
X
X@item endhostent
XEnds lookup processing.
X
X@item gethostbyname(@var{NAME})
XGets info by name.
X
X@item gethostent
XGets next info.
X
X@item sethostent(@var{STAYOPEN})
XResets lookup processing.
X@end table
X
X@file{/etc/networks}.
XInfo is @code{($name, $aliases, $addrtype, $net)}.
X
X@table @code
X
X@item endnetent
XEnds lookup processing.
X
X@item getnetbyaddr(@var{ADDR},@var{TYPE})
XGets info by address and type.
X
X@item getnetbyname(@var{NAME})
XGets info by name.
X
X@item getnetent
XGets next info.
X
X@item setnetent(@var{STAYOPEN})
XResets lookup processing.
X@end table
X
X@file{/etc/services}.
XInfo is @code{($name, $aliases, $port, $proto)}.
X
X@table @code
X
X@item endservent
XEnds lookup processing.
X
X@item getservbyname(@var{NAME}, @var{PROTO})
XGets info by name.
X
X@item getservbyport(@var{PORT}, @var{PROTO})
XGets info by port.
X
X@item getservent
XGets next info.
X
X@item setservent(@var{STAYOPEN})
XResets lookup processing.
X@end table
X
X@file{/etc/protocols}.
XInfo is @code{($name, $aliases, $proto)}.
X
X@table @code
X
X@item endprotoent
XEnds lookup processing.
X
X@item getprotobyname(@var{NAME})
XGets info by name.
X
X@item getprotobynumber(@var{NUMBER})
XGets info by number.
X
X@item getprotoent
XGets next info.
X
X@item setprotoent(@var{STAYOPEN})
XResets lookup processing.
X@end table
X
X@c----------------------------------------------------------------
X@node Regular expressions, Formats, Info from system files, Top
X@chapter Regular expressions
X
XStandard UNIX regular expressions, with the following additions:
X
X@table @asis
X
X@item @code{(} @code{)} @code{|} @code{@{} @code{@}}
Xdo not have to be escaped with a @code{\}.
SHAR_EOF
echo "End of perlref.texinfo part 2"
echo "File perlref.texinfo is continued in part 3"
echo "3" > shar3_seq_.tmp
exit 0
--
Johan Vromans				       jv@mh.nl via internet backbones
Multihouse Automatisering bv		       uucp: ..!{uunet,hp4nl}!mh.nl!jv
Doesburgweg 7, 2803 PL Gouda, The Netherlands  phone/fax: +31 1820 62911/62500
------------------------ "Arms are made for hugging" -------------------------