This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: IMAP/Admin, Next: INSPEC/BibTeX, Prev: IETF/ACE, Up: Module List Perl module for basic IMAP server administration ************************************************ NAME ==== IMAP::Admin - Perl module for basic IMAP server administration SYNOPSIS ======== use IMAP::Admin; $imap = IMAP::Admin->new('Server' => 'name.of.server.com', 'Login' => 'login_of_imap_administrator', 'Password' => 'password_of_imap_adminstrator', 'Port' => port# (143 is default), 'Separator' => ".", # default is a period 'SSL' => 1, # off by default # and any of the SSL_ options from IO::Socket::SSL ); $err = $imap->create("user.bob"); if ($err != 0) { print "$imap->{'Error'}\n"; } if ($err != 0) { print $imap->error; } $err = $imap->create("user.bob", "green"); $err = $imap->delete("user.bob"); $err = $imap->h_delete("user.bob"); $err = $imap->subscribe("user.bob"); $err = $imap->unsubscribe("user.bob"); $err = $imap->rename("bboard", "newbboard"); @quota = $imap->get_quotaroot("user.bob"); @quota = $imap->get_quota("user.bob"); $err = $imap->set_quota("user.bob", 10000); @acl = $imap->get_acl("user.bob"); $err = $imap->set_acl("user.bob", "admin", "lrswipdca", "joe", "lrs"); $err = $imap->delete_acl("user.bob", "joe", "admin"); @list = $imap->list("user.bob"); @list = $imap->list("user.b*"); $imap->{'Capability'} # this contains the Capabilities reply from the IMAP server $imap->close; # close open imap connection DESCRIPTION =========== IMAP::Admin provides basic IMAP server adminstration. It provides functions for creating and deleting mailboxes and setting various information such as quotas and access rights. It's interface should, in theory, work with any RFC compliant IMAP server, but I currently have only tested it against Carnegie Mellon University's Cyrus IMAP and Mirapoint's IMAP servers. It does a CAPABILITY check for specific extensions to see if they are supported. Operationally it opens a socket connection to the IMAP server and logs in with the supplied login and password. You then can call any of the functions to perform their associated operation. Separator on the new call is the hiearchical separator used by the imap server. It is defaulted to a period ("/" might be another popular one). SSL on the new call will attempt to make an SSL connection to the imap server. It does not fallback to a regular connection if it fails. It is off by default. IO::Socket::SSL requires a ca certificate, a client certificate, and a client private key. By default these are in current_directory/certs, respectively named ca-cert.pem, client-cert.pem, and client-key.pem. The location of this can be overridden by setting SSL_ca_file, SSL_cert_file, and SSL_key_file (you'll probably want to also set SSL_ca_path). I generated my ca cert and ca key with openssl: openssl req -x509 -newkey rsa:1024 -keyout ca-key.pem -out ca-cert.pem I generated my client key and cert with openssl: openssl req -new -newkey rsa:1024 -keyout client-key.pem -out req.pem -nodes openssl x509 -CA ca-cert.pem -CAkey ca-key.pem -req -in req.pem -out client-cert.pem -addtrust clientAuth -days 600 Setting up SSL Cyrus IMAP v 2.x (completely unofficial, but it worked for me) add these to your /etc/imapd.conf (remember to change /usr/local/cyrus/tls to wherever yours is) tls_ca_path: /usr/local/cyrus/tls tls_ca_file: /usr/local/cyrus/tls/ca-cert.pem tls_key_file: /usr/local/cyrus/tls/serv-key.pem tls_cert_file: /usr/local/cyrus/tls/serv-cert.pem For my server key I used a self signed certificate: openssl req -x509 -newkey rsa:1024 -keyout serv-key.pem -out serv-cert.pem -nodes -extensions usr_cert (in openssl.cnf I have nsCertType set to server) I also added this to my /etc/cyrus.conf, it shouldn't strictly be necessary as clients that are RFC2595 compliant can issue a STARTTLS to initiate the secure layer, but currently IMAP::Admin doesn't issue this command (in SERVICES section): imap2 cmd="imapd -s" listen="simap" prefork=0 where simap in /etc/services is: simap 993/tcp # IMAP over SSL MAILBOX FUNCTIONS ----------------- RFC2060 commands. These should work with any RFC2060 compliant IMAP mail servers. create makes new mailboxes. Cyrus IMAP, for normal mailboxes, has the user. prefix. create returns a 0 on success or a 1 on failure. An error message is placed in the object->{'Error'} variable on failure. create takes an optional second argument that is the partition to create the mailbox in (I don't know if partition is rfc or not, but it is supported by Cyrus IMAP and Mirapoint). delete destroys mailboxes. The action delete takes varies from server to server depending on it's implementation. On some servers this is a hierarchical delete and on others this will delete only the mailbox specified and only if it has no subfolders that are marked \Noselect. If you wish to insure a hierarchical delete use the h_delete command as it deletes starting with the subfolders and back up to the specified mailbox. delete returns a 0 on success or a 1 on failure. An error message is placed in the object->{'Error'} variable on failure. h_delete hierarchical delete (I don't believe this is RFC anything) deletes a mailbox and all sub-mailboxes/subfolders that belong to it. It basically gets a subfolder list and does multiple delete calls. It returns 0 on sucess or a 1 on failure with the error message from delete being put into the object->{'Error'} variable. Don't forget to set your Separator if it's not a period. list lists mailboxes. list accepts wildcard matching subscribe/unsubscribe does this action on given mailbox. rename renames a mailbox. IMAP servers seem to be peculiar about how they implement this, so I wouldn't necessarily expect it to do what you think it should. QUOTA FUNCTIONS --------------- RFC2087 imap extensions. These are supported by Cyrus IMAP and Mirapoint. get_quotaroot and get_quota retrieve quota information. They return an array on success and undef on failure. In the event of a failure the error is place in the object->{'Error'} variable. The array has three elements for each item in the quota. $quota[0] <- mailbox name $quota[1] <- quota amount used in kbytes $quota[2] <- quota in kbytes set_quota sets the quota. The number is in kilobytes so 10000 is approximately 10Meg. set_quota returns a 0 on success or a 1 on failure. An error message is placed in the object->{'Error'} variable on failure. To delete a quota do a set_quota($mailbox, "none"); ACCESS CONTROL FUNCTIONS ------------------------ RFC2086 imap extensions. These are supported by Cyrus IMAP, Mirapoint and probably many others. get_acl retrieves acl information. It returns an array on success and under on failure. In the event of a failure the error is placed in the object->{'Error'} variable. The array contains a pair for each person who has an acl on this mailbox $acl[0] user who has acl information $acl[1] acl information $acl[2] next user ... set_acl set acl information for a single mailbox. You can specify more the one user's rights on the same set call. It returns a 0 on success or a 1 on failure. An error message is placed in the object->{'Error'} variable on failure. delete_acl removes acl information on a single mailbox for the given users. You can specify more the one users rights to be removed in the same delete_acl call. It returns a 0 on success or a 1 on failure. An error message is placed int the object->{'Error'} variable on failure. standard rights (rfc2086): l - lookup (mailbox is visible to LIST/LSUB commands) r - read (SELECT the mailbox, perform CHECK, FETCH, PARTIAL, SEARCH, and COPY) s - keep seen/unssen information across sessions (STORE SEEN flag) w - write (STORE flags other then SEEN and DELETED) i - insert (perform APPEND and COPY into mailbox) p - post (send mail to submission address for mailbox) c - create (CREATE new sub-mailboxes) (*note* allows for delete of sub mailboxes as well) d - delete (STORE DELETED flag, perform EXPUNGE) a - administer (perform SETACL) The access control information is from Cyrus IMAP. read = "lrs" post = "lrsp" append = "lrsip" write = "lrswipcd" all = "lrswipcda" KNOWN BUGS ========== Currently all the of the socket traffic is handled via prints and _read. This means that some of the calls could hang if the socket connection is broken. Eventually the will be properly selected and timed. LICENSE ======= This is licensed under the Artistic license (same as perl). A copy of the license is included in this package. The file is called Artistic. If you use this in a product or distribution drop me a line, 'cause I am always curious about that... CVS REVISION ============ $Id: Admin.pm,v 1.31 2000/11/29 06:06:44 eric Exp $ AUTHOR ====== Eric Estabrooks, eric@urbanrage.com SEE ALSO ======== perl(1).  File: pm.info, Node: INSPEC/BibTeX, Next: INSPEC/Retriever, Prev: IMAP/Admin, Up: Module List Perl extensions to convert INSPEC data from INSPEC::Retriever to BibTeX format ****************************************************************************** NAME ==== INSPEC::BibTeX - Perl extensions to convert INSPEC data from INSPEC::Retriever to BibTeX format SYNOPSIS ======== use INSPEC::BibTeX; DESCRIPTION =========== These routines allow you to to convert INSPEC data from INSPEC::Retriever to BibTeX format EXAMPLES ======== AUTHOR ====== Vincent LaBella vlabella@uark.edu COPYRIGHT ========= Copyright (C) 2000 Vincent LaBella. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. WARRANTY ======== THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. SEE ALSO ======== perl(1).  File: pm.info, Node: INSPEC/Retriever, Next: IO, Prev: INSPEC/BibTeX, Up: Module List Perl extensions to extract information from the INSPEC database provided by AXIOM ********************************************************************************* NAME ==== INSPEC::Retriever - Perl extensions to extract information from the INSPEC database provided by AXIOM SYNOPSIS ======== use INSPEC::Retriever; DESCRIPTION =========== These routines allow you to extract information about a citation or paper from a the INSPEC database provided by AXIOM EXAMPLES ======== AUTHOR ====== Vincent LaBella vlabella@uark.edu COPYRIGHT ========= Copyright (C) 2000 Vincent LaBella. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. WARRANTY ======== THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. SEE ALSO ======== perl(1).  File: pm.info, Node: IO, Next: IO/AtomicFile, Prev: INSPEC/Retriever, Up: Module List load various IO modules *********************** NAME ==== IO - load various IO modules SYNOPSIS ======== use IO; DESCRIPTION =========== IO provides a simple mechanism to load some of the IO modules at one go. Currently this includes: IO::Handle IO::Seekable IO::File IO::Pipe IO::Socket IO::Dir For more information on any of these modules, please see its respective documentation.  File: pm.info, Node: IO/AtomicFile, Next: IO/BLOB/Pg, Prev: IO, Up: Module List write a file which is updated atomically **************************************** NAME ==== IO::AtomicFile - write a file which is updated atomically SYNOPSIS ======== use IO::AtomicFile; # Write a temp file, and have it install itself when closed: my $FH = IO::AtomicFile->open("bar.dat", "w"); print $FH "Hello!\n"; $FH->close || die "couldn't install atomic file: $!"; # Write a temp file, but delete it before it gets installed: my $FH = IO::AtomicFile->open("bar.dat", "w"); print $FH "Hello!\n"; $FH->delete; # Write a temp file, but neither install it nor delete it: my $FH = IO::AtomicFile->open("bar.dat", "w"); print $FH "Hello!\n"; $FH->detach; DESCRIPTION =========== This module is intended for people who need to update files reliably in the face of unexpected program termination. For example, you generally don't want to be halfway in the middle of writing */etc/passwd* and have your program terminate! Even the act of writing a single scalar to a filehandle is not atomic. But this module gives you true atomic updates, via rename(). When you open a file */foo/bar.dat* via this module, you are *actually* opening a temporary file */foo/bar.dat..TMP*, and writing your output there. The act of closing this file (either explicitly via close(), or implicitly via the destruction of the object) will cause rename() to be called... therefore, from the point of view of the outside world, the file's contents are updated in a single time quantum. To ensure that problems do not go undetected, the "close" method done by the destructor will raise a fatal exception if the rename() fails. The explicit close() just returns undef. You can also decide at any point to trash the file you've been building. AUTHOR ====== Eryq (`eryq@zeegee.com'). President, ZeeGee Software Inc (`http://www.zeegee.com'). REVISION ======== $Revision: 1.105 $  File: pm.info, Node: IO/BLOB/Pg, Next: IO/Cat, Prev: IO/AtomicFile, Up: Module List Emulate IO::File interface for PostgreSQL Large Objects ******************************************************* NAME ==== IO::BLOB::Pg - Emulate IO::File interface for PostgreSQL Large Objects SYNOPSIS ======== use IO::BLOB::Pg; use DBI; $dbh = DBI->connect("dbi:Pg:dbname=mah", "", "", {RaiseError=>1, AutoCommit=>0}) # <- Absolutely necessary! $io = IO::BLOB::Pg->new($dbi); # Create a new blob tie *IO, 'IO::BLOB::Pg'; # write data print $io "string\n"; $io->print(@data); syswrite($io, $buf, 100); select $io; printf "Some text %s\n", $str; # seek $pos = $io->getpos; $io->setpos(0); # rewind $io->seek(-30, -1); # read data <$io>; $io->getline; read($io, $buf, 100); # get the blob's oid $oid = $io->oid; # close up $io->close; # open a previously created blob $io = IO::BLOB::Pg->new($dbi, $oid); **** WARNING **** ================= To use this module, you *must* feed your DBI connection `AutoCommit => 0'. See the PostgreSQL documentation for more details. DESCRIPTION =========== The `IO::BLOB::Pg' module provide the IO::File interface for Large Objects (aka BLOBs) in a PostgreSQL database. An `IO::BLOB::Pg' object can be attached to a Large Object ID, and will make it possible to use the normal file operations for reading or writing data, as well as seeking to various locations of the object. This provides a tremendous amount of convenience since you can treat the object just like a regular file and operate on it as you would normally in Perl instead of doing all sorts of funky stuff like: $dbh->func($lobjfd, $buff, $len, "lo_read"); you get: <$lobjfd> I based this code on Gisle Aas' IO::String, so the interface is similar. The `IO::BLOB::Pg' module provides an interface compatible with IO::File as distributed with `IO-1.20', but the following methods are not available; new_from_fd, fdopen, format_write, format_page_number, format_lines_per_page, format_lines_left, format_name, format_top_name. The following methods are specific for the `IO::BLOB::Pg' class: $io = IO::BLOB::Pg->new( $dbh[, $objid] ) The constructor returns a newly created `IO::BLOB::Pg' object. You must supply it with a database handle. It takes an optional argument which is oid of the large objectto read from or write into. If no $objid argument is given, then a new large object is created. The `IO::BLOB::Pg' object returned will be tied to itself. This means that you can use most perl IO builtins on it too; readline, <>, getc, print, printf, syswrite, sysread, close. $io->open( $dbh[, $objid] ) Attach an existing IO::BLOB::Pg object to some other $objid, or create a new large object if no $objid is given. The position is reset back to 0. $io->oid This method will return the oid of the large object. This is useful for when you create a large object and what to put a reference to it in another table. $io->pad( [$char] ) *Currently, extending the Blob via seek() or truncate() is not possible.* The pad() method makes it possible to specify the padding to use if the object is extended by either the seek() or truncate() methods. It is a single character and defaults to "\0". $io->pos( [$newpos] ) Yet another interface for reading and setting the current read/write position within the object (the normal getpos/setpos/tell/seek methods are also available). The pos() method will always return the old position, and if you pass it an argument it will set the new position. $io->length Convenience method that gives you the size of the Blob. One more difference compared to IO::Handle, is that the write() and syswrite() methods allow the length argument to be left out. BUGS ==== The perl TIEHANDLE interface is still not complete. There are quite a few file operations that will not yet invoke any method on the tied object. See *Note Perltie: (perl.info)perltie, for details. SEE ALSO ======== *Note IO/File: IO/File,, *Note IO/String: IO/String, COPYRIGHT ========= Copyright 2000 Mark A. Hershberger, . This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: IO/Cat, Next: IO/Default, Prev: IO/BLOB/Pg, Up: Module List Object-oriented Perl implementation of cat(1) ********************************************* NAME ==== IO::Cat - Object-oriented Perl implementation of cat(1) SYNOPSIS ======== require IO::Cat; my $meow = new IO::Cat '/etc/motd'; $meow->cat( \*STDOUT, \*STDERR ) or die "Can't cat /etc/motd: $!"; DESCRIPTION =========== IO::Cat provides an intuitive, scalable, encapsulated interface to the common task of printing to a filehandle. Use it a few times, and you'll never know how you lived without it! METHODS ======= * new FILENAME This constructor takes the name of a file to be catted and returns a brand spanking new IO::Cat object. If you prefer, you can pass it no args here and use the file() accessor method to set the filename before calling cat(). * file FILENAME An accessor method that lets you set the filename or filehandle which a particular IO::Cat object will cat. Returns the open filehandle which it will cat from. * cat *FILEHANDLE* Copies data from a previously specified file to FILEHANDLE, or returns false if an error occurred. * cattail *FILEHANDLE* Prints data from a previously specified file to FILEHANDLE - backwards, line by line - or returns false if an error occurred. AUTHOR ====== Dennis Taylor, SEE ALSO ======== cat(1) and the File::Cat module.  File: pm.info, Node: IO/Default, Next: IO/Dir, Prev: IO/Cat, Up: Module List replace select() with $DEFOUT, $DEFERR, $DEFIN ********************************************** NAME ==== IO::Default - replace select() with $DEFOUT, $DEFERR, $DEFIN SYNOPSIS ======== use IO::Default; open LOG, ">/var/log/my.log"; $DEFOUT = LOG; # instead of select(LOG); open $DEFERR, ">/var/log/my.err"; warn "Badness!"; # sends to $DEFERR $DEFIN = \*STDIN; # barewords or globs work @data = <>; # reads from $DEFIN now use FileHandle; # provide OO file methods $DEFOUT = \*MYFILE; # need to use globs if want OO $DEFOUT->autoflush(1); # set $| on whatever $DEFOUT is $DEFERR->autoflush(1); # ditto $DEFIN->untaint; # untaint default input stream DESCRIPTION =========== Currently, Perl provides a somewhat clumsy way of manipulating the default filehandle, and no easy way of manipulating default error and input handles. This module serves the dual purpose of providing a means around this, as well as serving as a prototype for a proposed Perl 6 feature. This module replaces the use of select() and the default filehandle with three variables, $DEFOUT, $DEFERR, and $DEFIN, that are the default output, input, and error filehandles. By default, they point to STDOUT, STDERR, and nothing, respectively. The reason $DEFIN doesn't do anything until you assign to it is because assigning to it wipes out @ARGV. See the BUGS below. To change what the default filehandle is for output, simply assign a filehandle or filehandle glob to $DEFOUT: open LOG, ">/var/log/my.log" or die; $DEFOUT = LOG; # bare filehandles ok print "Here's some data"; # goes to LOG The same can be easily done with $DEFERR for default errors: open ERR, ">/var/log/my.err" or die; $DEFERR = \*ERR unless $have_a_tty; # glob refs ok too warn "Danger, Will Robinson!"; # goes to ERR Finally, this module changes the semantics of <> if you assign to $DEFIN. Normally, the <> ARGV filehandle will iterate through command line arguments. This is still the default. However, if you explicitly assign a filehandle to $DEFIN, then this changes the semantics and input is instead read from the handle: open MOTD, "); # just reads /etc/motd Why do this? Well, passing filehandles in and out of functions is a pain in Perl 5, requiring you to use globs. If you simply want to change the default input for a sub function somewhere, have it read from <>: sub get_data { my @data = <>; # do more stuff return @data; } Then from the top level do something like this: # Figure out our input stream $DEFIN = get_handle || \*STDIN; @data = get_data; And now you don't have to pass filehandles in and out of functions anymore just for dealing with default input and output. Note that here <> and <$DEFIN> are synonymous. BUGS ==== This module should NOT be used in production code because it is considered unstable and subject to change. Unfortunately, getting $DEFIN to work in Perl 5 is hairy, since ARGV is so special. As such, assigning to $DEFIN will wipe out whatever you have in @ARGV at the time. It also can't set $ARGV, since the file that was opened is unknown. Luckily, if you never assign or access $DEFIN, then <> retains its magic powers, so if you don't like this simply don't use $DEFIN. This module really just does some trickery to reopen the STD filehandles and point them to different places. As such, mixing print calls to $DEFERR and STDERR will send the output to the same place (contrary to the Perl 6 proposal). REFERENCES ========== For complete details on the Perl 6 proposal, please visit http://dev.perl.org/rfc/129.html. Comments are welcome. AUTHOR ====== Copyright (c) 2000, Nathan Wiger . All Rights Reserved. This module is free software; you may copy this under the terms of the GNU General Public License, or the Artistic License, copies of which should have accompanied your Perl kit.  File: pm.info, Node: IO/Dir, Next: IO/File, Prev: IO/Default, Up: Module List supply object methods for directory handles ******************************************* NAME ==== IO::Dir - supply object methods for directory handles SYNOPSIS ======== use IO::Dir; $d = new IO::Dir "."; if (defined $d) { while (defined($_ = $d->read)) { something($_); } $d->rewind; while (defined($_ = $d->read)) { something_else($_); } undef $d; } tie %dir, IO::Dir, "."; foreach (keys %dir) { print $_, " " , $dir{$_}->size,"\n"; } DESCRIPTION =========== The IO::Dir package provides two interfaces to perl's directory reading routines. The first interface is an object approach. IO::Dir provides an object constructor and methods, which are just wrappers around perl's built in directory reading routines. new ( [ DIRNAME ] ) new is the constuctor for IO::Dir objects. It accepts one optional argument which, if given, new will pass to open The following methods are wrappers for the directory related functions built into perl (the trailing `dir' has been removed from the names). See *Note Perlfunc: (perl.info)perlfunc, for details of these functions. open ( DIRNAME ) read () seek ( POS ) tell () rewind () close () IO::Dir also provides a interface to reading directories via a tied HASH. The tied HASH extends the interface beyond just the directory reading routines by the use of lstat, from the File::stat package, unlink, rmdir and utime. tie %hash, IO::Dir, DIRNAME [, OPTIONS ] The keys of the HASH will be the names of the entries in the directory. Reading a value from the hash will be the result of calling `File::stat::lstat'. Deleting an element from the hash will call unlink providing that DIR_UNLINK is passed in the OPTIONS. Assigning to an entry in the HASH will cause the time stamps of the file to be modified. If the file does not exist then it will be created. Assigning a single integer to a HASH element will cause both the access and modification times to be changed to that value. Alternatively a reference to an array of two values can be passed. The first array element will be used to set the access time and the second element will be used to set the modification time. SEE ALSO ======== *Note File/stat: File/stat, AUTHOR ====== Graham Barr <`gbarr@pobox.com'> COPYRIGHT ========= Copyright (c) 1997-8 Graham Barr . All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: IO/File, Next: IO/File/Multi, Prev: IO/Dir, Up: Module List supply object methods for filehandles ************************************* NAME ==== IO::File - supply object methods for filehandles SYNOPSIS ======== use IO::File; $fh = new IO::File; if ($fh->open("< file")) { print <$fh>; $fh->close; } $fh = new IO::File "> file"; if (defined $fh) { print $fh "bar\n"; $fh->close; } $fh = new IO::File "file", "r"; if (defined $fh) { print <$fh>; undef $fh; # automatically closes the file } $fh = new IO::File "file", O_WRONLY|O_APPEND; if (defined $fh) { print $fh "corge\n"; $pos = $fh->getpos; $fh->setpos($pos); undef $fh; # automatically closes the file } autoflush STDOUT 1; DESCRIPTION =========== IO::File inherits from IO::Handle and IO::Seekable. It extends these classes with methods that are specific to file handles. CONSTRUCTOR =========== new ( FILENAME [,MODE [,PERMS]] ) Creates a IO::File. If it receives any parameters, they are passed to the method open; if the open fails, the object is destroyed. Otherwise, it is returned to the caller. new_tmpfile Creates an IO::File opened for read/write on a newly created temporary file. On systems where this is possible, the temporary file is anonymous (i.e. it is unlinked after creation, but held open). If the temporary file cannot be created or opened, the IO::File object is destroyed. Otherwise, it is returned to the caller. METHODS ======= open( FILENAME [,MODE [,PERMS]] ) open accepts one, two or three parameters. With one parameter, it is just a front end for the built-in open function. With two or three parameters, the first parameter is a filename that may include whitespace or other special characters, and the second parameter is the open mode, optionally followed by a file permission value. If `IO::File::open' receives a Perl mode string (">", "+<", etc.) or a ANSI C fopen() mode string ("w", "r+", etc.), it uses the basic Perl open operator (but protects any special characters). If `IO::File::open' is given a numeric mode, it passes that mode and the optional permissions value to the Perl sysopen operator. The permissions default to 0666. For convenience, IO::File exports the O_XXX constants from the Fcntl module, if this module is available. SEE ALSO ======== *Note Perlfunc: (perl.info)perlfunc,, `"I', *Note Perlop: (perl.info)perlop,, `"I', *Note IO/Handle: IO/Handle, `"I', *Note IO/Seekable: IO/Seekable, HISTORY ======= Derived from FileHandle.pm by Graham Barr <`gbarr@pobox.com'>.  File: pm.info, Node: IO/File/Multi, Next: IO/Handle, Prev: IO/File, Up: Module List Print to multiple filehandles with one output call ************************************************** NAME ==== Multi - Print to multiple filehandles with one output call SYNOPSIS ======== use IO::File::Multi; $mult_obj=new IO::File::Multi; $mult_obj->open('>-'); $mult_obj->open('>file'); $mult_obj->open(">$file"); $mult_obj->open('>>file2'); $mult_obj->print("This will be printed to several filehandles\n"); $mult_obj->printf("This will be printed to %d filehandles\n", scalar @{$mult_obj->{handles}}); $mult_obj->autoflush(); @handle_refs = $mult_obj->members(); $mult_obj->output_field_separator(':'); $mult_obj->output_record_separator('\n'); $mult_obj->format_page_number(2); $mult_obj->format_lines_per_page(66); $mult_obj->format_lines_left(10); $mult_obj->format_name('AN_REPORT'); $mult_obj->format_top_name('AN_REPORT_TOP'); $mult_obj->format_line_break_characters('\n'); $mult_obj->format_formfeed('\l'); $mult_obj->close(); DESCRIPTION =========== This module requires that the user have the IO::File module installed (it comes with the perl distribution). Create objects for each of the output filehandles you'll have - then call the print() and printf() methods to send output to ALL the filehandles associated with an object. EXAMPLES ======== Look at the SYNOPSIS section. Also, here is a simple implementation of the unix tee(1) program (non-append mode): #!/local/bin/perl use IO::File::Multi; $mh=new IO::File::Multi; $mh->open('>-'); for (@ARGV) { $mh->open(">$_"); } while () { $mh->print($_); } BUGS ==== I don't think using my()s the way I am in the open() method is all that good. binmode isn't supported, but I don't see anybody using that anyways. In order to use fcntl(), fileno(), or flock() you'll have to access the filehandles yourself by calling members(). There's no write() yet (but I'm working on it!). Also, any limitations to the IO::File module also apply here. It has been pointed out to me that multiple open() calls on the same file under MacOS will fail. Hopefully, the carp() call will help with catching this. AUTHOR ====== Nem W Schlecht (nem@plains.nodak.edu). Comments, bugs fixes, and suggestions welcome.  File: pm.info, Node: IO/Handle, Next: IO/InnerFile, Prev: IO/File/Multi, Up: Module List supply object methods for I/O handles ************************************* NAME ==== IO::Handle - supply object methods for I/O handles SYNOPSIS ======== use IO::Handle; $io = new IO::Handle; if ($io->fdopen(fileno(STDIN),"r")) { print $io->getline; $io->close; } $io = new IO::Handle; if ($io->fdopen(fileno(STDOUT),"w")) { $io->print("Some text\n"); } use IO::Handle '_IOLBF'; $io->setvbuf($buffer_var, _IOLBF, 1024); undef $io; # automatically closes the file if it's open autoflush STDOUT 1; DESCRIPTION =========== IO::Handle is the base class for all other IO handle classes. It is not intended that objects of IO::Handle would be created directly, but instead IO::Handle is inherited from by several other classes in the IO hierarchy. If you are reading this documentation, looking for a replacement for the FileHandle package, then I suggest you read the documentation for IO::File too. CONSTRUCTOR =========== new () Creates a new IO::Handle object. new_from_fd ( FD, MODE ) Creates a IO::Handle like new does. It requires two parameters, which are passed to the method fdopen; if the fdopen fails, the object is destroyed. Otherwise, it is returned to the caller. METHODS ======= See *Note Perlfunc: (perl.info)perlfunc, for complete descriptions of each of the following supported IO::Handle methods, which are just front ends for the corresponding built-in functions: $io->close $io->eof $io->fileno $io->format_write( [FORMAT_NAME] ) $io->getc $io->read ( BUF, LEN, [OFFSET] ) $io->print ( ARGS ) $io->printf ( FMT, [ARGS] ) $io->stat $io->sysread ( BUF, LEN, [OFFSET] ) $io->syswrite ( BUF, LEN, [OFFSET] ) $io->truncate ( LEN ) See *Note Perlvar: (perl.info)perlvar, for complete descriptions of each of the following supported IO::Handle methods. All of them return the previous value of the attribute and takes an optional single argument that when given will set the value. If no argument is given the previous value is unchanged (except for $io->autoflush will actually turn ON autoflush by default). $io->autoflush ( [BOOL] ) $| $io->format_page_number( [NUM] ) $% $io->format_lines_per_page( [NUM] ) $= $io->format_lines_left( [NUM] ) $- $io->format_name( [STR] ) $~ $io->format_top_name( [STR] ) $^ $io->input_line_number( [NUM]) $. The following methods are not supported on a per-filehandle basis. IO::Handle->format_line_break_characters( [STR] ) $: IO::Handle->format_formfeed( [STR]) $^L IO::Handle->output_field_separator( [STR] ) $, IO::Handle->output_record_separator( [STR] ) $\ IO::Handle->input_record_separator( [STR] ) $/ Furthermore, for doing normal I/O you might need these: $io->fdopen ( FD, MODE ) fdopen is like an ordinary open except that its first parameter is not a filename but rather a file handle name, a IO::Handle object, or a file descriptor number. $io->opened Returns true if the object is currently a valid file descriptor. $io->getline This works like <$io> described in `"I', *Note Perlop: (perl.info)perlop, except that it's more readable and can be safely called in an array context but still returns just one line. $io->getlines This works like <$io> when called in an array context to read all the remaining lines in a file, except that it's more readable. It will also croak() if accidentally called in a scalar context. $io->ungetc ( ORD ) Pushes a character with the given ordinal value back onto the given handle's input stream. Only one character of pushback per handle is guaranteed. $io->write ( BUF, LEN [, OFFSET ] ) This write is like write found in C, that is it is the opposite of read. The wrapper for the perl write function is called format_write. $io->error Returns a true value if the given handle has experienced any errors since it was opened or since the last call to clearerr. $io->clearerr Clear the given handle's error indicator. $io->sync sync synchronizes a file's in-memory state with that on the physical medium. sync does not operate at the perlio api level, but operates on the file descriptor, this means that any data held at the perlio api level will not be synchronized. To synchronize data that is buffered at the perlio api level you must use the flush method. sync is not implemented on all platforms. See `fsync(3c)' in this node. $io->flush flush causes perl to flush any buffered data at the perlio api level. Any unread data in the buffer will be discarded, and any unwritten data will be written to the underlying file descriptor. $io->printflush ( ARGS ) Turns on autoflush, print ARGS and then restores the autoflush status of the IO::Handle object. $io->blocking ( [ BOOL ] ) If called with an argument blocking will turn on non-blocking IO if `BOOL' is false, and turn it off if `BOOL' is true. blocking will return the value of the previous setting, or the current setting if `BOOL' is not given. If an error occurs blocking will return undef and $! will be set. If the C functions setbuf() and/or setvbuf() are available, then `IO::Handle::setbuf' and `IO::Handle::setvbuf' set the buffering policy for an IO::Handle. The calling sequences for the Perl functions are the same as their C counterparts-including the constants `_IOFBF', `_IOLBF', and `_IONBF' for setvbuf()-except that the buffer parameter specifies a scalar variable to use as a buffer. WARNING: A variable used as a buffer by `setbuf' or `setvbuf' must not be modified in any way until the IO::Handle is closed or `setbuf' or `setvbuf' is called again, or memory corruption may result! Note that you need to import the constants `_IOFBF', `_IOLBF', and `_IONBF' explicitly. Lastly, there is a special method for working under -T and setuid/gid scripts: $io->untaint Marks the object as taint-clean, and as such data read from it will also be considered taint-clean. Note that this is a very trusting action to take, and appropriate consideration for the data source and potential vulnerability should be kept in mind. NOTE ==== A IO::Handle object is a reference to a symbol/GLOB reference (see the Symbol package). Some modules that inherit from IO::Handle may want to keep object related variables in the hash table part of the GLOB. In an attempt to prevent modules trampling on each other I propose the that any such module should prefix its variables with its own name separated by _'s. For example the IO::Socket module keeps a timeout variable in 'io_socket_timeout'. SEE ALSO ======== *Note Perlfunc: (perl.info)perlfunc,, `"I', *Note Perlop: (perl.info)perlop,, `"I', *Note IO/File: IO/File, BUGS ==== Due to backwards compatibility, all filehandles resemble objects of class IO::Handle, or actually classes derived from that class. They actually aren't. Which means you can't derive your own class from IO::Handle and inherit those methods. HISTORY ======= Derived from FileHandle.pm by Graham Barr <`gbarr@pobox.com'>  File: pm.info, Node: IO/InnerFile, Next: IO/Interface, Prev: IO/Handle, Up: Module List define a file inside another file ********************************* NAME ==== IO::InnerFile - define a file inside another file SYNOPSIS ======== ### Read a subset of a file: $inner = IO::InnerFile->new($fh, $start, $length); while (<$inner>) { ... } DESCRIPTION =========== If you have a filehandle that can seek() and tell(), then you can open an IO::InnerFile on a range of the underlying file. PUBLIC INTERFACE ================ new FILEHANDLE, [START, [LENGTH]] *Class method, constructor.* Create a new inner-file opened on the given FILEHANDLE, from bytes START to START+LENGTH. Both START and LENGTH default to 0; negative values are silently coerced to zero. Note that FILEHANDLE must be able to seek() and tell(), in addition to whatever other methods you may desire for reading it. set_length LENGTH get_length add_length NBYTES *Instance methods.* Get/set the virtual length of the inner file. set_start START get_start add_start NBYTES *Instance methods.* Get/set the virtual start position of the inner file. binmode close flush getc getline print LIST printf LIST read BUF, NBYTES readline seek OFFFSET, WHENCE tell write ARGS... *Instance methods.* Standard filehandle methods. AUTHOR ====== Original version by Doru Petrescu (pdoru@kappa.ro). Documentation and current maintenance by Eryq (eryq@zeegee.com).  File: pm.info, Node: IO/Interface, Next: IO/Lines, Prev: IO/InnerFile, Up: Module List Perl extension for access to network card configuration information ******************************************************************* NAME ==== IO::Interface - Perl extension for access to network card configuration information SYNOPSIS ======== use IO::Socket; use IO::Interface; my $s = IO::Socket::INET->new(Proto => 'udp'); my @interfaces = $s->if_list; for my $f (@interfaces) { print "interface = $f\n"; my $flags = $s->if_flags($if); print "addr = ",$s->if_addr($if),"\n", "broadcast = ",$s->if_broadcast($if),"\n", "netmask = ",$s->if_netmask($if),"\n", "dstaddr = ",$s->if_dstaddr($if),"\n", "hwaddr = ",$s->if_hwaddr($if),"\n"; print "is running\n" if $flags & IFF_RUNNING; print "is broadcast\n" if $flags & IFF_BROADCAST; print "is p-to-p\n" if $flags & IFF_POINTOPOINT; print "is loopback\n" if $flags & IFF_LOOPBACK; print "is promiscuous\n" if $flags & IFF_PROMISCUOUS; print "is multicast\n" if $flags & IFF_MULTICAST; print "is notrailers\n" if $flags & IFF_NOTRAILERS; print "is noarp\n" if $flags & IFF_NOARP; } $interface = $s->addr_to_interface('127.0.0.1'); DESCRIPTION =========== IO::Interface adds methods to IO::Socket objects that allows them to be used to retrieve and change information about the network interfaces on your system. In addition to the object-oriented access methods, you can use a function-oriented style. Creating a Socket to Access Interface Information ------------------------------------------------- You must create a socket before you can access interface information. The socket does not have to be connected to a remote site, or even used for communication. The simplest procedure is to create a UDP protocol socket: my $s = IO::Socket::INET->new(Proto => 'udp'); The various IO::Interface functions will now be available as methods on this socket. Methods ------- @iflist = $s->if_list The if_list() method will return a list of active interface names, for example "eth0" or "tu0". If no interfaces are configured and running, returns an empty list. $addr = $s->if_addr($ifname [,$newaddr]) if_addr() gets or sets the interface address. Call with the interface name to retrieve the address (in dotted decimal format). Call with a new address to set the interface. In the latter case, the routine will return a true value if the operation was successful. my $oldaddr = $s->if_addr('eth0'); $s->if_addr('eth0','192.168.8.10') || die "couldn't set address: $!"; Special case: the address of the pseudo-device "any" will return the IP address "0.0.0.0", which corresponds to the INADDR_ANY constant. $broadcast = $s->if_broadcast($ifname [,$newbroadcast] Get or set the interface broadcast address. If the interface does not have a broadcast address, returns undef. $mask = $s->if_netmask($ifname [,$newmask]) Get or set the interface netmask. $dstaddr = $s->if_dstaddr($ifname [,$newdest]) Get or set the destination address for point-to-point interfaces. $hwaddr = $s->if_hwaddr($ifname [,$newhwaddr]) Get or set the hardware address for the interface. Currently only ethernet addresses in the form "00:60:2D:2D:51:70" are accepted. $flags = $s->if_flags($ifname [,$newflags]) Get or set the flags for the interface. The flags are a bitmask formed from a series of constants. See `Exportable constants' in this node below. $ifname = $s->addr_to_interface($ifaddr) Given an interface address in dotted form, returns the name of the interface associated with it. Special case: the INADDR_ANY address, 0.0.0.0 will return a pseudo-interface name of "any". EXPORT ------ IO::Interface exports nothing by default. However, you can import the following symbol groups into your namespace: :functions Function-oriented interface (see below) :flags Flag constants (see below) :all All of the above Function-Oriented Interface --------------------------- By importing the ":functions" set, you can access IO::Interface in a function-oriented manner. This imports all the methods described above into your namespace. Example: use IO::Socket; use IO::Interface ':functions'; my $sock = IO::Socket::INET->new(Proto=>'udp'); my @interfaces = if_list($sock); print "address = ",if_addr($sock,$interfaces[0]); Exportable constants -------------------- The ":flags" constant imports the following constants for use with the flags returned by if_flags(): IFF_ALLMULTI IFF_AUTOMEDIA IFF_BROADCAST IFF_DEBUG IFF_LOOPBACK IFF_MASTER IFF_MULTICAST IFF_NOARP IFF_NOTRAILERS IFF_POINTOPOINT IFF_PORTSEL IFF_PROMISC IFF_RUNNING IFF_SLAVE IFF_UP This example determines whether interface 'tu0' supports multicasting: use IO::Socket; use IO::Interface ':flags'; my $sock = IO::Socket::INET->new(Proto=>'udp'); print "can multicast!\n" if $sock->if_flags & IFF_MULTICAST. AUTHOR ====== Lincoln Stein This module is distributed under the same license as Perl itself. SEE ALSO ======== perl(1), IO::Socket(3), IO::Multicast(3)  File: pm.info, Node: IO/Lines, Next: IO/LockedFile, Prev: IO/Interface, Up: Module List IO:: interface for reading/writing an array of lines **************************************************** NAME ==== IO::Lines - IO:: interface for reading/writing an array of lines SYNOPSIS ======== use IO::Lines; # See IO::ScalarArray for details DESCRIPTION =========== This class implements objects which behave just like FileHandle (or IO::Handle) objects, except that you may use them to write to (or read from) an array of lines. They can be tiehandle'd as well. This is a subclass of `IO::ScalarArray|IO::ScalarArray' in this node in which the underlying array has its data stored in a line-oriented-format: that is, every element ends in a `"\n"', with the possible exception of the final element. This makes `getline()' *much* more efficient; if you plan to do line-oriented reading/printing, you want this class. The print() method will enforce this rule, so you can print arbitrary data to the line-array: it will break the data at newlines appropriately. See *Note IO/ScalarArray: IO/ScalarArray, for full usage. VERSION ======= $Id: Lines.pm,v 1.110 2000/08/16 04:59:02 eryq Exp $ AUTHORS ======= Principal author ---------------- Eryq (`eryq@zeegee.com'). President, ZeeGee Software Inc (`http://www.zeegee.com'). Other contributors ------------------ Thanks to the following individuals for their invaluable contributions (if I've forgotten or misspelled your name, please email me!): *Morris M. Siegel,* for his $/ patch and the new `getlines()'.  File: pm.info, Node: IO/LockedFile, Next: IO/Multiplex, Prev: IO/Lines, Up: Module List supply object methods for locking files *************************************** NAME ==== IO::LockedFile Class - supply object methods for locking files SYNOPSIS ======== use IO::LockedFile; # create new locked file object. $file will hold a file handle. # if the file is already locked, the method will not return until the # file is unlocked my $file = new IO::LockedFile(">locked1.txt"); # when we close the file - it become unlocked. $file->close(); # if we delete the object, the file is automatically unlocked and # closed. $file = undef; DESCRIPTION =========== The IO::LockedFile class gives us the same interface of the IO::File class to files with the unique difference that those files are locked using the flock mechanism. If during the running of the process, the process crashed - the file will be automatically unlocked. Actually - if the IO::LockedFile object goes out of scope, the file is automatically closed and unlocked. CONSTRUCTOR =========== new ( FILENAME [,MODE [,PERMS]] ) Creates a `IO::LockedFile'. If it receives any parameters, they are passed to the method open; if the open fails, the object is destroyed. Otherwise, it is returned to the caller. METHODS ======= open( FILENAME [,MODE [,PERMS]] ) The file FILENAME will be opened as a locked file, and the object will be the file handle of that opened file. If the file that is opened is locked the method will not return until the file is unlocked. The parameters that should be provided are the same as the parameters that the method open of IO::File accepts. (like ">file.txt" for example). close() The file will be closed and unlocked. The method does not return anything. is_locked( FILENAME ) Will return true if the file is locked. Will return false otherwise. AUTHOR ====== Rani Pinchuk, rani@cpan.org COPYRIGHT ========= Copyright (c) 2001 EM-TECH (www.em-tech.net) & Rani Pinchuk. All rights reserved. This package is free software; you can redistribute it and/or modify it under the same terms as Perl itself. SEE ALSO ======== `IO::File(3)' in this node