This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: File/Cat, Next: File/CheckTree, Prev: File/Cache, Up: Module List Perl implementation of cat(1) ***************************** NAME ==== File::Cat - Perl implementation of cat(1) SYNOPSIS ======== use File::Cat; cat ('/etc/motd', \*STDOUT) or die "Can't cat /etc/motd: $!"; DESCRIPTION =========== File::Cat is a module of adventure, danger, and low cunning. With it, you will explore some of the most inane programs ever seen by mortals. No computer should be without one! FUNCTIONS ========= * cat EXPR, *FILEHANDLE* Copies data from EXPR to FILEHANDLE, or returns false if an error occurred. EXPR can be either an open readable filehandle or a filename to use as input. * cattail EXPR, *FILEHANDLE* Prints EXPR to FILEHANDLE - backwards, line by line - or returns false if an error occurred. Again, EXPR can be either a filehandle or a filename. AUTHOR ====== Dennis Taylor, APOLOGIES TO... =============== Marc Blank. SEE ALSO ======== cat(1)  File: pm.info, Node: File/CheckTree, Next: File/Compare, Prev: File/Cat, Up: Module List run many filetest checks on a tree ********************************** NAME ==== validate - run many filetest checks on a tree SYNOPSIS ======== use File::CheckTree; $warnings += validate( q{ /vmunix -e || die /boot -e || die /bin cd csh -ex csh !-ug sh -ex sh !-ug /usr -d || warn "What happened to $file?\n" }); DESCRIPTION =========== The validate() routine takes a single multiline string consisting of lines containing a filename plus a file test to try on it. (The file test may also be a "cd", causing subsequent relative filenames to be interpreted relative to that directory.) After the file test you may put `|| die' to make it a fatal error if the file test fails. The default is `|| warn'. The file test may optionally have a "!' prepended to test for the opposite condition. If you do a cd and then list some relative filenames, you may want to indent them slightly for readability. If you supply your own die() or warn() message, you can use $file to interpolate the filename. Filetests may be bunched: "-rwx" tests for all of -r, -w, and -x. Only the first failed test of the bunch will produce a warning. The routine returns the number of warnings issued.  File: pm.info, Node: File/Compare, Next: File/Copy, Prev: File/CheckTree, Up: Module List Compare files or filehandles **************************** NAME ==== File::Compare - Compare files or filehandles SYNOPSIS ======== use File::Compare; if (compare("file1","file2") == 0) { print "They're equal\n"; } DESCRIPTION =========== The File::Compare::compare function compares the contents of two sources, each of which can be a file or a file handle. It is exported from File::Compare by default. File::Compare::cmp is a synonym for File::Compare::compare. It is exported from File::Compare only by request. File::Compare::compare_text does a line by line comparison of the two files. It stops as soon as a difference is detected. compare_text() accepts an optional third argument: This must be a CODE reference to a line comparison function, which returns 0 when both lines are considered equal. For example: compare_text($file1, $file2) is basically equivalent to compare_text($file1, $file2, sub {$_[0] ne $_[1]} ) RETURN ====== File::Compare::compare return 0 if the files are equal, 1 if the files are unequal, or -1 if an error was encountered. AUTHOR ====== File::Compare was written by Nick Ing-Simmons. Its original documentation was written by Chip Salzenberg.  File: pm.info, Node: File/Copy, Next: File/CounterFile, Prev: File/Compare, Up: Module List Copy files or filehandles ************************* NAME ==== File::Copy - Copy files or filehandles SYNOPSIS ======== use File::Copy; copy("file1","file2"); copy("Copy.pm",\*STDOUT);' move("/dev1/fileA","/dev2/fileB"); use POSIX; use File::Copy cp; $n=FileHandle->new("/dev/null","r"); cp($n,"x");' DESCRIPTION =========== The File::Copy module provides two basic functions, copy and move, which are useful for getting the contents of a file from one place to another. * The copy function takes two parameters: a file to copy from and a file to copy to. Either argument may be a string, a FileHandle reference or a FileHandle glob. Obviously, if the first argument is a filehandle of some sort, it will be read from, and if it is a file name it will be opened for reading. Likewise, the second argument will be written to (and created if need be). *Note that passing in files as handles instead of names may lead to loss of information on some operating systems; it is recommended that you use file names whenever possible.* Files are opened in binary mode where applicable. To get a consistent behaviour when copying from a filehandle to a file, use binmode on the filehandle. An optional third parameter can be used to specify the buffer size used for copying. This is the number of bytes from the first file, that wil be held in memory at any given time, before being written to the second file. The default buffer size depends upon the file, but will generally be the whole file (up to 2Mb), or 1k for filehandles that do not reference files (eg. sockets). You may use the syntax `use File::Copy "cp"' to get at the "cp" alias for this function. The syntax is *exactly* the same. * The move function also takes two parameters: the current name and the intended name of the file to be moved. If the destination already exists and is a directory, and the source is not a directory, then the source file will be renamed into the directory specified by the destination. If possible, move() will simply rename the file. Otherwise, it copies the file to the new location and deletes the original. If an error occurs during this copy-and-delete process, you may be left with a (possibly partial) copy of the file under the destination name. You may use the "mv" alias for this function in the same way that you may use the "cp" alias for copy. File::Copy also provides the `syscopy' routine, which copies the file specified in the first parameter to the file specified in the second parameter, preserving OS-specific attributes and file structure. For Unix systems, this is equivalent to the simple copy routine. For VMS systems, this calls the `rmscopy' routine (see below). For OS/2 systems, this calls the `syscopy' XSUB directly. For Win32 systems, this calls `Win32::CopyFile'. Special behaviour if `syscopy' is defined (OS/2, VMS and Win32) --------------------------------------------------------------- If both arguments to copy are not file handles, then copy will perform a "system copy" of the input file to a new output file, in order to preserve file attributes, indexed file structure, etc. The buffer size parameter is ignored. If either argument to copy is a handle to an opened file, then data is copied using Perl operators, and no effort is made to preserve file attributes or record structure. The system copy routine may also be called directly under VMS and OS/2 as `File::Copy::syscopy' (or under VMS as `File::Copy::rmscopy', which is the routine that does the actual work for syscopy). rmscopy($from,$to[,$date_flag]) The first and second arguments may be strings, typeglobs, typeglob references, or objects inheriting from IO::Handle; they are used in all cases to obtain the *filespec* of the input and output files, respectively. The name and type of the input file are used as defaults for the output file, if necessary. A new version of the output file is always created, which inherits the structure and RMS attributes of the input file, except for owner and protections (and possibly timestamps; see below). All data from the input file is copied to the output file; if either of the first two parameters to `rmscopy' is a file handle, its position is unchanged. (Note that this means a file handle pointing to the output file will be associated with an old version of that file after `rmscopy' returns, not the newly created version.) The third parameter is an integer flag, which tells `rmscopy' how to handle timestamps. If it is < 0, none of the input file's timestamps are propagated to the output file. If it is > 0, then it is interpreted as a bitmask: if bit 0 (the LSB) is set, then timestamps other than the revision date are propagated; if bit 1 is set, the revision date is propagated. If the third parameter to `rmscopy' is 0, then it behaves much like the DCL COPY command: if the name or type of the output file was explicitly specified, then no timestamps are propagated, but if they were taken implicitly from the input filespec, then all timestamps other than the revision date are propagated. If this parameter is not supplied, it defaults to 0. Like copy, `rmscopy' returns 1 on success. If an error occurs, it sets $!, deletes the output file, and returns 0. RETURN ====== All functions return 1 on success, 0 on failure. $! will be set if an error was encountered. AUTHOR ====== File::Copy was written by Aaron Sherman ** in 1995, and updated by Charles Bailey ** in 1996.  File: pm.info, Node: File/CounterFile, Next: File/Descriptions, Prev: File/Copy, Up: Module List Persistent counter class ************************ NAME ==== File::CounterFile - Persistent counter class SYNOPSIS ======== use File::CounterFile; $c = new File::CounterFile "COUNTER", "aa00"; $id = $c->inc; open(F, ">F$id"); DESCRIPTION =========== This module implements a persistent counter class. Each counter is represented by a separate file in the file system. File locking is applied, so multiple processes might try to access the same counters at the same time without risk of counter destruction. You give the file name as the first parameter to the object constructor (new). The file is created if it does not exist. If the file name does not start with "/" or ".", then it is interpreted as a file relative to `$File::CounterFile::DEFAULT_DIR'. The default value for this variable is initialized from the environment variable TMPDIR, or `/usr/tmp' is no environment variable is defined. You may want to assign a different value to this variable before creating counters. If you pass a second parameter to the constructor, that sets the initial value for a new counter. This parameter only takes effect when the file is created (i.e. it does not exist before the call). When you call the `inc()' method, you increment the counter value by one. When you call `dec()' the counter value is decrementd. In both cases the new value is returned. The `dec()' method only works for numerical counters (digits only). You can peek at the value of the counter (without incrementing it) by using the value() method. The counter can be locked and unlocked with the lock() and unlock() methods. Incrementing and value retrieval is faster when the counter is locked, because we do not have to update the counter file all the time. You can query whether the counter is locked with the `locked()' method. There is also an operator overloading interface to the File::CounterFile object. This means that you might use the `++' operator for incrementing the counter, - operator for decrementing and you can interpolate counters diretly into strings. BUGS ==== It uses flock(2) to lock the counter file. This does not work on all systems. Perhaps we should use the File::Lock module? COPYRIGHT ========= Copyright (c) 1995-1998 Gisle Aas. All rights reserved. This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. AUTHOR ====== Gisle Aas  File: pm.info, Node: File/Descriptions, Next: File/DosGlob, Prev: File/CounterFile, Up: Module List Perl extension for getting file descriptions ******************************************** NAME ==== File::Descriptions - Perl extension for getting file descriptions SYNOPSIS ======== use File::Descriptions; $d = new File::Descriptions; %descriptions = $d->gethash($directory); DESCRIPTION =========== This extension retrieves file descriptions from common mirror distributions like SimtelNet, Debian, etc... It should auto-recognize the presence of file descriptions for a particular type soon there will be more methods implemented AUTHOR ====== Pedro Leite, leite@ua.pt SEE ALSO ======== perl(1).  File: pm.info, Node: File/DosGlob, Next: File/FDpasser, Prev: File/Descriptions, Up: Module List DOS like globbing and then some ******************************* NAME ==== File::DosGlob - DOS like globbing and then some SYNOPSIS ======== require 5.004; # override CORE::glob in current package use File::DosGlob 'glob'; # override CORE::glob in ALL packages (use with extreme caution!) use File::DosGlob 'GLOBAL_glob'; @perlfiles = glob "..\\pe?l/*.p?"; print <..\\pe?l/*.p?>; # from the command line (overrides only in main::) > perl -MFile::DosGlob=glob -e "print <../pe*/*p?>" DESCRIPTION =========== A module that implements DOS-like globbing with a few enhancements. It is largely compatible with perlglob.exe (the M$ setargv.obj version) in all but one respect-it understands wildcards in directory components. For example, `<..\\l*b\\file/*glob.p?'> will work as expected (in that it will find something like '..\lib\File/DosGlob.pm' alright). Note that all path components are case-insensitive, and that backslashes and forward slashes are both accepted, and preserved. You may have to double the backslashes if you are putting them in literally, due to double-quotish parsing of the pattern by perl. Spaces in the argument delimit distinct patterns, so `glob('*.exe *.dll')' globs all filenames that end in `.exe' or `.dll'. If you want to put in literal spaces in the glob pattern, you can escape them with either double quotes, or backslashes. e.g. `glob('c:/"Program Files"/*/*.dll')', or `glob('c:/Program\ Files/*/*.dll')'. The argument is tokenized using `Text::ParseWords::parse_line()', so see *Note Text/ParseWords: Text/ParseWords, for details of the quoting rules used. Extending it to csh patterns is left as an exercise to the reader. EXPORTS (by request only) ========================= glob() BUGS ==== Should probably be built into the core, and needs to stop pandering to DOS habits. Needs a dose of optimizium too. AUTHOR ====== Gurusamy Sarathy HISTORY ======= * Support for globally overriding glob() (GSAR 3-JUN-98) * Scalar context, independent iterator context fixes (GSAR 15-SEP-97) * A few dir-vs-file optimizations result in glob importation being 10 times faster than using perlglob.exe, and using perlglob.bat is only twice as slow as perlglob.exe (GSAR 28-MAY-97) * Several cleanups prompted by lack of compatible perlglob.exe under Borland (GSAR 27-MAY-97) * Initial version (GSAR 20-FEB-97) SEE ALSO ======== perl perlglob.bat Text::ParseWords  File: pm.info, Node: File/FDpasser, Next: File/Find, Prev: File/DosGlob, Up: Module List Perl extension for blah blah blah ********************************* NAME ==== File::FDpasser - Perl extension for blah blah blah SYNOPSIS ======== use File::FDpasser; @fd=spipe(); die "spipe() failed\n" if !defined(@fd); $LS=endp_create("/tmp/openserver") || die "endp_create: $!\n"; $rin = ''; vec($rin,fileno($LS),1) = 1; $timeout=0.5; ($nfound,$timeleft) = select($rout=$rin, '', $eout=$rin, $timeout); $fh=serv_accept_fh($LS,$uid) || die "serv_accept: $!\n"; $rc=send_file($fh,*FH{IO}); $fh=endp_connect("/tmp/openserver") || die "endp_connect: $!\n"; $newfh=recv_fh($fh); DESCRIPTION =========== File::FDpasser is a module for passing open filedescriptors to and from other scripts or even other programs. An endpoint is just a Filehandle that can be used to send and receive filehandles over. To create two endpoints before forking spipe() is used - it returns two endpoints or undef on failiure. If the processes are unrelated or can not use spipe() for some reason, it is possible to create a 'server endpoint' in the filesystem by calling endp_create(). That endpoint can be polled for incomming connections similar to how sockets are polled for incomming connection. To accept an incomming connection serv_accept_fh() is used. It returns a filehandle or undef on failiure. To connect to a server endpoint from a client program endp_connect() is used. It returns a filehandle to an open connection. Irregardless of how the endpoints were created send_file() is used to send an open filehandle to the process who has other end of the pipe or socket. The first argument to send_file is the connection to send the open handle over. The second argument is the actual handle to send. Similarly recv_fh() is always used to receive an open filehandle. Both return false on failiure. How does it work ================ Under BSD derived systems open filedescriptors are passed over unix domain sockets. SysV systems however pass them over streams. This means to create that under BSD socketpair() is used to create the socket endpoints. While SysV uses pipe() since pipe on SysV creates a bidirectional stream based pipe. This is all nice and dandy if you are going to fork later on since both child and parent are going to have an endpoint to read from or write to. endp_create() is used to create a server endpoint that can be polled for incomming connections with poll or select. Under BSD the perl call socket() is used to create a Unix Domain Socket in the filesystem. Under SysV the perl function pipe() is called followed by an XS function that pushes the conn_ld module on one end of the stream pipe and then calles fattach to attach the pipe end to a point in the filesystem. To connect to a server endpoint in BSD a socket is created (but not bound to any point in the filesystem) and a connect call is made. In SysV a normal open() in perl is made. The actuall sending of filedescriptors is done with XS functions that under BSD use sendmsg for sending and recvmsg for reciving. SysV uses an ioctl call to send and receive (getmsg is actually a wrapper for receiving the fd - a uid of the connecting process is discarded since it's not reliably avaliable for BSD system too). AUTHOR ====== amh@mbl.is SEE ALSO ======== perl(1), sendmsg, recvmsg, ioctl, ioctl_list, select, poll. IO::Handle. http://gauss.mbl.is/~amh/FDpasser/. Advanced Programming in the UNIX Environment, Addison-Wesley, 1992. UNIX Network Programming, Prentice Hall, 1990.  File: pm.info, Node: File/Find, Next: File/Flock, Prev: File/FDpasser, Up: Module List traverse a file tree ******************** NAME ==== find - traverse a file tree finddepth - traverse a directory structure depth-first SYNOPSIS ======== use File::Find; find(\&wanted, '/foo', '/bar'); sub wanted { ... } use File::Find; finddepth(\&wanted, '/foo', '/bar'); sub wanted { ... } use File::Find; find({ wanted => \&process, follow => 1 }, '.'); DESCRIPTION =========== The first argument to find() is either a hash reference describing the operations to be performed for each file, or a code reference. Here are the possible keys for the hash: `wanted' The value should be a code reference. This code reference is called *the wanted() function* below. `bydepth' Reports the name of a directory only AFTER all its entries have been reported. Entry point finddepth() is a shortcut for specifying `{ bydepth =' 1 }> in the first argument of find(). `follow' Causes symbolic links to be followed. Since directory trees with symbolic links (followed) may contain files more than once and may even have cycles, a hash has to be built up with an entry for each file. This might be expensive both in space and time for a large directory tree. See *follow_fast* and *follow_skip* below. If either *follow* or *follow_fast* is in effect: * It is guarantueed that an lstat has been called before the user's *wanted()* function is called. This enables fast file checks involving _. * There is a variable `$File::Find::fullname' which holds the absolute pathname of the file with all symbolic links resolved `follow_fast' This is similar to *follow* except that it may report some files more than once. It does detect cycles however. Since only symbolic links have to be hashed, this is much cheaper both in space and time. If processing a file more than once (by the user's *wanted()* function) is worse than just taking time, the option *follow* should be used. `follow_skip' `follow_skip==1', which is the default, causes all files which are neither directories nor symbolic links to be ignored if they are about to be processed a second time. If a directory or a symbolic link are about to be processed a second time, File::Find dies. `follow_skip==0' causes File::Find to die if any file is about to be processed a second time. `follow_skip==2' causes File::Find to ignore any duplicate files and dirctories but to proceed normally otherwise. `no_chdir' Does not chdir() to each directory as it recurses. The wanted() function will need to be aware of this, of course. In this case, $_ will be the same as `$File::Find::name'. untaint If find is used in taint-mode (-T command line switch or if EUID != UID or if EGID != GID) then internally directory names have to be untainted before they can be cd'ed to. Therefore they are checked against a regular expression *untaint_pattern*. Note, that all names passed to the user's *wanted()* function are still tainted. `untaint_pattern' See above. This should be set using the qr quoting operator. The default is set to `qr|^([-+@\w./]+)$|'. Note that the paranthesis which are vital. `untaint_skip' If set, directories (subtrees) which fail the *untaint_pattern* are skipped. The default is to 'die' in such a case. The wanted() function does whatever verifications you want. `$File::Find::dir' contains the current directory name, and $_ the current filename within that directory. `$File::Find::name' contains the complete pathname to the file. You are chdir()'d to `$File::Find::dir' when the function is called, unless `no_chdir' was specified. When or are in effect there is also a `$File::Find::fullname'. The function may set `$File::Find::prune' to prune the tree unless `bydepth' was specified. Unless `follow' or `follow_fast' is specified, for compatibility reasons (find.pl, find2perl) there are in addition the following globals available: `$File::Find::topdir', `$File::Find::topdev', `$File::Find::topino', `$File::Find::topmode' and `$File::Find::topnlink'. This library is useful for the find2perl tool, which when fed, find2perl / -name .nfs\* -mtime +7 \ -exec rm -f {} \; -o -fstype nfs -prune produces something like: sub wanted { /^\.nfs.*\z/s && (($dev, $ino, $mode, $nlink, $uid, $gid) = lstat($_)) && int(-M _) > 7 && unlink($_) || ($nlink || (($dev, $ino, $mode, $nlink, $uid, $gid) = lstat($_))) && $dev < 0 && ($File::Find::prune = 1); } Set the variable `$File::Find::dont_use_nlink' if you're using AFS, since AFS cheats. Here's another interesting wanted function. It will find all symlinks that don't resolve: sub wanted { -l && !-e && print "bogus link: $File::Find::name\n"; } See also the script `pfind' on CPAN for a nice application of this module. CAVEAT ====== Be aware that the option to follow symblic links can be dangerous. Depending on the structure of the directory tree (including symbolic links to directories) you might traverse a given (physical) directory more than once (only if `follow_fast' is in effect). Furthermore, deleting or changing files in a symbolically linked directory might cause very unpleasant surprises, since you delete or change files in an unknown directory.  File: pm.info, Node: File/Flock, Next: File/FlockDir, Prev: File/Find, Up: Module List file locking with flock *********************** NAME ==== File::Flock - file locking with flock SYNOPSIS ======== use File::Flock; lock($filename); lock($filename, 'shared'); lock($filename, undef, 'nonblocking'); lock($filename, 'shared', 'nonblocking'); unlock($filename); my $lock = new File::Flock '/somefile'; lock_rename($oldfilename, $newfilename) DESCRIPTION =========== Lock files using the flock() call. If the file to be locked does not exist, then the file is created. If the file was created then it will be removed when it is unlocked assuming it's still an empty file. Locks can be created by new'ing a *File::Flock* object. Such locks are automatically removed when the object goes out of scope. The unlock() method may also be used. *lock_rename()* is used to tell File::Flock when a file has been renamed (and thus the locking data that is stored based on the filename should be moved to a new name). AUTHOR ====== David Muir Sharnoff,  File: pm.info, Node: File/FlockDir, Next: File/Glob, Prev: File/Flock, Up: Module List override perl flock() for network or portability purposes ********************************************************* NAME ==== FlockDir - override perl flock() for network or portability purposes SYNOPSIS ======== use File::FlockDir qw (open close flock); open (FH, ">$path"); flock(FH, 2); close FH; DESCRIPTION =========== A flock module for Windows9x and other systems lacking a good perl flock() function (not platform specific) Usage: use File::FlockDir qw (open close flock); OR (careful) use File::FlockDir qw (GLOBAL_open GLOBAL_close GLOBAL_flock); Rationale: flock on Win95/98 is badly broken but perl code needs to be portable. One way to do this is to override perl's open(), flock(), and close(). We then get an absolute file specification for all opened files and and use it in a hash to create a unique lock for the file using the File::LockDir module from *Perl Cookbook*, by Christiansen and Torkington (O'Reilly, 1998). This module may be included in the CPAN distribution but belongs to those authors. New code is deliberately kept at a minimum. As with nflock(), this will allow flock() to work over a network (usually). KNOWN PROBLEMS AND LIMITATIONS ============================== * May be slow compared to unix flock(). This is mainly due to the fact it depends upon non-buffered disk writes (directory creation) for its implementation. May be speeded up somewhat by importing and setting the variable *$Max_SH_Processes* to a smaller value as long as no more than a few processes will be using shared locks at a time on any one file. * Abnormal termination may leave File::LockDir entries still on the drive. This means the directory locks set by File::LockDir may have to be removed after a system crash to prevent the module from assuming that files locked at the time of the crash are still locked later. This may be partially overcome by importing and setting the variable *$Assume_LockDir_Zombie_Minutes* to a value equal to the maximal number of minutes a lock is to be allowed to exist (defaults to one week or 10040 minutes). * Since the implementation creates a subdirectory in the directory containing the file that you flock(), you must have permission to create a directory where the file is located in order to flock() that file over the network. CREDITS ======= *Perl Cookbook*, by Tom Christiansen and Nathan Torkington. This module is an extension of *Perl Cookbook*'s nflock(), in chapter 7, section 21 (7.21, pp 264-266). AUTHOR ====== William Herrera  File: pm.info, Node: File/Glob, Next: File/HomeDir, Prev: File/FlockDir, Up: Module List Perl extension for BSD glob routine *********************************** NAME ==== File::Glob - Perl extension for BSD glob routine SYNOPSIS ======== use File::Glob ':glob'; @list = glob('*.[ch]'); $homedir = glob('~gnat', GLOB_TILDE | GLOB_ERR); if (GLOB_ERROR) { # an error occurred reading $homedir } ## override the core glob (core glob() does this automatically ## by default anyway, since v5.6.0) use File::Glob ':globally'; my @sources = <*.{c,h,y}> ## override the core glob, forcing case sensitivity use File::Glob qw(:globally :case); my @sources = <*.{c,h,y}> ## override the core glob forcing case insensitivity use File::Glob qw(:globally :nocase); my @sources = <*.{c,h,y}> DESCRIPTION =========== File::Glob implements the FreeBSD glob(3) routine, which is a superset of the POSIX glob() (described in IEEE Std 1003.2 "POSIX.2"). The glob() routine takes a mandatory pattern argument, and an optional flags argument, and returns a list of filenames matching the pattern, with interpretation of the pattern modified by the flags variable. The POSIX defined flags are: `GLOB_ERR' Force glob() to return an error when it encounters a directory it cannot open or read. Ordinarily glob() continues to find matches. `GLOB_MARK' Each pathname that is a directory that matches the pattern has a slash appended. `GLOB_NOCASE' By default, file names are assumed to be case sensitive; this flag makes glob() treat case differences as not significant. `GLOB_NOCHECK' If the pattern does not match any pathname, then glob() returns a list consisting of only the pattern. If `GLOB_QUOTE' is set, its effect is present in the pattern returned. `GLOB_NOSORT' By default, the pathnames are sorted in ascending ASCII order; this flag prevents that sorting (speeding up glob()). The FreeBSD extensions to the POSIX standard are the following flags: `GLOB_BRACE' Pre-process the string to expand `{pat,pat,...}' strings like csh(1). The pattern '{}' is left unexpanded for historical reasons (and csh(1) does the same thing to ease typing of find(1) patterns). `GLOB_NOMAGIC' Same as `GLOB_NOCHECK' but it only returns the pattern if it does not contain any of the special characters "*", "?" or "[". `NOMAGIC' is provided to simplify implementing the historic csh(1) globbing behaviour and should probably not be used anywhere else. `GLOB_QUOTE' Use the backslash ('\') character for quoting: every occurrence of a backslash followed by a character in the pattern is replaced by that character, avoiding any special interpretation of the character. (But see below for exceptions on DOSISH systems). `GLOB_TILDE' Expand patterns that start with '~' to user name home directories. `GLOB_CSH' For convenience, `GLOB_CSH' is a synonym for `GLOB_BRACE | GLOB_NOMAGIC | GLOB_QUOTE | GLOB_TILDE'. The POSIX provided `GLOB_APPEND', `GLOB_DOOFFS', and the FreeBSD extensions `GLOB_ALTDIRFUNC', and `GLOB_MAGCHAR' flags have not been implemented in the Perl version because they involve more complex interaction with the underlying C structures. DIAGNOSTICS =========== glob() returns a list of matching paths, possibly zero length. If an error occurred, &File::Glob::GLOB_ERROR will be non-zero and $! will be set. &File::Glob::GLOB_ERROR is guaranteed to be zero if no error occurred, or one of the following values otherwise: `GLOB_NOSPACE' An attempt to allocate memory failed. `GLOB_ABEND' The glob was stopped because an error was encountered. In the case where glob() has found some matching paths, but is interrupted by an error, glob() will return a list of filenames and set &File::Glob::ERROR. Note that glob() deviates from POSIX and FreeBSD glob(3) behaviour by not considering `ENOENT' and `ENOTDIR' as errors - glob() will continue processing despite those errors, unless the `GLOB_ERR' flag is set. Be aware that all filenames returned from File::Glob are tainted. NOTES ===== * If you want to use multiple patterns, e.g. `glob "a* b*"', you should probably throw them in a set as in `glob "{a*,b*}'. This is because the argument to glob isn't subjected to parsing by the C shell. Remember that you can use a backslash to escape things. * On DOSISH systems, backslash is a valid directory separator character. In this case, use of backslash as a quoting character (via GLOB_QUOTE) interferes with the use of backslash as a directory separator. The best (simplest, most portable) solution is to use forward slashes for directory separators, and backslashes for quoting. However, this does not match "normal practice" on these systems. As a concession to user expectation, therefore, backslashes (under GLOB_QUOTE) only quote the glob metacharacters '[', ']', '{', '}', '-', '~', and backslash itself. All other backslashes are passed through unchanged. * Win32 users should use the real slash. If you really want to use backslashes, consider using Sarathy's File::DosGlob, which comes with the standard Perl distribution. AUTHOR ====== The Perl interface was written by Nathan Torkington , and is released under the artistic license. Further modifications were made by Greg Bacon and Gurusamy Sarathy . The C glob code has the following copyright: Copyright (c) 1989, 1993 The Regents of the University of California. All rights reserved. This code is derived from software contributed to Berkeley by Guido van Rossum. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. Neither the name of the University nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.  File: pm.info, Node: File/HomeDir, Next: File/LckPwdF, Prev: File/Glob, Up: Module List get home directory for self or other users ****************************************** NAME ==== File::HomeDir - get home directory for self or other users SYNOPSIS ======== use File::HomeDir; print "My dir is ", home(), " and root's is ", home('root'), "\n"; print "My dir is $~{''} and root's is $~{root}\n"; # These both print the same thing, something like: # "My dir is /home/user/mojo and root's is /" DESCRIPTION =========== This module provides a function, `home', and also ties the in-all-packages variable `%~'. home() Returns a filespec to this user's home directory. home($user) Returns a filespec to the home directory of the given user, or undef if no such user. Note that the argument to this must be a defined value, and mustn't be a zero-length string, or a fatal error will result. `$~{$user}' `$~{username}' `"...$~{$user}..."' `"...$~{username}..."' This calls home($user) or `home('username')' - except that if you ask for `$~{some_user}' and there is no such user, a fatal error results! Note that this is especially useful in doublequotish strings, like: print "Jojo's .newsrc is ", -s "$~{jojo}/.newsrc", "b long!\n"; # (helpfully dies if there is no user 'jojo') If you want to avoid the fatal errors, first test the value of `home('jojo')', which will return undef (instead of dying) in case of there being no such user. Note, however, that if the hash key is "" or undef (whether thru being a literal "", or a scalar whose value is empty-string or undef), then this returns zero-argument home(), i.e., your home directory: `$~{""}' `$~{undef}' `"...$~{''}..."' These all return home(), i.e., your home directory. If running under an OS that doesn't implement `getpwid', this library tries to provide a sane return value for the no-argument home(). Under MacOS, for example, it tries returning the pathspec to the desktop folder. See source for full details. Under OSs that don't implement getpwnam (as home($user) calls), you will always get a failed lookup, just as if you'd tried to look up the home dir for a nonexistent user on an OS that *does* support getpwnam. BUGS AND CAVEATS ================ * One-argument `home($username)' is memoized. Read the source if you need it unmemoized. * According to the fileio.c in one version of Emacs, MSWindows (NT?) does have the concept of users having home directories, more or less. But I don't know if MSWin ports of Perl allow accessing that with getpwnam. I hear that it (currently) doesn't. * This documentation gets garbled by some AIX manual formatters. Consider `perldoc -t File::HomeDir' instead. COPYRIGHT ========= Copyright (c) 2000 Sean M. Burke. All rights reserved. This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. AUTHOR ====== Sean M. Burke `sburke@cpan.org'  File: pm.info, Node: File/LckPwdF, Next: File/Listing, Prev: File/HomeDir, Up: Module List Lock and unlock the passwd and shadow files with lckpwdf and ulckpwdf ********************************************************************* NAME ==== File::LckPwdF - Lock and unlock the passwd and shadow files with lckpwdf and ulckpwdf SYNOPSIS ======== use File::LckPwdF; (lock_passwd(15)) || (die "Can't lock password file:\n$! stopped"); # ... do stuff with the passwd file ... (unlock_passwd()) || (die "Can't unlock password file:\n$! stopped"); DESCRIPTION =========== This is a perl module to use *lckpwdf(3)* and *ulckpwdf(3)* to lock the `/etc/passwd' and (if present) `/etc/shadow' files. Functions exported automatically -------------------------------- *lock_passwd($timeout)* $timeout works as follows: 1. The initial time is checked. 2. If $timeout is 0, it tries *lckpwdf()* until it succeeds, waiting a random time in between. 3. If $timeout is above 0, it tries *lckpwdf()* once. If that (or any following *lckpwdf()*) succeeds, it returns 1. It will try *lckpwdf()* until either it succeeds or the time is greater than the initial time plus $timeout. In the latter case, it returns 0. It waits a random time in between tries of *lckpwdf()*. The random timeout is controlled by *$File::LckPwdF::Rand_Wait*, which is exported on request. It is used via sleep int(rand($Rand_Wait) + 1); inside an until loop. This sleep is only done if *$File::LckPwdF::Rand_Wait* is above 0. $timeout defaults to *$File::LckPwdF::Default_Timeout*, which is also exported on request; the initial setting of *$File::LckPwdF::Default_Timeout* (the default default) is 15 seconds. The default setting for *$File::LckPwdF::Rand_Wait* is 10 seconds. *unlock_passwd()* This function uses *ulckpwdf()*. If *lock_passwd()* has previously been used to lock the passwd file, and *unlock_passwd()* has not been used to lock it, then it will be used to unlock the passwd file in an END: statement. (Admittedly, with many implementations of *lckpwdf()* this is not necessary, since when a process exits it loses the passwd file lock; it is present as a safety measure for those systems for which this is not true.) Functions exported by request ----------------------------- *lckpwdf()* *ulckpwdf()* These are the xs-loaded versions of *lckpwdf(3)* and *ulckpwdf(3)*, respectively. RETURN VALUE ============ The *lock_passwd()* and *unlock_passwd()* functions return 1 on success and 0 on failure. The return values for *lckpwdf()* and *ulckpwdf()* are the same as for the system versions (*lckpwdf(3)* and *ulckpwdf(3)*). ERRORS ====== If the effective UID is not 0, then *lock_passwd()* and *unlock_passwd()* set $! to *EACCES* if they fail (they do try once, just in case you've got a *really* weird setup). If the effective UID is 0, in the event of failure, *lock_passwd()* sets $! to: 1. if you've already locked the file through *lock_passwd()*, *EALREADY* 2. *EAGAIN* (or *EWOULDBLOCK*, if *EAGAIN* isn't present on your system and *EWOULDBLOCK* is; *$File::LckPwdF::EAGAIN*, which is exported on request, is equal to the value returned). *unlock_passwd()*, in the event of failure, sets $! to: 1. if you've already unlocked the file via *unlock_passwd()* or haven't locked it via *lock_passwd()*, *EALREADY*. 2. *EINVAL*. If you try to use a negative number for $timeout with *lock_passwd($timeout)*, it carps, returns 0, and sets $! to *EINVAL*. CAVEATS ======= This program only works if your system has *lckpwdf(3)* and *ulckpwdf(3)*. This should be true of SVR4 systems; others will vary. If you use *lock_passwd()* and *unlock_passwd()*, *lckpwdf(3)* and *ulckpwdf(3)* need to have return values of 0+ for success and below 0 (usually -1) for failure. The timeout period for *lock_passwd()* is approximate, since many versions of *lckpwdf()* will keep trying for a total of 15 seconds to lock the passwd (and possibly shadow) files before they return an appropriate value. This module only keeps track on its own of whether the passwd file is locked if you always use *lock_passwd()* and *unlock_passwd()*. If you use *lckpwdf()* or *ulckpwdf()* by themselves for locking and unlocking, you will need to set *$File::LckPwdF::Passwd_Locked* to 1 for locked and 0 for unlocked yourself. BUGS ==== I haven't written any good automated tests for this program yet. If anyone's interested, be my guest (or for any other improvements, of course). AUTHOR ====== E. Allen Smith, . Copyright 1998. This software may be used, distributed, modified, etcetera under the same conditions as *perl*. FILES ===== `/etc/passwd', `/etc/shadow' SEE ALSO ======== `perl(1)' in this node, `lckpwdf(3)' in this node, `ulckpwdf(3)' in this node  File: pm.info, Node: File/Listing, Next: File/MMagic, Prev: File/LckPwdF, Up: Module List parse directory listing *********************** NAME ==== parse_dir - parse directory listing SYNOPSIS ======== use File::Listing; for (parse_dir(`ls -l`)) { ($name, $type, $size, $mtime, $mode) = @$_; next if $type ne 'f'; # plain file #... } # directory listing can also be read from a file open(LISTING, "zcat ls-lR.gz|"); $dir = parse_dir(\*LISTING, '+0000'); DESCRIPTION =========== The parse_dir() routine can be used to parse directory listings. Currently it only understand Unix `'ls -l'' and `'ls -lR'' format. It should eventually be able to most things you might get back from a ftp server file listing (LIST command), i.e. VMS listings, NT listings, DOS listings,... The first parameter to parse_dir() is the directory listing to parse. It can be a scalar, a reference to an array of directory lines or a glob representing a filehandle to read the directory listing from. The second parameter is the time zone to use when parsing time stamps in the listing. If this value is undefined, then the local time zone is assumed. The third parameter is the type of listing to assume. The values will be strings like 'unix', 'vms', 'dos'. Currently only 'unix' is implemented and this is also the default value. Ideally, the listing type should be determined automatically. The fourth parameter specifies how unparseable lines should be treated. Values can be 'ignore', 'warn' or a code reference. Warn means that the perl warn() function will be called. If a code reference is passed, then this routine will be called and the return value from it will be incorporated in the listing. The default is 'ignore'. Only the first parameter is mandatory. The return value from parse_dir() is a list of directory entries. In a scalar context the return value is a reference to the list. The directory entries are represented by an array consisting of [ $filename, $filetype, $filesize, $filetime, $filemode ]. The $filetype value is one of the letters 'f', 'd', 'l' or '?'. The $filetime value is the seconds since Jan 1, 1970. The $filemode is a bitmask like the mode returned by stat(). CREDITS ======= Based on lsparse.pl (from Lee McLoughlin's ftp mirror package) and Net::FTP's parse_dir (Graham Barr).  File: pm.info, Node: File/MMagic, Next: File/MkTemp, Prev: File/Listing, Up: Module List Guess file type *************** NAME ==== File::MMagic - Guess file type SYNOPSIS ======== use File::MMagic; use FileHandle; $mm = new File::MMagic; # use internal magic file # $mm = File::MMagic::new('/etc/magic'); # use external magic file $res = $mm->checktype_filename("/somewhere/unknown/file"); $fh = new FileHandle "< /somewhere/unknown/file2"; $res = $mm->checktype_filehandle($fh); $fh->read($data, 0x8564); $res = $mm->checktype_contents($data); ABSTRACT ======== This perl library uses perl5 objects to guess file type from filename and/or filehandle. DESCRIPTION =========== checktype_filename(), checktype_filehandle() and checktype_contents returns string contains file type with MIME mediatype format. COPYRIGHT ========= This program is originated from file.kulp that is a production of The Unix Reconstruction Projct. Copyright (c) 1999 NOKUBI Takatsugu . There is no warranty for the program. This product includes software developed by the Apache Group for use in the Apache HTTP server project (http://www.apache.org/). License for the program is followed the original software. The license is below. This program is free and open software. You may use, copy, modify, distribute and sell this program (and any modified variants) in any way you wish, provided you do not restrict others to do the same, except for the following consideration. I read some of Ian F. Darwin's BSD C implementation, to try to determine how some of this was done since the specification is a little vague. I don't believe that this perl version could be construed as an "altered version", but I did grab the tokens for identifying the hard-coded file types in names.h and copied some of the man page. Here's his notice: * Copyright (c) Ian F. Darwin, 1987. * Written by Ian F. Darwin. * * This software is not subject to any license of the American Telephone * and Telegraph Company or of the Regents of the University of California. * * Permission is granted to anyone to use this software for any purpose on * any computer system, and to alter it and redistribute it freely, subject * to the following restrictions: * * 1. The author is not responsible for the consequences of use of this * software, no matter how awful, even if they arise from flaws in it. * * 2. The origin of this software must not be misrepresented, either by * explicit claim or by omission. Since few users ever read sources, * credits must appear in the documentation. * * 3. Altered versions must be plainly marked as such, and must not be * misrepresented as being the original software. Since few users * ever read sources, credits must appear in the documentation. * * 4. This notice may not be removed or altered. The following is the Apache License. This program contains the magic file that derived from the Apache HTTP Server. * Copyright (c) 1995-1999 The Apache Group. All rights reserved. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: * * 1. Redistributions of source code must retain the above copyright * notice, this list of conditions and the following disclaimer. * * 2. Redistributions in binary form must reproduce the above copyright * notice, this list of conditions and the following disclaimer in * the documentation and/or other materials provided with the * distribution. * * 3. All advertising materials mentioning features or use of this * software must display the following acknowledgment: * "This product includes software developed by the Apache Group * for use in the Apache HTTP server project (http://www.apache.org/)." * * 4. The names "Apache Server" and "Apache Group" must not be used to * endorse or promote products derived from this software without * prior written permission. For written permission, please contact * apache@apache.org. * * 5. Products derived from this software may not be called "Apache" * nor may "Apache" appear in their names without prior written * permission of the Apache Group. * * 6. Redistributions of any form whatsoever must retain the following * acknowledgment: * "This product includes software developed by the Apache Group * for use in the Apache HTTP server project (http://www.apache.org/)." * * THIS SOFTWARE IS PROVIDED BY THE APACHE GROUP ``AS IS'' AND ANY * EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE APACHE GROUP OR * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED * OF THE POSSIBILITY OF SUCH DAMAGE.