This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: IO/Socket/SSL, Next: IO/Socket/UNIX, Prev: IO/Socket/Multicast, Up: Module List a SSL socket interface class **************************** NAME ==== IO::Socket::SSL - a SSL socket interface class SYNOPSIS ======== use IO::Socket::SSL; DESCRIPTION =========== IO::Socket::SSL is a class implementing an object oriented interface to SSL sockets. The class is a descendent of IO::Socket::INET and provides a subset of the base class's interface methods as well as SSL specific methods. SUPPORTED INTERFACE =================== The following methods from the IO::Socket::INET interface are supported, unimplemented and unsupported respectively: supported methods IO::Socket::INET interface: new, close, fileno, opened, flush, socket, socketpair, bind, listen, peername, sockname, timeout, sockopt, sockdomain, socktype, protocol, sockaddr, sockport, sockhost, peeraddr, peerport, peerhost, sysread, syswrite, read, write, DESTROY, accept, connect, print, printf; others: context_init, get_cipher, get_peer_certificate; unimplemented methods getline, getlines, fdopen, untaint, error, clearerr, send, recv; unsupported methods getc, eof, truncate, stat, ungetc, setbuf, setvbuf, <$fh>. CLASS VARIABLES =============== IO::Socket::SSL::DEBUG METHODS ======= context_init ( [ARGS] ) ----------------------- This class method is used for initializing and setting the global SSL settings. The following following arguments are supported: SSL_server This option must be used when a SSL_Context is explicitly created for server contexts. SSL_use_cert With server sockets a server certificate is always used. For client sockets certificate use is optional. This attribute is set to true if a certificate is to be used. SSL_verify_mode Type of verification process which is to be performed upon a peer certificate. This can be a combination of 0x00 (don't verify), 0x01 (verify peer), 0x02 (fail verification if there's no peer certificate), and 0x04 (verify client once). Default: verify peer. SSL_key_file Filename of the PEM encoded private key file. Default: "certs/server-key.pem" or "certs/client-key.pem". SSL_cert_file Filename of the PEM encoded certificate file. Default: "certs/server-cert.pem" or "certs/client-cert.pem". SSL_ca_path Pathname to the Certicate Authority certificate directory. If server or client certificates are to be verified the trusted CA certificates have to reside in this directory. The CA certificate filename that is used for finding the certificate is a hash value generated from the certificate with a . suffix appended to it. The hash value can be obtained with the command line: ssleay x509 -hash < ca-cert.pem. SSL_ca_file Filename of the CA certificate. new ( [ARGS] ) -------------- See IO::Socket::INET constructor's documentation for details. The following additional per connection SSL options are supported: SSL_verify_mode See above. SSL_cipher_list A list of allowed ciphers. The list is in string form. See http://www.modssl.org/docs/2.3/ssl_reference.html#ToC9. get_cipher ---------- Get a string representation of the used cipher. get_peer_certificate -------------------- Obtain a reference to the X509_Certificate object representing peer's certificate. RELATED CLASSES =============== These are internal classes with which the IO::Socket::SSL API user usually doesn't have to be concerned with. SSL_Context ----------- Encapsulates global SSL options. METHODS ------- new ( [ARGS] ) See context_init arguments. DESTROY SSL_SSL ------- Encapsulates per connection SSL options. METHODS ------- new ( [ARGS] ) DESTROY X509_Certificate ---------------- Encapsulates X509 certificate information. METHODS ------- subject_name Returns a stringified representation of subject's name. issuer_name Returns a stringified representation of issuer's name. EXAMPLES ======== See demo and t directories. RESTRICTIONS ============ Currently, the IO::Socket::INET interface as implemented by this package is not quite complete. There can be only one SSL context at a given time. SEE ALSO ======== IO::Socket::INET. ACKNOWLEDGEMENTS ================ This package has benefited from the work and help of Gisle Aas and Sampo Kellomäki. COPYRIGHT ========= Copyright 1999, Marko Asplund 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/Socket/UNIX, Next: IO/String, Prev: IO/Socket/SSL, Up: Module List Object interface for AF_UNIX domain sockets ******************************************* NAME ==== IO::Socket::UNIX - Object interface for AF_UNIX domain sockets SYNOPSIS ======== use IO::Socket::UNIX; DESCRIPTION =========== IO::Socket::UNIX provides an object interface to creating and using sockets in the AF_UNIX domain. It is built upon the *Note IO/Socket: IO/Socket, interface and inherits all the methods defined by *Note IO/Socket: IO/Socket,. CONSTRUCTOR =========== new ( [ARGS] ) Creates an IO::Socket::UNIX object, which is a reference to a newly created symbol (see the Symbol package). new optionally takes arguments, these arguments are in key-value pairs. In addition to the key-value pairs accepted by *Note IO/Socket: IO/Socket,, IO::Socket::UNIX provides. Type Type of socket (eg SOCK_STREAM or SOCK_DGRAM) Local Path to local fifo Peer Path to peer fifo Listen Create a listen socket If the constructor is only passed a single argument, it is assumed to be a `Peer' specification. NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE As of VERSION 1.18 all IO::Socket objects have autoflush turned on by default. This was not the case with earlier releases. NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE METHODS ======= hostpath() Returns the pathname to the fifo at the local end peerpath() Returns the pathanme to the fifo at the peer end SEE ALSO ======== *Note Socket: Socket,, *Note IO/Socket: IO/Socket, AUTHOR ====== Graham Barr <`gbarr@pobox.com'> COPYRIGHT ========= Copyright (c) 1996-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/String, Next: IO/Stringy, Prev: IO/Socket/UNIX, Up: Module List Emulate IO::File interface for in-core strings ********************************************** NAME ==== IO::String - Emulate IO::File interface for in-core strings SYNOPSIS ======== use IO::String; $io = IO::String->new; $io = IO::String->new($var); tie *IO, 'IO::String'; # read data <$io>; $io->getline; read($io, $buf, 100); # 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); DESCRIPTION =========== The `IO::String' module provide the IO::File interface for in-core strings. An `IO::String' object can be attached to a string, 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 string. The main reason you might want to do this, is if you have some other library module that only provide an interface to file handles, and you want to keep all the stuff in memory. The `IO::String' module provide 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::String' class: $io = IO::String->new( [$string] ) The constructor returns a newly created `IO::String' object. It takes an optional argument which is the string to read from or write into. If no $string argument is given, then an internal buffer (initially empty) is allocated. The `IO::String' 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( [$string] ) Attach an existing IO::String object to some other $string, or allocate a new internal buffer (if no argument is given). The position is reset back to 0. $io->string_ref This method will return a reference to the string that is attached to the `IO::String' object. Most useful when you let the `IO::String' create an internal buffer to write into. $io->pad( [$char] ) The pad() method makes it possible to specify the padding to use if the string 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 string (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. There is (deliberately) a difference between the setpos() and seek() methods in that seek() will extend the string (with the specified padding) if you go to a location past the end, while setpos() will just snap back to the end. If truncate() is used to extend the string, then it works as seek(). 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/Stringy: IO/Stringy, COPYRIGHT ========= Copyright 1998-2000 Gisle Aas. 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/Stringy, Next: IO/Tee, Prev: IO/String, Up: Module List stringy - I/O on in-core objects like strings and arrays ******************************************************** NAME ==== IO-stringy - I/O on in-core objects like strings and arrays SYNOPSIS ======== IO:: ::AtomicFile adpO Write a file which is updated atomically ERYQ ::Lines bdpO I/O handle to read/write to array of lines ERYQ ::Scalar RdpO I/O handle to read/write to a string ERYQ ::ScalarArray RdpO I/O handle to read/write to array of scalars ERYQ ::Wrap RdpO Wrap old-style FHs in standard OO interface ERYQ ::WrapTie adpO Tie your handles & retain full OO interface ERYQ DESCRIPTION =========== This toolkit primarily provides modules for performing both traditional and object-oriented i/o) on things other than normal filehandles; in particular, `IO::Scalar|IO::Scalar' in this node, `IO::ScalarArray|IO::ScalarArray' in this node, and `IO::Lines|IO::Lines' in this node. If you have access to tie(), these classes will make use of the `IO::WrapTie|IO::WrapTie' in this node module to inherit a convenient new_tie() constructor. It also exports a nice wraptie() function. In the more-traditional IO::Handle front, we have `IO::AtomicFile|IO::AtomicFile' in this node which may be used to painlessly create files which are updated atomically. And in the "this-may-prove-useful" corner, we have `IO::Wrap|IO::Wrap' in this node, whose exported wraphandle() function will clothe anything that's not a blessed object in an IO::Handle-like wrapper... so you can just use OO syntax and stop worrying about whether your function's caller handed you a string, a globref, or a FileHandle. INSTALLATION ============ Most of you already know the drill... perl Makefile.PL make test make install For everyone else out there... if you've never installed Perl code before, or you're trying to use this in an environment where your sysadmin or ISP won't let you do interesting things, *relax:* since this module contains no binary extensions, you can cheat. That means copying the directory tree under my "./lib" directory into someplace where your script can "see" it. For example, under Linux: cp -r IO-stringy-1.234/lib/* /path/to/my/perl/ Now, in your Perl code, do this: use lib "/path/to/my/perl"; use IO::Scalar; ### or whatever Ok, now you've been told. At this point, anyone who whines about not being given enough information gets an unflattering haiku written about them in the next change log. I'll do it. Don't think I won't. VERSION ======= $Id: Stringy.pm,v 1.219 2001/02/23 09:46:23 eryq Exp $ TO DO ===== (2000/08/02) Finalize $/ support Graham Barr submitted this patch half a year ago; Like a moron, I lost his message under a ton of others, and only now have the experimental implementation done. Will the sudden sensitivity to $/ hose anyone out there? I'm worried, so you have to enable it explicitly. (2000/09/28) Separate read/write cursors? Binkley sent me a very interesting variant of IO::Scalar which maintains two separate cursors on the data, one for reading and one for writing. Quoth he: Isn't it the case that real operating system file descriptors maintain an independent read and write file position (and seek(2) resets them both)? He also pointed out some issues with his implementation: For example, what does eof or tell return? The read position or the write position? (I assumed read position was more important). Your opinions on this are most welcome. (Me, I'm just squeamish that this will break some code which depends on the existing behavior, and that attempts to maintain backwards-compatibility will slow down the code. But I'll give it a shot.) CHANGE LOG ========== Version 1.219 (2001/02/23) IO::Scalar objects can now be made sensitive to $/ . Pains were taken to keep the fast code fast while adding this feature. *Cheers to Graham Barr for submitting his patch; jeers to me for losing his email for 6 months.* Version 1.218 (2001/02/23) IO::Scalar has a new sysseek() method. *Thanks again to Richard Jones.* New "TO DO" section, because people who submit patches/ideas should at least know that they're in the system... and that I won't lose their stuff. Please read it. New entries in `"AUTHOR"' in this node. Please read those too. Version 1.216 (2000/09/28) *IO::Scalar and IO::ScalarArray now inherit from IO::Handle.* I thought I'd remembered a problem with this ages ago, related to the fact that these IO:: modules don't have "real" filehandles, but the problem apparently isn't surfacing now. If you suddenly encounter Perl warnings during global destruction (especially if you're using tied filehandles), then please let me know! *Thanks to B. K. Oxley (binkley) for this.* *Nasty bug fixed in IO::Scalar::write().* Apparently, the offset and the number-of-bytes arguments were, for all practical purposes, *reversed.* You were okay if you did all your writing with print(), but boy was *this* a stupid bug! *Thanks to Richard Jones for finding this one. For you, Rich, a double-length haiku:* Newspaper headline typeset by dyslexic man loses urgency BABY EATS FISH is simply not equivalent to FISH EATS BABY *New sysread and syswrite methods for IO::Scalar.* *Thanks again to Richard Jones for this.* Version 1.215 (2000/09/05) Added 'bool' overload to '""' overload, so object always evaluates to true. (Whew. Glad I caught this before it went to CPAN.) Version 1.214 (2000/09/03) Evaluating an IO::Scalar in a string context now yields the underlying string. *Thanks to B. K. Oxley (binkley) for this.* Version 1.213 (2000/08/16) Minor documentation fixes. Version 1.212 (2000/06/02) Fixed IO::InnerFile incompatibility with Perl5.004. *Thanks to many folks for reporting this.* Version 1.210 (2000/04/17) Added flush() and other no-op methods. *Thanks to Doru Petrescu for suggesting this.* Version 1.209 (2000/03/17) Small bug fixes. Version 1.208 (2000/03/14) Incorporated a number of contributed patches and extensions, mostly related to speed hacks, support for "offset", and WRITE/CLOSE methods. *Thanks to Richard Jones, Doru Petrescu, and many others.* Version 1.206 (1999/04/18) Added creation of ./testout when Makefile.PL is run. Version 1.205 (1999/01/15) Verified for Perl5.005. Version 1.202 (1998/04/18) New IO::WrapTie and IO::AtomicFile added. Version 1.110 Added IO::WrapTie. Version 1.107 Added IO::Lines, and made some bug fixes to IO::ScalarArray. Also, added getc(). Version 1.105 No real changes; just upgraded IO::Wrap to have a $VERSION string. AUTHOR ====== Primary Maintainer Eryq (`eryq@zeegee.com'). President, ZeeGee Software Inc (`http://www.zeegee.com'). Unofficial Co-Authors For all their bug reports and patch submissions, the following are officially recognized: Richard Jones B. K. Oxley (binkley) Doru Petrescu Enjoy. Yell if it breaks.  File: pm.info, Node: IO/Tee, Next: IO/Wrap, Prev: IO/Stringy, Up: Module List Multiplex output to multiple output handles ******************************************* NAME ==== IO::Tee - Multiplex output to multiple output handles SYNOPSIS ======== use IO::Tee; $tee = IO::Tee->new($handle1, $handle2); print $tee "foo", "bar"; my $input = <$tee>; DESCRIPTION =========== `IO::Tee' objects can be used to multiplex input and output in two different ways. The first way is to multiplex output to zero or more output handles. The `IO::Tee' constructor, given a list of output handles, returns a tied handle that can be written to. When written to (using print or printf), the `IO::Tee' object multiplexes the output to the list of handles originally passed to the constructor. As a shortcut, you can also directly pass a string or an array reference to the constructor, in which case `IO::File::new' is called for you with the specified argument or arguments. The second way is to multiplex input from one input handle to zero or more output handles as it is being read. The `IO::Tee' constructor, given an input handle followed by a list of output handles, returns a tied handle that can be read from as well as written to. When written to, the `IO::Tee' object multiplexes the output to all handles passed to the constructor, as described in the previous paragraph. When read from, the `IO::Tee' object reads from the input handle given as the first argument to the `IO::Tee' constructor, then writes any data read to the output handles given as the remaining arguments to the constructor. The `IO::Tee' class supports certain IO::Handle and IO::File methods related to input and output. In particular, the following methods will iterate themselves over all handles associated with the `IO::Tee' object, and return TRUE indicating success if and only if all associated handles returned TRUE indicating success: close truncate write syswrite format_write formline fcntl ioctl flush clearerr seek The following methods perform input multiplexing as described above: read sysread readline getc gets eof getline getlines The following methods can be used to set (but not retrieve) the current values of output-related state variables on all associated handles: autoflush output_field_separator output_record_separator format_page_number format_lines_per_page format_lines_left format_name format_top_name format_line_break_characters format_formfeed The following methods are directly passed on to the input handle given as the first argument to the `IO::Tee' constructor: input_record_separator input_line_number Note that the return value of input multiplexing methods (such as print) is always the return value of the input action, not the return value of subsequent output actions. In particular, no error is indicated by the return value if the input action itself succeeds but subsequent output multiplexing fails. EXAMPLE ======= use IO::Tee; use IO::File; my $tee = new IO::Tee(\*STDOUT, new IO::File(">tt1.out"), ">tt2.out"); print join(' ', $tee->handles), "\n"; $tee->output_field_separator("//"); for (1..10) { print $tee $_, "\n" } for (1..10) { $tee->print($_, "\n") } $tee->flush; $tee = new IO::Tee('; print scalar(@lines); AUTHOR ====== Chung-chieh Shan, ken@digitas.harvard.edu COPYRIGHT ========= Copyright (c) 1998 Chung-chieh Shan. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. SEE ALSO ======== *Note Perlfunc: (perl.info)perlfunc,, *Note IO/Handle: IO/Handle,, *Note IO/File: IO/File,.  File: pm.info, Node: IO/Wrap, Next: IO/WrapTie, Prev: IO/Tee, Up: Module List wrap raw filehandles in IO::Handle interface ******************************************** NAME ==== IO::Wrap - wrap raw filehandles in IO::Handle interface SYNOPSIS ======== use IO::Wrap; # Do stuff with any kind of filehandle (including a bare globref), or # any kind of blessed object that responds to a print() message. # sub do_stuff { my $fh = shift; ### At this point, we have no idea what the user gave us... ### a globref? a FileHandle? a scalar filehandle name? $fh = wraphandle($fh); ### At this point, we know we have an IO::Handle-like object! $fh->print("Hey there!"); ... } DESCRIPTION =========== Let's say you want to write some code which does I/O, but you don't want to force the caller to provide you with a FileHandle or IO::Handle object. You want them to be able to say: do_stuff(\*STDOUT); do_stuff('STDERR'); do_stuff($some_FileHandle_object); do_stuff($some_IO_Handle_object); And even: do_stuff($any_object_with_a_print_method); Sure, one way to do it is to force the caller to use tiehandle(). But that puts the burden on them. Another way to do it is to use *IO::Wrap*, which provides you with the following functions: wraphandle SCALAR This function will take a single argument, and "wrap" it based on what it seems to be... * *A raw scalar filehandle name,* like `"STDOUT"' or `"Class::HANDLE"'. In this case, the filehandle name is wrapped in an IO::Wrap object, which is returned. * *A raw filehandle glob,* like `\*STDOUT'. In this case, the filehandle glob is wrapped in an IO::Wrap object, which is returned. * *A blessed FileHandle object.* In this case, the FileHandle is wrapped in an IO::Wrap object if and only if your FileHandle class does not support the read() method. * *Any other kind of blessed object,* which is assumed to be already conformant to the IO::Handle interface. In this case, you just get back that object. If you get back an IO::Wrap object, it will obey a basic subset of the IO:: interface. That is, the following methods (note: I said methods, not named operators) should work on the thing you get back: close getline getlines print ARGS... read BUFFER,NBYTES seek POS,WHENCE tell NOTES ===== Clearly, when wrapping a raw external filehandle (like \*STDOUT), I didn't want to close the file descriptor when the "wrapper" object is destroyed... since the user might not appreciate that! Hence, there's no DESTROY method in this class. When wrapping a FileHandle object, however, I believe that Perl will invoke the FileHandle::DESTROY when the last reference goes away, so in that case, the filehandle is closed if the wrapped FileHandle really was the last reference to it. WARNINGS ======== This module does not allow you to wrap filehandle names which are given as strings that lack the package they were opened in. That is, if a user opens FOO in package Foo, they must pass it to you either as `\*FOO' or as `"Foo::FOO"'. However, `"STDIN"' and friends will work just fine. AUTHOR ====== Eryq (`eryq@zeegee.com'). President, ZeeGee Software Inc (`http://www.zeegee.com').  File: pm.info, Node: IO/WrapTie, Next: IO/Zlib, Prev: IO/Wrap, Up: Module List wrap tieable objects in IO::Handle interface ******************************************** NAME ==== IO::WrapTie - wrap tieable objects in IO::Handle interface *This is currently Alpha code, released for comments. Please give me your feedback!* SYNOPSIS ======== First of all, you'll need tie(), so: require 5.004; *Function interface (experimental).* Use this with any existing class... use IO::WrapTie; use FooHandle; # implements TIEHANDLE interface # Suppose we want a "FooHandle->new(&FOO_RDWR, 2)". # We can instead say... $FH = wraptie('FooHandle', &FOO_RDWR, 2); # Now we can use... print $FH "Hello, "; # traditional operator syntax... $FH->print("world!\n"); # ...and OO syntax as well! *OO interface (preferred).* You can inherit from the IO::WrapTie::Slave mixin to get a nifty `new_tie()' constructor... #------------------------------ package FooHandle; # a class which can TIEHANDLE use IO::WrapTie; @ISA = qw(IO::WrapTie::Slave); # inherit new_tie() ... #------------------------------ package main; $FH = FooHandle->new_tie(&FOO_RDWR, 2); # $FH is an IO::WrapTie::Master print $FH "Hello, "; # traditional operator syntax $FH->print("world!\n"); # OO syntax See IO::Scalar as an example. It also shows you how to create classes which work both with and without 5.004. DESCRIPTION =========== Suppose you have a class `FooHandle', where... * *FooHandle does not inherit from IO::Handle;* that is, it performs filehandle-like I/O, but to something other than an underlying file descriptor. Good examples are IO::Scalar (for printing to a string) and IO::Lines (for printing to an array of lines). * *FooHandle implements the TIEHANDLE interface* (see *Note Perltie: (perl.info)perltie,); that is, it provides methods TIEHANDLE, GETC, PRINT, PRINTF, READ, and READLINE. * *FooHandle implements the traditional OO interface* of FileHandle and IO::Handle; i.e., it contains methods like getline(), read(), print(), seek(), tell(), eof(), etc. Normally, users of your class would have two options: * *Use only OO syntax,* and forsake named I/O operators like 'print'. * *Use with tie,* and forsake treating it as a first-class object (i.e., class-specific methods can only be invoked through the underlying object via tied()... giving the object a "split personality"). But now with IO::WrapTie, you can say: $WT = wraptie('FooHandle', &FOO_RDWR, 2); $WT->print("Hello, world\n"); # OO syntax print $WT "Yes!\n"; # Named operator syntax too! $WT->weird_stuff; # Other methods! And if you're authoring a class like FooHandle, just have it inherit from `IO::WrapTie::Slave' and that first line becomes even prettier: $WT = FooHandle->new_tie(&FOO_RDWR, 2); *The bottom line:* now, almost any class can look and work exactly like an IO::Handle... and be used both with OO and non-OO filehandle syntax. HOW IT ALL WORKS ================ The data structures ------------------- Consider this example code, using classes in this distribution: use IO::Scalar; use IO::WrapTie; $WT = wraptie('IO::Scalar',\$s); print $WT "Hello, "; $WT->print("world!\n"); In it, the wraptie() function creates a data structure as follows: * $WT is a blessed reference to a tied filehandle $WT glob; that glob is tied to the "Slave" object. | * You would do all your i/o with $WT directly. | | | ,---isa--> IO::WrapTie::Master >--isa--> IO::Handle V / .-------------. | | | | * Perl i/o operators work on the tied object, | "Master" | invoking the TIEHANDLE methods. | | * Method invocations are delegated to the tied | | slave. `-------------' | tied(*$WT) | .---isa--> IO::WrapTie::Slave V / .-------------. | | | "Slave" | * Instance of FileHandle-like class which doesn't | | actually use file descriptors, like IO::Scalar. | IO::Scalar | * The slave can be any kind of object. | | * Must implement the TIEHANDLE interface. `-------------' NOTE: just as an IO::Handle is really just a blessed reference to a *traditional* filehandle glob... so also, an IO::WrapTie::Master is really just a blessed reference to a filehandle glob *which has been tied to some "slave" class.* How wraptie() works ------------------- 1. The call to function `wraptie(SLAVECLASS, TIEARGS...)' is passed onto `IO::WrapTie::Master::new()'. Note that class IO::WrapTie::Master is a subclass of IO::Handle. 2. The `IO::WrapTie::Master::new' method creates a new IO::Handle object, reblessed into class IO::WrapTie::Master. This object is the master, which will be returned from the constructor. At the same time... 3. The new method also creates the slave: this is an instance of SLAVECLASS which is created by tying the master's IO::Handle to SLAVECLASS via `tie(HANDLE, SLAVECLASS, TIEARGS...)'. This call to tie() creates the slave in the following manner: 4. Class SLAVECLASS is sent the message `TIEHANDLE(TIEARGS...)'; it will usually delegate this to `SLAVECLASS::new(TIEARGS...)', resulting in a new instance of SLAVECLASS being created and returned. 5. Once both master and slave have been created, the master is returned to the caller. How I/O operators work (on the master) -------------------------------------- Consider using an i/o operator on the master: print $WT "Hello, world!\n"; Since the master ($WT) is really a [blessed] reference to a glob, the normal Perl i/o operators like print may be used on it. They will just operate on the symbol part of the glob. Since the glob is tied to the slave, the slave's PRINT method (part of the TIEHANDLE interface) will be automatically invoked. If the slave is an IO::Scalar, that means IO::Scalar::PRINT will be invoked, and that method happens to delegate to the print() method of the same class. So the real work is ultimately done by IO::Scalar::print(). How methods work (on the master) -------------------------------- Consider using a method on the master: $WT->print("Hello, world!\n"); Since the master ($WT) is blessed into the class IO::WrapTie::Master, Perl first attempts to find a print() method there. Failing that, Perl next attempts to find a print() method in the superclass, IO::Handle. It just so happens that there *is* such a method; that method merely invokes the print i/o operator on the self object... and for that, see above! But let's suppose we're dealing with a method which *isn't* part of IO::Handle... for example: my $sref = $WT->sref; In this case, the intuitive behavior is to have the master delegate the method invocation to the slave (now do you see where the designations come from?). This is indeed what happens: IO::WrapTie::Master contains an AUTOLOAD method which performs the delegation. So: when `sref()' can't be found in IO::Handle, the AUTOLOAD method of IO::WrapTie::Master is invoked, and the standard behavior of delegating the method to the underlying slave (here, an IO::Scalar) is done. Sometimes, to get this to work properly, you may need to create a subclass of IO::WrapTie::Master which is an effective master for *your* class, and do the delegation there. NOTES ===== *Why not simply use the object's OO interface?* Because that means forsaking the use of named operators like print(), and you may need to pass the object to a subroutine which will attempt to use those operators: $O = FooHandle->new(&FOO_RDWR, 2); $O->print("Hello, world\n"); # OO syntax is okay, BUT.... sub nope { print $_[0] "Nope!\n" } X nope($O); # ERROR!!! (not a glob ref) *Why not simply use tie()?* Because (1) you have to use tied() to invoke methods in the object's public interface (yuck), and (2) you may need to pass the tied symbol to another subroutine which will attempt to treat it in an OO-way... and that will break it: tie *T, 'FooHandle', &FOO_RDWR, 2; print T "Hello, world\n"; # Operator is okay, BUT... tied(*T)->other_stuff; # yuck! AND... sub nope { shift->print("Nope!\n") } X nope(\*T); # ERROR!!! (method "print" on unblessed ref) *Why a master and slave? Why not simply write FooHandle to inherit from IO::Handle?* I tried this, with an implementation similar to that of IO::Socket. The problem is that *the whole point is to use this with objects that don't have an underlying file/socket descriptor.*. Subclassing IO::Handle will work fine for the OO stuff, and fine with named operators if you tie()... but if you just attempt to say: $IO = FooHandle->new(&FOO_RDWR, 2); print $IO "Hello!\n"; you get a warning from Perl like: Filehandle GEN001 never opened because it's trying to do system-level i/o on an (unopened) file descriptor. To avoid this, you apparently have to tie() the handle... which brings us right back to where we started! At least the IO::WrapTie mixin lets us say: $IO = FooHandle->new_tie(&FOO_RDWR, 2); print $IO "Hello!\n"; and so is not *too* bad. `:-)' WARNINGS ======== Remember: this stuff is for doing FileHandle-like i/o on things *without underlying file descriptors*. If you have an underlying file descriptor, you're better off just inheriting from IO::Handle. *Be aware that new_tie() always returns an instance of a kind of IO::WrapTie::Master...* it does not return an instance of the i/o class you're tying to! Invoking some methods on the master object causes AUTOLOAD to delegate them to the slave object... so it *looks* like you're manipulating a "FooHandle" object directly, but you're not. I have not explored all the ramifications of this use of tie(). *Here there be dragons*. AUTHOR ====== Eryq (`eryq@zeegee.com'). President, ZeeGee Software Inc (`http://www.zeegee.com').  File: pm.info, Node: IO/Zlib, Next: IPC/Cache, Prev: IO/WrapTie, Up: Module List IO:: style interface to *Note Compress/Zlib: Compress/Zlib, *********************************************************** NAME ==== IO::Zlib - IO:: style interface to *Note Compress/Zlib: Compress/Zlib, SYNOPSIS ======== With any version of Perl 5 you can use the basic OO interface: use IO::Zlib; $fh = new IO::Zlib; if ($fh->open("file.gz", "rb")) { print <$fh>; $fh->close; } $fh = IO::Zlib->new("file.gz", "wb9"); if (defined $fh) { print $fh "bar\n"; $fh->close; } $fh = IO::Zlib->new("file.gz", "rb"); if (defined $fh) { print <$fh>; undef $fh; # automatically closes the file } With Perl 5.004 you can also use the TIEHANDLE interface to access compressed files just like ordinary files: use IO::Zlib; tie *FILE, 'IO::Zlib', "file.gz", "wb"; print FILE "line 1\nline2\n"; tie *FILE, 'IO::Zlib', "file.gz", "rb"; while () { print "LINE: ", $_ }; DESCRIPTION =========== `IO::Zlib' provides an IO:: style interface to *Note Compress/Zlib: Compress/Zlib, and hence to gzip/zlib compressed files. It provides many of the same methods as the *Note IO/Handle: IO/Handle, interface. CONSTRUCTOR =========== new ( [ARGS] ) Creates an `IO::Zlib' object. 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 ) open takes two arguments. The first is the name of the file to open and the second is the open mode. The mode can be anything acceptable to *Note Compress/Zlib: Compress/Zlib, and by extension anything acceptable to *zlib* (that basically means POSIX fopen() style mode strings plus an optional number to indicate the compression level). opened Returns true if the object currently refers to a opened file. close Close the file associated with the object and disassociate the file from the handle. Done automatically on destroy. getc Return the next character from the file, or undef if none remain. getline Return the next line from the file, or undef on end of string. Can safely be called in an array context. Currently ignores $/ ($INPUT_RECORD_SEPARATOR or $RS when *Note English: English, is in use) and treats lines as delimited by "\n". getlines Get all remaining lines from the file. It will croak() if accidentally called in a scalar context. print ( ARGS... ) Print ARGS to the file. read ( BUF, NBYTES, [OFFSET] ) Read some bytes from the file. Returns the number of bytes actually read, 0 on end-of-file, undef on error. eof Returns true if the handle is currently positioned at end of file? seek ( OFFSET, WHENCE ) Seek to a given position in the stream. Not yet supported. tell Return the current position in the stream, as a numeric offset. Not yet supported. setpos ( POS ) Set the current position, using the opaque value returned by `getpos()'. Not yet supported. getpos ( POS ) Return the current position in the string, as an opaque object. Not yet supported. SEE ALSO ======== *Note Perlfunc: (perl.info)perlfunc,, `"I', *Note Perlop: (perl.info)perlop,, `"I', *Note IO/Handle: IO/Handle,, `"I', *Note Compress/Zlib: Compress/Zlib, HISTORY ======= Created by Tom Hughes <`tom@compton.nu'>. COPYRIGHT ========= Copyright (c) 1998-2001 Tom Hughes <`tom@compton.nu'>. 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: IPC/Cache, Next: IPC/ChildSafe, Prev: IO/Zlib, Up: Module List a perl module that implements an object storage space where data is persisted across process boundaries ******************************************************************************************************* NAME ==== *IPC::Cache* - a perl module that implements an object storage space where data is persisted across process boundaries SYNOPSIS ======== use IPC::Cache; # create a cache in the specified namespace, where objects # will expire in one day my $cache = new Cache( { namespace => 'MyCache', expires_in => 86400 } ); # store a value in the cache (will expire in one day) $cache->set("key1", "value1"); # retrieve a value from the cache $cache->get("key1"); # store a value that expires in one hour $cache->set("key2", "value2", 3600); # clear this cache's contents $cache->clear(); # delete all namespaces from shared memory IPC::Cache::CLEAR(); DESCRIPTION =========== IPC::Cache is used to persist data across processes via shared memory. TYPICAL USAGE ------------- A typical scenario for this would be a mod_perl or perl CGI application. In a multi-tier architecture, it is likely that a trip from the front-end to the database is the most expensive operation, and that data may not change frequently. Using this module will help keep that data on the front-end. Consider the following usage in a mod_perl application, where a mod_perl application serves out images that are retrieved from a database. Those images change infrequently, but we want to check them once an hour, just in case. my $cache = new Cache( { namespace => 'Images', expires_in => 3600 } ); my $image = $imageCache->get("the_requested_image"); if (!$image) { # $image = [expensive database call to get the image] $cache->set("the_requested_image", $image); } That bit of code, executed in any instance of the mod_perl/httpd process will first try the shared memory cache, and only perform the expensive database call if the image has not been fetched before, has timed out, or the cache has been cleared. METHODS ------- new(\%options) Creates a new instance of the cache object. The constructor takes a reference to an options hash which can contain any or all of the following: $options{namespace} Namespaces provide isolation between objects. Each cache refers to one and only one namespace. Multiple caches can refer to the same namespace, however. While specifying a namespace is not required, it is recommended so as not to have data collide. $options{expires_in} If the "expires_in" option is set, all objects in this cache will be cleared in that number of seconds. It can be overridden on a per-object basis. If expires_in is not set, the objects will never expire unless explicitly set. $options{cache_key} The "cache_key" is used to determine the underlying shared memory segment to use. In typical usage, leaving this unset and relying on namespaces alone will be more than adequate. *set($identifier, $object, $expires_in)* Adds an object to the cache. set takes the following parameters: $identifier The key the refers to this object. $object The object to be stored. $expires_in *(optional)* The object will be cleared from the cache in this number of seconds. Overrides the default expire_in for the cache. get($identifier) Retrieves an object from the cache. get takes the following parameter: $identifier The key referring to the object to be retrieved. clear() Removes all objects from this cache. purge() Removes all objects that have expired IPC::Cache::CLEAR($cache_key) Removes this cache and all the associated namespaces from shared memory. CLEAR takes the following parameter: $cache_key *(optional)* Specifies the shared memory segment to be cleared. Needed only if a cache was created in a non-standard shared memory segment. IPC::Cache::PURGE($cache_key) Removes all objects in all namespaces that have expired. PURGE takes the following parameter: $cache_key *(optional)* Specifies the shared memory segment to be purged. Needed only if a cache was created in a non-standard shared memory segment. IPC::Cache::SIZE($cache_key) Roughly estimates the amount of memory in use. SIZE takes the following parameter: $cache_key *(optional)* Specifies the shared memory segment to be examined. Needed only if a cache was created in a non-standard shared memory segment. BUGS ==== * The SIZE method estimates only the size of the frozen data, not the actual shared memory usage * There is no mechanism for limiting the amount of memory in use AUTHOR ====== DeWitt Clinton  File: pm.info, Node: IPC/ChildSafe, Next: IPC/ClearTool, Prev: IPC/Cache, Up: Module List control a child process without blocking **************************************** NAME ==== IPC::ChildSafe, ChildSafe - control a child process without blocking SYNOPSIS ======== use IPC::ChildSafe; # Start a shell process (create a new shell object). $SH = IPC::ChildSafe->new('sh', 'echo ++EOT++', '++EOT++'); # If the ls command succeeds, read lines from its stdout one at a time. if ($SH->cmd('ls') == 0) { print "Found ", scalar($SH->stdout), " files in current dir ...\n"; # Another ls cmd - results added to the object's internal stack $SH->cmd('ls /tmp'); # Since we're stuck in this dumb example, let's get the date too. $SH->cmd('date'); # Now dump results to stdout - show how to get 1 line at a time for my $line ($SH->stdout) { print $line; } # You could also print the output this way: # print $SH->stdout; # Or even just: # $SH->stdout; } # Send it a command, read back the stdout/stderr/return code # into a hash array. my(%results) = $SH->cmd('id'); # Send an 'id' cmd die if $results{status}; # Expect no errors die if @{$results{stdout}} != 1; # Should be just 1 line die if $results{stdout}[0] !~ /^uid=/; # Check output line # (lather, rinse, repeat) # Finishing up. die if $SH->finish; # Returns final status DESCRIPTION =========== This was written to address the "blocking problem" inherent in most coprocessing designs such as IPC::Open3.pm, which has warnings such as this in its documentation: ... additionally, this is very dangerous as you may block forever. It assumes it's going to talk to something like bc, both writing to it and reading from it. This is presumably safe because you "know" that commands like bc will read a line at a time and output a line at a time ... or IPC::Open2 which has this warning from its author (Tom Christansen): ... I strongly advise against using open2 for almost anything, even though I'm its author. UNIX buffering will just drive you up the wall. You'll end up quite disappointed ... The blocking problem is: once you've sent a command to your coprocess, how do you know when the output resulting from this command has finished? If you guess wrong and issue one read too many you can deadlock forever. This implementation solves the problem, at least for a subset of possible child programs, by using a little trick: it sends a 2nd (trivial) command down the pipe right in back of every real command. When we see the the output of this special command in the return pipe, we know the real command is done. This module also returns an "exit status" for each command, which is really a count of the error messages produced by it. The programmer can optionally register his/her own discriminator function for determining which output to stderr constitutes an error message. CONSTRUCTOR =========== The constructor takes 3 arguments plus an optional 4th and 5th: the 1st is the program to run, the 2nd is a command to that program which produces a unique one-line output, and the 3rd is that unique output. If a 4th arg is supplied it becomes the mode in which this object will run (default: NOTIFY, see below), and if a 5th is given it must be a code ref, which will be registered as the error discriminator. If no discriminator is supplied then a standard internal one is used. The 2nd arg is called the "tag command". Preferably this would be something lightweight, e.g. a shell builtin. Unfortunately the current version has no support for a multi-line return value since it would require some fairly complex buffering. DISCRIMINATOR ============= The discriminator function is invoked after each command completes, and is passed a reference to an array containing the stderr generated by that command in its first parameter. A pointer to the stdout is similarly supplied in the second param. Normally this function would just apply a regular expression to one or both of these and indicate by its return status whether it considers this to constitute an error condition. E.g. the version provided internally is: sub errors { my($r_stderr, $r_stdout) = @_; grep(!/^\+\s|warning:/i, @$r_stderr); } my $sh = IPC::ChildSafe->new('sh', 'echo ++EOT++', '++EOT++', \&errors); which treats ANY output to stderr as indicative of an error, with the exception of lines beginning with "+ " (shell verbosity) or containing the string "warning:". METHODS ======= * *notify/store/print/ignore* Sets the output-handling mode. The meanings of these are described below. * cmd Send specified command to child process. Return behavior varies with context: array context returns a hash containing an array of stdout results (key: 'stdout'), an array of stderr messages ('stderr), and the "return code" of the command ('status'). scalar context returns command's "return code". In the default mode (NOTIFY), sends stderr results directly to parent's stderr while storing stdout in the object for later retrieval via stdout method. In PRINT mode both stdout and stderr are sent directly to the "real" (parent's) stdout/stderr. STORE mode causes both stdout and stderr to be stored for later use, while IGNORE mode throws away both. void context similar to scalar mode but exits on nonzero return code unless in IGNORE mode. void context and no args clears the stdout and stderr buffers * stdout Return stored output from previous command(s). Behavior varies with context: array context shifts all stored lines off the stdout stack and returns them in a list. scalar context returns the number of lines currently stored in the stdout stack. void context prints the current stdout stack to actual stdout. * stderr Similar to stdout method above. Note that by default stderr does not go to the accumulator, but rather to the parent's stderr. Set the STORE attribute to leave stderr in the accumulator instead where this method can operate on it. * status Pass the current stdout and stderr buffers to the currently-registered error discriminator and return its results (aka the error count). * finish Ends the child process and returns its final exit status. * *dbglevel* Sets a debugging (verbosity) level. Current defined levels are 1-4. Verbosity lines are printed with a leading '+'. * *noexec* Sets the 'noexec' attribute, which causes commands to not be run but to be printed with a leading '-'. AUTHOR ====== David Boyce dsb@world.std.com Copyright (c) 1997-1999 David Boyce. All rights reserved. This perl program is free software; you may redistribute it and/or modify it under the same terms as Perl itself. SEE ALSO ======== perl(1), "perldoc IPC::Open3", _Advanced Programming in the Unix Environment_ by W. R. Stevens