This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: Net/FTPServer/DBeg1/DirHandle, Next: Net/FTPServer/DBeg1/FileHandle, Prev: Net/FTPServer, Up: Module List The example DB FTP server personality ************************************* NAME ==== Net::FTPServer::DBeg1::DirHandle - The example DB FTP server personality SYNOPSIS ======== use Net::FTPServer::DBeg1::DirHandle; DESCRIPTION =========== METHODS ======= AUTHORS ======= Richard Jones (rich@annexia.org). COPYRIGHT ========= Copyright (C) 2000 Biblio@Tech Ltd., Unit 2-3, 50 Carnwath Road, London, SW6 3EG, UK SEE ALSO ======== `Net::FTPServer(3)' in this node, `perl(1)' in this node  File: pm.info, Node: Net/FTPServer/DBeg1/FileHandle, Next: Net/FTPServer/DBeg1/IOBlob, Prev: Net/FTPServer/DBeg1/DirHandle, Up: Module List The full FTP server personality ******************************* NAME ==== Net::FTPServer::DBeg1::FileHandle - The full FTP server personality SYNOPSIS ======== use Net::FTPServer::DBeg1::FileHandle; DESCRIPTION =========== METHODS ======= AUTHORS ======= Richard Jones (rich@annexia.org). COPYRIGHT ========= Copyright (C) 2000 Biblio@Tech Ltd., Unit 2-3, 50 Carnwath Road, London, SW6 3EG, UK SEE ALSO ======== `Net::FTPServer(3)' in this node, `perl(1)' in this node  File: pm.info, Node: Net/FTPServer/DBeg1/IOBlob, Next: Net/FTPServer/DBeg1/Server, Prev: Net/FTPServer/DBeg1/FileHandle, Up: Module List The example DB FTP server personality ************************************* NAME ==== Net::FTPServer::DBeg1::IOBlob - The example DB FTP server personality SYNOPSIS ======== use Net::FTPServer::DBeg1::IOBlob; DESCRIPTION =========== METHODS ======= $io = Net::FTPServer::DBeg1::IOBlob ('r', $dbh, $blob_id); $io = Net::FTPServer::DBeg1::IOBlob ('w', $dbh, $blob_id); Create an IO handle for reading or writing a PostgreSQL blob. $io->getc (); Read 1 byte from the buffer and return it $io->read ($buffer, $nbytes, [$offset]); $io->sysread ($buffer, $nbytes, [$offset]); Read `$nbytes' from the handle and place them in `$buffer' at offset $offset. $io->write ($buffer, $nbytes, [$offset]); $io->syswrite ($buffer, $nbytes, [$offset]); Write `$nbytes' to the handle from `$buffer' offset $offset. $io->print ($buffer); $io->close; Close the IO handle. AUTHORS ======= Richard Jones (rich@annexia.org). COPYRIGHT ========= Copyright (C) 2000 Biblio@Tech Ltd., Unit 2-3, 50 Carnwath Road, London, SW6 3EG, UK SEE ALSO ======== `Net::FTPServer(3)' in this node, `perl(1)' in this node  File: pm.info, Node: Net/FTPServer/DBeg1/Server, Next: Net/FTPServer/DirHandle, Prev: Net/FTPServer/DBeg1/IOBlob, Up: Module List The DB example FTP server personality ************************************* NAME ==== Net::FTPServer::DBeg1::Server - The DB example FTP server personality SYNOPSIS ======== dbeg1-ftpd [-d] [-v] [-p port] [-s] [-S] [-V] [-C conf_file] DESCRIPTION =========== `Net::FTPServer::DBeg1::Server' is the example DB-based FTP server personality. This personality implements a simple FTP server with a PostgreSQL database back-end. METHODS ======= FILES ===== /etc/ftpd.conf /usr/lib/perl5/site_perl/5.005/Net/FTPServer.pm /usr/lib/perl5/site_perl/5.005/Net/FTPServer/DirHandle.pm /usr/lib/perl5/site_perl/5.005/Net/FTPServer/FileHandle.pm /usr/lib/perl5/site_perl/5.005/Net/FTPServer/Handle.pm /usr/lib/perl5/site_perl/5.005/Net/FTPServer/DBeg1/Server.pm /usr/lib/perl5/site_perl/5.005/Net/FTPServer/DBeg1/DirHandle.pm /usr/lib/perl5/site_perl/5.005/Net/FTPServer/DBeg1/FileHandle.pm AUTHORS ======= Richard Jones (rich@annexia.org). COPYRIGHT ========= Copyright (C) 2000 Biblio@Tech Ltd., Unit 2-3, 50 Carnwath Road, London, SW6 3EG, UK SEE ALSO ======== `Net::FTPServer(3)' in this node, `Authen::PAM(3)' in this node, `Net::FTP(3)' in this node, `perl(1)' in this node, RFC 765, RFC 959, RFC 1579, RFC 2389, RFC 2428, RFC 2577, RFC 2640, Extensions to FTP Internet Draft draft-ietf-ftpext-mlst-NN.txt.  File: pm.info, Node: Net/FTPServer/DirHandle, Next: Net/FTPServer/FileHandle, Prev: Net/FTPServer/DBeg1/Server, Up: Module List A Net::FTPServer directory handle. ********************************** NAME ==== Net::FTPServer::DirHandle - A Net::FTPServer directory handle. SYNOPSIS ======== use Net::FTPServer::DirHandle; DESCRIPTION =========== METHODS ======= $dirh = new Net::FTPServer::DirHandle ($ftps); Create a new directory handle. The directory handle corresponds to "/". $dirh = $dirh->parent; Return the parent directory of the directory $dirh. If the directory is already "/", this returns the same directory handle. $rv = $dirh->is_root; Return true if the current directory is the root directory. $handle = $dirh->get ($filename); Return the file or directory $handle corresponding to the file $filename in directory $dirh. If there is no file or subdirectory of that name, then this returns undef. $ref = $dirh->list ([$wildcard]); Return a list of the contents of directory $dirh. The list returned is a reference to an array of pairs: [ $filename, $handle ] The list returned does not include "." or "..". The list is sorted into alphabetical order automatically. $ref = $dirh->list_status ([$wildcard]); Return a list of the contents of directory $dirh and status information. The list returned is a reference to an array of triplets: [ $filename, $handle, $statusref ] where $statusref is the tuple returned from the status method (see *Note Net/FTPServer/Handle: Net/FTPServer/Handle,). The list returned does not include "." or "..". The list is sorted into alphabetical order automatically. $rv = $dirh->delete; Delete the current directory. If the delete command was successful, then return 0, else if there was an error return -1. It is normally only possible to delete a directory if it is empty. $rv = $dirh->mkdir ($name); Create a subdirectory called $name within the current directory $dirh. $file = $dirh->open ($filename, "r"|"w"|"a"); Open or create a file called $filename in the current directory, opening it for either read, write or append. This function returns a IO::File handle object. $rv = $dirh->can_write; Return true if the current user can write into the current directory (ie. create files, rename files, delete files, etc.). $rv = $dirh->can_delete; Return true if the current user can delete the current directory. $rv = $dirh->can_enter; Return true if the current user can enter the current directory. $rv = $dirh->can_list; Return true if the current user can list the current directory. $rv = $dirh->can_rename; Return true if the current user can rename the current directory. $rv = $dirh->can_mkdir; Return true if the current user can create subdirectories of the current directory. AUTHORS ======= Richard Jones (rich@annexia.org). COPYRIGHT ========= Copyright (C) 2000 Biblio@Tech Ltd., Unit 2-3, 50 Carnwath Road, London, SW6 3EG, UK SEE ALSO ======== `Net::FTPServer(3)' in this node, `perl(1)' in this node  File: pm.info, Node: Net/FTPServer/FileHandle, Next: Net/FTPServer/Full/DirHandle, Prev: Net/FTPServer/DirHandle, Up: Module List A Net::FTPServer file handle. ***************************** NAME ==== Net::FTPServer::FileHandle - A Net::FTPServer file handle. SYNOPSIS ======== use Net::FTPServer::FileHandle; DESCRIPTION =========== METHODS ======= $filename = $fileh->filename; Return the filename (last) component. $dirh = $fileh->dir; Return the directory which contains this file. $fh = $fileh->open (["r"|"w"|"a"]); Open a file handle (derived from IO::Handle, see `IO::Handle(3)' in this node) in either read or write mode. $rv = $fileh->delete; Delete the current file. If the delete command was successful, then return 0, else if there was an error return -1. $rv = $fileh->can_read; Return true if the current user can read the given file. $rv = $fileh->can_write; Return true if the current user can overwrite the given file. $rv = $fileh->can_append Return true if the current user can append to the given file. $rv = $fileh->can_rename; Return true if the current user can change the name of the given file. $rv = $fileh->can_delete; Return true if the current user can delete the given file. AUTHORS ======= Richard Jones (rich@annexia.org). COPYRIGHT ========= Copyright (C) 2000 Biblio@Tech Ltd., Unit 2-3, 50 Carnwath Road, London, SW6 3EG, UK SEE ALSO ======== `Net::FTPServer(3)' in this node, `perl(1)' in this node  File: pm.info, Node: Net/FTPServer/Full/DirHandle, Next: Net/FTPServer/Full/FileHandle, Prev: Net/FTPServer/FileHandle, Up: Module List The full FTP server personality ******************************* NAME ==== Net::FTPServer::Full::DirHandle - The full FTP server personality SYNOPSIS ======== use Net::FTPServer::Full::DirHandle; DESCRIPTION =========== METHODS ======= $handle = $dirh->get ($filename); Return the file or directory $handle corresponding to the file $filename in directory $dirh. If there is no file or subdirectory of that name, then this returns undef. $dirh = $dirh->parent; Return the parent directory of the directory $dirh. If the directory is already "/", this returns the same directory handle. $ref = $dirh->list ([$wildcard]); Return a list of the contents of directory $dirh. The list returned is a reference to an array of pairs: [ $filename, $handle ] The list returned does not include "." or "..". The list is sorted into alphabetical order automatically. $ref = $dirh->list_status ([$wildcard]); Return a list of the contents of directory $dirh and status information. The list returned is a reference to an array of triplets: [ $filename, $handle, $statusref ] where $statusref is the tuple returned from the status method (see *Note Net/FTPServer/Handle: Net/FTPServer/Handle,). The list returned does not include "." or "..". The list is sorted into alphabetical order automatically. ($mode, $perms, $nlink, $user, $group, $size, $time) = $handle->status; Return the file or directory status. The fields returned are: $mode Mode 'd' = directory, 'f' = file, and others as with the file(1) -type option. $perms Permissions Permissions in normal octal numeric format. $nlink Link count $user Username In printable format. $group Group name In printable format. $size Size File size in bytes. $time Time Time (usually mtime) in Unix time_t format. In derived classes, some of this status information may well be synthesized, since virtual filesystems will often not contain information in a Unix-like format. $rv = $handle->move ($dirh, $filename); Move the current file (or directory) into directory $dirh and call it $filename. If the operation is successful, return 0, else return -1. Underlying filesystems may impose limitations on moves: for example, it may not be possible to move a directory; it may not be possible to move a file to another directory; it may not be possible to move a file across filesystems. $rv = $dirh->delete; Delete the current directory. If the delete command was successful, then return 0, else if there was an error return -1. It is normally only possible to delete a directory if it is empty. $rv = $dirh->mkdir ($name); Create a subdirectory called $name within the current directory $dirh. $file = $dirh->open ($filename, "r"|"w"|"a"); Open or create a file called $filename in the current directory, opening it for either read, write or append. This function returns a IO::File handle object. $rv = $dirh->can_write; Return true if the current user can write into the current directory (ie. create files, rename files, delete files, etc.). $rv = $dirh->can_delete; Return true if the current user can delete the current directory. $rv = $dirh->can_enter; Return true if the current user can enter the current directory. $rv = $dirh->can_list; Return true if the current user can list the current directory. $rv = $dirh->can_rename; Return true if the current user can rename the current directory. $rv = $dirh->can_mkdir; Return true if the current user can create subdirectories of the current directory. AUTHORS ======= Richard Jones (rich@annexia.org). COPYRIGHT ========= Copyright (C) 2000 Biblio@Tech Ltd., Unit 2-3, 50 Carnwath Road, London, SW6 3EG, UK SEE ALSO ======== `Net::FTPServer(3)' in this node, `perl(1)' in this node  File: pm.info, Node: Net/FTPServer/Full/FileHandle, Next: Net/FTPServer/Full/Server, Prev: Net/FTPServer/Full/DirHandle, Up: Module List The full FTP server personality ******************************* NAME ==== Net::FTPServer::Full::FileHandle - The full FTP server personality SYNOPSIS ======== use Net::FTPServer::Full::FileHandle; DESCRIPTION =========== METHODS ======= $dirh = $fileh->dir; Return the directory which contains this file. $fh = $fileh->open (["r"|"w"|"a"]); Open a file handle (derived from IO::Handle, see `IO::Handle(3)' in this node) in either read or write mode. ($mode, $perms, $nlink, $user, $group, $size, $time) = $handle->status; Return the file or directory status. The fields returned are: $mode Mode 'd' = directory, 'f' = file, and others as with the file(1) -type option. $perms Permissions Permissions in normal octal numeric format. $nlink Link count $user Username In printable format. $group Group name In printable format. $size Size File size in bytes. $time Time Time (usually mtime) in Unix time_t format. In derived classes, some of this status information may well be synthesized, since virtual filesystems will often not contain information in a Unix-like format. $rv = $handle->move ($dirh, $filename); Move the current file (or directory) into directory $dirh and call it $filename. If the operation is successful, return 0, else return -1. Underlying filesystems may impose limitations on moves: for example, it may not be possible to move a directory; it may not be possible to move a file to another directory; it may not be possible to move a file across filesystems. $rv = $fileh->delete; Delete the current file. If the delete command was successful, then return 0, else if there was an error return -1. $rv = $fileh->can_read; Return true if the current user can read the given file. $rv = $fileh->can_write; Return true if the current user can overwrite the given file. $rv = $fileh->can_append Return true if the current user can append to the given file. $rv = $fileh->can_rename; Return true if the current user can change the name of the given file. $rv = $fileh->can_delete; Return true if the current user can delete the given file. AUTHORS ======= Richard Jones (rich@annexia.org). COPYRIGHT ========= Copyright (C) 2000 Biblio@Tech Ltd., Unit 2-3, 50 Carnwath Road, London, SW6 3EG, UK SEE ALSO ======== `Net::FTPServer(3)' in this node, `perl(1)' in this node  File: pm.info, Node: Net/FTPServer/Full/Server, Next: Net/FTPServer/Handle, Prev: Net/FTPServer/Full/FileHandle, Up: Module List The full FTP server personality ******************************* NAME ==== Net::FTPServer::Full::Server - The full FTP server personality SYNOPSIS ======== ftpd [-d] [-v] [-p port] [-s] [-S] [-V] [-C conf_file] DESCRIPTION =========== `Net::FTPServer::Full::Server' is the full FTP server personality. This personality implements a complete FTP server with similar functionality to *wu-ftpd*. METHODS ======= $rv = $self->authentication_hook ($user, $pass, $user_is_anon) Perform login against `/etc/passwd' or the PAM database. $self->user_login_hook ($user, $user_is_anon) Hook: Called just after user `$user' has successfully logged in. $dirh = $self->root_directory_hook; Hook: Return an instance of Net::FTPServer::FullDirHandle corresponding to the root directory. FILES ===== /etc/ftpd.conf /usr/lib/perl5/site_perl/5.005/Net/FTPServer.pm /usr/lib/perl5/site_perl/5.005/Net/FTPServer/DirHandle.pm /usr/lib/perl5/site_perl/5.005/Net/FTPServer/FileHandle.pm /usr/lib/perl5/site_perl/5.005/Net/FTPServer/Handle.pm /usr/lib/perl5/site_perl/5.005/Net/FTPServer/Full/Server.pm /usr/lib/perl5/site_perl/5.005/Net/FTPServer/Full/DirHandle.pm /usr/lib/perl5/site_perl/5.005/Net/FTPServer/Full/FileHandle.pm AUTHORS ======= Richard Jones (rich@annexia.org). COPYRIGHT ========= Copyright (C) 2000 Biblio@Tech Ltd., Unit 2-3, 50 Carnwath Road, London, SW6 3EG, UK SEE ALSO ======== `Net::FTPServer(3)' in this node, `Authen::PAM(3)' in this node, `Net::FTP(3)' in this node, `perl(1)' in this node, RFC 765, RFC 959, RFC 1579, RFC 2389, RFC 2428, RFC 2577, RFC 2640, Extensions to FTP Internet Draft draft-ietf-ftpext-mlst-NN.txt.  File: pm.info, Node: Net/FTPServer/Handle, Next: Net/FTPServer/InMem/DirHandle, Prev: Net/FTPServer/Full/Server, Up: Module List A generic Net::FTPServer file or directory handle. ************************************************** NAME ==== Net::FTPServer::Handle - A generic Net::FTPServer file or directory handle. SYNOPSIS ======== use Net::FTPServer::Handle; DESCRIPTION =========== METHODS ======= $handle = Net::FTPServer::Handle->new ($ftps); Create a new handle. You would normally call this from a derived class. $rv = $handle->equals ($other_handle); Decide if two handles refer to the same thing (file or directory). ($mode, $perms, $nlink, $user, $group, $size, $time) = $handle->status; Return the file or directory status. The fields returned are: $mode Mode 'd' = directory, 'f' = file, and others as with the file(1) -type option. $perms Permissions Permissions in normal octal numeric format. $nlink Link count $user Username In printable format. $group Group name In printable format. $size Size File size in bytes. $time Time Time (usually mtime) in Unix time_t format. In derived classes, some of this status information may well be synthesized, since virtual filesystems will often not contain information in a Unix-like format. $name = $handle->pathname; Return the full path of this file or directory. The path consists of all components separated by "/" characters. If the object is a directory, then the pathname will have a "/" character at the end. $name = $handle->filename; Return the filename part of the path. If the file is a directory, then this function returns "". $name = $handle->dirname; Return the directory name part of the path. The directory name always has a trailing "/" character. $rv = $handle->move ($dirh, $filename); Move the current file (or directory) into directory $dirh and call it $filename. If the operation is successful, return 0, else return -1. Underlying filesystems may impose limitations on moves: for example, it may not be possible to move a directory; it may not be possible to move a file to another directory; it may not be possible to move a file across filesystems. $rv = $handle->delete; Delete the current file or directory. If the delete command was successful, then return 0, else if there was an error return -1. Different underlying file systems may impose restrictions on this command: for example, it may not be possible to delete directories, or only if they are empty. This is a virtual function which is actually implemented in one of the subclasses. AUTHORS ======= Richard Jones (rich@annexia.org). COPYRIGHT ========= Copyright (C) 2000 Biblio@Tech Ltd., Unit 2-3, 50 Carnwath Road, London, SW6 3EG, UK SEE ALSO ======== `Net::FTPServer(3)' in this node, `perl(1)' in this node  File: pm.info, Node: Net/FTPServer/InMem/DirHandle, Next: Net/FTPServer/InMem/FileHandle, Prev: Net/FTPServer/Handle, Up: Module List Store files in local memory *************************** NAME ==== Net::FTPServer::InMem::DirHandle - Store files in local memory SYNOPSIS ======== use Net::FTPServer::InMem::DirHandle; DESCRIPTION =========== METHODS ======= AUTHORS ======= Richard Jones (rich@annexia.org). COPYRIGHT ========= Copyright (C) 2000 Biblio@Tech Ltd., Unit 2-3, 50 Carnwath Road, London, SW6 3EG, UK SEE ALSO ======== `Net::FTPServer(3)' in this node, `perl(1)' in this node  File: pm.info, Node: Net/FTPServer/InMem/FileHandle, Next: Net/FTPServer/InMem/Server, Prev: Net/FTPServer/InMem/DirHandle, Up: Module List Store files in local memory *************************** NAME ==== Net::FTPServer::InMem::FileHandle - Store files in local memory SYNOPSIS ======== use Net::FTPServer::InMem::FileHandle; DESCRIPTION =========== METHODS ======= AUTHORS ======= Richard Jones (rich@annexia.org). COPYRIGHT ========= Copyright (C) 2000 Biblio@Tech Ltd., Unit 2-3, 50 Carnwath Road, London, SW6 3EG, UK SEE ALSO ======== `Net::FTPServer(3)' in this node, `perl(1)' in this node  File: pm.info, Node: Net/FTPServer/InMem/Server, Next: Net/FTPServer/RO/DirHandle, Prev: Net/FTPServer/InMem/FileHandle, Up: Module List Store files in local memory *************************** NAME ==== Net::FTPServer::InMem::Server - Store files in local memory SYNOPSIS ======== inmem-ftpd [-d] [-v] [-p port] [-s] [-S] [-V] [-C conf_file] DESCRIPTION =========== `Net::FTPServer::InMem::Server' is the example FTP server personality. This personality implements a simple FTP server which stores files in local memory. This personality is used mainly for automatic testing in the test suites (see the `t/' directory in the distribution). METHODS ======= FILES ===== /etc/ftpd.conf /usr/lib/perl5/site_perl/5.005/Net/FTPServer.pm /usr/lib/perl5/site_perl/5.005/Net/FTPServer/DirHandle.pm /usr/lib/perl5/site_perl/5.005/Net/FTPServer/FileHandle.pm /usr/lib/perl5/site_perl/5.005/Net/FTPServer/Handle.pm /usr/lib/perl5/site_perl/5.005/Net/FTPServer/InMem/Server.pm /usr/lib/perl5/site_perl/5.005/Net/FTPServer/InMem/DirHandle.pm /usr/lib/perl5/site_perl/5.005/Net/FTPServer/InMem/FileHandle.pm AUTHORS ======= Richard Jones (rich@annexia.org). COPYRIGHT ========= Copyright (C) 2000 Biblio@Tech Ltd., Unit 2-3, 50 Carnwath Road, London, SW6 3EG, UK SEE ALSO ======== `Net::FTPServer(3)' in this node.  File: pm.info, Node: Net/FTPServer/RO/DirHandle, Next: Net/FTPServer/RO/FileHandle, Prev: Net/FTPServer/InMem/Server, Up: Module List The anonymous, read-only FTP server personality *********************************************** NAME ==== Net::FTPServer::RO::DirHandle - The anonymous, read-only FTP server personality SYNOPSIS ======== use Net::FTPServer::RO::DirHandle; DESCRIPTION =========== METHODS ======= $handle = $dirh->get ($filename); Return the file or directory $handle corresponding to the file $filename in directory $dirh. If there is no file or subdirectory of that name, then this returns undef. $dirh = $dirh->parent; Return the parent directory of the directory $dirh. If the directory is already "/", this returns the same directory handle. $ref = $dirh->list ([$wildcard]); Return a list of the contents of directory $dirh. The list returned is a reference to an array of pairs: [ $filename, $handle ] The list returned does not include "." or "..". The list is sorted into alphabetical order automatically. $ref = $dirh->list_status ([$wildcard]); Return a list of the contents of directory $dirh and status information. The list returned is a reference to an array of triplets: [ $filename, $handle, $statusref ] where $statusref is the tuple returned from the status method (see *Note Net/FTPServer/Handle: Net/FTPServer/Handle,). The list returned does not include "." or "..". The list is sorted into alphabetical order automatically. ($mode, $perms, $nlink, $user, $group, $size, $time) = $handle->status; Return the file or directory status. The fields returned are: $mode Mode 'd' = directory, 'f' = file, and others as with the file(1) -type option. $perms Permissions Permissions in normal octal numeric format. $nlink Link count $user Username In printable format. $group Group name In printable format. $size Size File size in bytes. $time Time Time (usually mtime) in Unix time_t format. In derived classes, some of this status information may well be synthesized, since virtual filesystems will often not contain information in a Unix-like format. $rv = $handle->move ($dirh, $filename); Move the current file (or directory) into directory $dirh and call it $filename. If the operation is successful, return 0, else return -1. Underlying filesystems may impose limitations on moves: for example, it may not be possible to move a directory; it may not be possible to move a file to another directory; it may not be possible to move a file across filesystems. $rv = $dirh->delete; Delete the current directory. If the delete command was successful, then return 0, else if there was an error return -1. It is normally only possible to delete a directory if it is empty. $rv = $dirh->mkdir ($name); Create a subdirectory called $name within the current directory $dirh. $file = $dirh->open ($filename, "r"|"w"|"a"); Open or create a file called $filename in the current directory, opening it for either read, write or append. This function returns a IO::File handle object. $rv = $dirh->can_write; Return true if the current user can write into the current directory (ie. create files, rename files, delete files, etc.). $rv = $dirh->can_delete; Return true if the current user can delete the current directory. $rv = $dirh->can_enter; Return true if the current user can enter the current directory. $rv = $dirh->can_list; Return true if the current user can list the current directory. $rv = $dirh->can_rename; Return true if the current user can rename the current directory. $rv = $dirh->can_mkdir; Return true if the current user can create subdirectories of the current directory. AUTHORS ======= Richard Jones (rich@annexia.org). COPYRIGHT ========= Copyright (C) 2000 Biblio@Tech Ltd., Unit 2-3, 50 Carnwath Road, London, SW6 3EG, UK SEE ALSO ======== `Net::FTPServer(3)' in this node, `perl(1)' in this node  File: pm.info, Node: Net/FTPServer/RO/FileHandle, Next: Net/FTPServer/RO/Server, Prev: Net/FTPServer/RO/DirHandle, Up: Module List The anonymous, read-only FTP server personality *********************************************** NAME ==== Net::FTPServer::RO::FileHandle - The anonymous, read-only FTP server personality SYNOPSIS ======== use Net::FTPServer::RO::FileHandle; DESCRIPTION =========== METHODS ======= $dirh = $fileh->dir; Return the directory which contains this file. $fh = $fileh->open (["r"|"w"|"a"]); Open a file handle (derived from IO::Handle, see `IO::Handle(3)' in this node) in either read or write mode. ($mode, $perms, $nlink, $user, $group, $size, $time) = $handle->status; Return the file or directory status. The fields returned are: $mode Mode 'd' = directory, 'f' = file, and others as with the file(1) -type option. $perms Permissions Permissions in normal octal numeric format. $nlink Link count $user Username In printable format. $group Group name In printable format. $size Size File size in bytes. $time Time Time (usually mtime) in Unix time_t format. In derived classes, some of this status information may well be synthesized, since virtual filesystems will often not contain information in a Unix-like format. $rv = $handle->move ($dirh, $filename); Move the current file (or directory) into directory $dirh and call it $filename. If the operation is successful, return 0, else return -1. Underlying filesystems may impose limitations on moves: for example, it may not be possible to move a directory; it may not be possible to move a file to another directory; it may not be possible to move a file across filesystems. $rv = $fileh->delete; Delete the current file. If the delete command was successful, then return 0, else if there was an error return -1. $rv = $fileh->can_read; Return true if the current user can read the given file. $rv = $fileh->can_write; Return true if the current user can overwrite the given file. $rv = $fileh->can_append Return true if the current user can append to the given file. $rv = $fileh->can_rename; Return true if the current user can change the name of the given file. $rv = $fileh->can_delete; Return true if the current user can delete the given file. AUTHORS ======= Richard Jones (rich@annexia.org). COPYRIGHT ========= Copyright (C) 2000 Biblio@Tech Ltd., Unit 2-3, 50 Carnwath Road, London, SW6 3EG, UK SEE ALSO ======== `Net::FTPServer(3)' in this node, `perl(1)' in this node  File: pm.info, Node: Net/FTPServer/RO/Server, Next: Net/Finger, Prev: Net/FTPServer/RO/FileHandle, Up: Module List The anonymous read-only FTP server personality ********************************************** NAME ==== Net::FTPServer::RO::Server - The anonymous read-only FTP server personality SYNOPSIS ======== ftpd [-d] [-v] [-p port] [-s] [-S] [-V] [-C conf_file] DESCRIPTION =========== `Net::FTPServer::RO::Server' is the anonymous read-only FTP server personality. This personality implements a complete FTP server with similar functionality to *wu-ftpd*, except that it is not possible to write and all logins must be anonymous. METHODS ======= $rv = $self->authentication_hook ($user, $pass, $user_is_anon) Perform login against `/etc/passwd' or the PAM database. $self->user_login_hook ($user, $user_is_anon) Hook: Called just after user `$user' has successfully logged in. $dirh = $self->root_directory_hook; Hook: Return an instance of Net::FTPServer::RO::DirHandle corresponding to the root directory. FILES ===== /etc/ftpd.conf /usr/lib/perl5/site_perl/5.005/Net/FTPServer.pm /usr/lib/perl5/site_perl/5.005/Net/FTPServer/DirHandle.pm /usr/lib/perl5/site_perl/5.005/Net/FTPServer/FileHandle.pm /usr/lib/perl5/site_perl/5.005/Net/FTPServer/Handle.pm /usr/lib/perl5/site_perl/5.005/Net/FTPServer/RO/Server.pm /usr/lib/perl5/site_perl/5.005/Net/FTPServer/RO/DirHandle.pm /usr/lib/perl5/site_perl/5.005/Net/FTPServer/RO/FileHandle.pm AUTHORS ======= Richard Jones (rich@annexia.org). COPYRIGHT ========= Copyright (C) 2000 Biblio@Tech Ltd., Unit 2-3, 50 Carnwath Road, London, SW6 3EG, UK SEE ALSO ======== `Net::FTPServer(3)' in this node, `Authen::PAM(3)' in this node, `Net::FTP(3)' in this node, `perl(1)' in this node, RFC 765, RFC 959, RFC 1579, RFC 2389, RFC 2428, RFC 2577, RFC 2640, Extensions to FTP Internet Draft draft-ietf-ftpext-mlst-NN.txt.  File: pm.info, Node: Net/Finger, Next: Net/Gen, Prev: Net/FTPServer/RO/Server, Up: Module List a Perl implementation of a finger client. ***************************************** NAME ==== Net::Finger - a Perl implementation of a finger client. SYNOPSIS ======== use Net::Finger; # You can put the response in a scalar... $response = finger('corbeau@execpc.com'); unless ($response) { warn "Finger problem: $Net::Finger::error"; } # ...or an array. @lines = finger('corbeau@execpc.com', 1); DESCRIPTION =========== Net::Finger is a simple, straightforward implementation of a finger client in Perl - so simple, in fact, that writing this documentation is almost unnecessary. This module has one automatically exported function, appropriately entitled `finger()'. It takes two arguments: * A username or email address to finger. (Yes, it does support the vaguely deprecated "user@host@host" syntax.) If you need to use a port other than the default finger port (79), you can specify it like so: "username@hostname:port". * (Optional) A boolean value for verbosity. True == verbose output. If you don't give it a value, it defaults to false. Actually, whether this output will differ from the non-verbose version at all is up to the finger server. `finger()' is context-sensitive. If it's used in a scalar context, it will return the server's response in one large string. If it's used in an array context, it will return the response as a list, line by line. If an error of some sort occurs, it returns undef and puts a string describing the error into the package global variable `$Net::Finger::error'. If you'd like to see some excessively verbose output describing every step `finger()' takes while talking to the other server, put a true value in the variable `$Net::Finger::debug'. Here's a sample program that implements a very tiny, stripped-down finger(1): #!/usr/bin/perl -w use Net::Finger; use Getopt::Std; use vars qw($opt_l); getopts('l'); $x = finger($ARGV[0], $opt_l); if ($x) { print $x; } else { warn "$0: error: $Net::Finger::error\n"; } BUGS ==== * Doesn't yet do non-blocking requests. (FITNR. Really.) * Doesn't do local requests unless there's a finger server running on localhost. * Contrary to the name's implications, this module involves no teledildonics. AUTHOR ====== Dennis Taylor, SEE ALSO ======== perl(1), finger(1), RFC 1288.  File: pm.info, Node: Net/Gen, Next: Net/Goofey, Prev: Net/Finger, Up: Module List generic sockets interface handling ********************************** NAME ==== Net::Gen - generic sockets interface handling SYNOPSIS ======== use Net::Gen; DESCRIPTION =========== The `Net::Gen' module provides basic services for handling socket-based communications. It supports no particular protocol family directly, however, so it is of direct use primarily to implementors of other modules. To this end, several housekeeping functions are provided for the use of derived classes, as well as several inheritable methods. The `Net::Gen' class does inherit from IO::Handle, thus making its methods available. See `METHODS', *Note IO/Handle: IO/Handle, for details on those methods. However, some of those methods are overridden, so be sure to check the methods described below to be sure. (In particular, the fcntl and ioctl methods are overridden.) Also provided in this distribution are `Net::Inet', `Net::TCP', `Net::TCP::Server', `Net::UDP', `Net::UNIX', and `Net::UNIX::Server', which are layered atop `Net::Gen'. Public Methods -------------- The public methods are listed alphabetically below. Here is an indication of their functional groupings: Creation and setup new, new_from_fd, new_from_fh, init, checkparams, open, connect, bind, listen Parameter manipulation setparams, setparam, delparams, delparam, getparams, getparam, param_saver Low-level control unbind, condition, getsopt, getropt, setsopt, setropt, fcntl, ioctl Medium-level control getsockinfo, shutdown, stopio, close Informational isopen, isconnected, isbound, didlisten, fhvec, getfh, fileno I/O send, sendto, put, recv, get, getline, gets, select, accept Utility routines format_addr, format_local_addr, format_remote_addr Tied filehandle support SEND, PRINT, PRINTF, RECV, READLINE, READ, GETC, WRITE, CLOSE, EOF, BINMODE, FILENO, TIEHANDLE Tied scalar support FETCH, STORE, TIESCALAR Accessors Any of the keys known to the getparam and setparams methods may be used as an *accessor* function. See `"Known Object Parameters"' in this node below, and the related sections in the derived classes. For an example, see `"blocking"' in this node below. The descriptions, listed alphabetically: accept Usage: $newobj = $obj->accept; Returns a new object in the same class as the given object if an accept() call succeeds, and undef otherwise. If the accept() call succeeds, the new object is marked as being open, connected, and bound. This can fail unexpectedly if the listening socket is non-blocking or if the object has a timeout parameter. See the discussion of non-blocking sockets and timeouts in `' in this node below. bind Usage: $ok = $obj->bind; Makes a call to the bind() builtin on the filehandle associated with the object. The arguments to bind() are determined from the current parameters of the object. First, if the filehandle has previously been bound or connected, it is closed. Then, if it is not currently open, a call to the open method is made. If all that works (which may be a no-op), then the following list of possible values is tried for the bind() builtin: First, the srcaddrlist object parameter, if its value is an array reference. The elements of the array are tried in order until a bind() succeeds or the list is exhausted. Second, if the srcaddrlist parameter is not set to an array reference, if the srcaddr parameter is a non-null string, it will be used. Finally, if neither srcaddrlist nor srcaddr is suitably set, the AF parameter will be used to construct a sockaddr structure which will be mostly zeroed, and the bind() will be attempted with that. If the bind() fails, undef will be returned at this point. Otherwise, a call to the getsockinfo method will be made, and then the value from a call to the isbound method will be returned. If all that seems too confusing, don't worry. Most clients will never need to do an explicit bind call, anyway. If you're writing a server or a privileged client which does need to bind to a particular local port or address, and you didn't understand the foregoing discussion, you may be in trouble. Don't panic until you've checked the discussion of binding in the derived class you're using, however. BINMODE Usage: binmode(TIEDFH); A no-op provided for the tied file handle support of perl 5.005_57. The sockets managed by this module are always set binmode() anyway. blocking Usage: $isblocking = $obj->blocking; $oldblocking = $obj->blocking($newvalue); The blocking method is an example of an *accessor* method. The above usage examples are (effectively) equivalent to the following code snippets, respectively: $isblocking = $obj->getparam('blocking'); $oldblocking = $obj->getparam('blocking'); $obj->setparams({blocking=>$newvalue}); The getparam method call is skipped if the accessor method was called in void context. checkparams Usage: $ok = $obj->checkparams; Verifies that all previous parameter assignments are valid. (Normally called only via the init method, rather than directly.) close CLOSE Usage: $ok = $obj->close; $ok = close(TIEDFH); The close method is like a call to the shutdown method followed by a call to the stopio method. It is the standard way to close down an object. condition Usage: $obj->condition; (Re-)establishes the condition of the associated filehandle after an open() or accept(). (In other words, the open and accept methods call the condition method.) Sets the socket to be autoflushed and marks it binmode(). This method attempts to set the socket blocking or non-blocking, depending on the state of the object's blocking parameter. (It may update that parameter if the socket's state cannot be made to match.) No useful value is returned. connect Usage: $ok = $obj->connect; Attempts to establish a connection for the object. [Note the special information for re-trying connects on non-blocking sockets, later in this section.] First, if the object is currently connected or has been connected since the last time it was opened, its close method is called. Then, if the object is not currently open, its open method is called. If it's not open after that, undef is returned. If it is open, and if either of its srcaddrlist or srcaddr parameters are set to indicate that a bind() is desired, and it is not currently bound, its bind method is called. If the bind method is called and fails, undef is returned. (Most of the foregoing is a no-op for simple clients, so don't panic.) Next, if the dstaddrlist object parameter is set to an array reference, a call to connect() is made for each element of the list until it succeeds or the list is exhausted. If the dstaddrlist parameter is not an array reference, a single attempt is made to call connect() with the dstaddr object parameter. If no connect() call succeeded, undef is returned. Finally, a call is made to the object's getsockinfo method, and then the value from a call to its isconnected method is returned. Each of the attempts with the connect() builtin is timed out separately. If there is no timeout parameter for the object, and the socket is blocking (which is the default), the timeout period is strictly at the mercy of your operating system. If there is no timeout parameter and the socket is non-blocking, that's effectively the same as having a timeout parameter value of 0. If there is a timeout parameter, the socket is made non-blocking temporarily (see `"param_saver"' in this node below), and the indicated timeout value will be used to limit the connection attempt. An attempt is made to preserve any meaningful $! values when all connection attempts have failed. In particular, if the timeout parameter is 0, then each failed connect returns without completing the processing of the dstaddrlist object parameter. This is so that the re-try logic for connections in progress will be more useful. If, on entry to the connect method, the object is already marked as having a connection in progress (`$obj->isconnecting' returns true), then the connection will be re-tried with a timeout of 0 to see whether it has succeeded in the meanwhile. The appropriate success/fail condition for that check will be returned, with no further processing of the dstaddrlist object parameter. Note that the derived classes tend to provide additional capabilities which make the connect method easier to use than the above description would indicate. delparam Usage: $ok = $obj->delparam($keyname); Sugar-coated call to the delparams method. delparams Usage: $ok = $obj->delparams(\@keynames); Removes the settings for the specified parameters. Uses the setparams method (with undef for the values) to validate that the removal is allowed by the owning object. If the invocation of setparams is successful, then the parameters in question are removed. Returns 1 if all the removals were successful, and undef otherwise. didlisten Usage: $ok = $obj->didlisten; Returns true if the object's listen method has been used successfully, and the object is still bound. If this method has not been overridden by a derived class, the value is undef on failure and the `$maxqueue' value used for the listen() builtin on success. EOF Usage: $iseof = $obj->EOF(); $iseof = eof(TIEDFH); Provided for tied filehandle support. Determines whether select() says that a read would work immediately, and tries it if so. If the read was tried and returned an eof condition, 1 is returned. The return is 0 on read errors or when select() said that a read would block. Note that this interferes with use of the select() built-in, since it has to buffer the read data if the read was successful. fcntl Usage: $rval = $obj->fcntl($func, $value); Returns the result of an fcntl() call on the associated I/O stream. fhvec Usage: $vecstring = $obj->fhvec; Returns a vector suitable as an argument to the 4-argument select() call. This is for use in doing selects with multiple I/O streams. See also `"select"' in this node. fileno FILENO Usage: $fnum = $obj->fileno; $fnum = fileno(TIEDFH); Returns the actual file descriptor number for the underlying socket. See `"getfh"' in this node for some restrictions as to the safety of using this. format_addr Usage: $string = $obj->format_addr($sockaddr); $string = format_addr Module $sockaddr; Returns a formatted representation of the address. This is a method so that it can be overridden by derived classes. It is used to implement "pretty-printing" methods for source and destination addresses. format_local_addr Usage: $string = $obj->format_local_addr; Returns a formatted representation of the local socket address associated with the object. format_remote_addr Usage: $string = $obj->format_remote_addr; Returns a formatted representation of the remote socket address associated with the object. get This is just a sugar-coated way to call the recv method which will work with indirect-object syntax. See `"recv"' in this node for details. GETC Usage: $char = $obj->GETC; $char = getc(TIEDFH); This method uses the recv method with a $flags argument of 0 and a $maxlen argument of 1 to emulate the getc() builtin. Like that builtin, it returns a string representing the character read when successful, and undef on eof or errors. This method exists for the support of tied filehandles. It's unreliable for non-blocking sockets. getfh Usage: $fhandle = $obj->getfh; I've strongly resisted giving people direct access to the filehandle embedded in the object because of the problems of mixing `stdio' input calls and traditional socket-level I/O. However, if you're sure you can keep things straight, here are the rules under which it's safe to use the embedded filehandle: * Don't use perl's own `stdio' calls. Stick to sysread() and recv(). * Don't use the object's getline method, since that stores a read-ahead buffer in the object which only the object's own get/recv and getline methods know to return to you. (The object's select method knows about the buffer enough to tell you that a read will succeed if there's saved data, though.) Similarly, avoid the object's EOF method. * Please don't change the state of the socket behind my back. That means no close(), shutdown(), connect(), bind(), or listen() built-ins. Use the corresponding methods instead, or all bets are off. Of course, if you're only using this module to get the connect() or bind() processing, and you're going to discard the object after you've done your I/O, then it's OK to use the built-ins for I/O. Just don't expect my code to know what you did behind my back. That $fh is a glob ref, by the way, but that doesn't matter for calling the built-in I/O primitives. getline Usage: $line = $obj->getline; This is a simulation of `scalar(<$filehandle>)' that doesn't let stdio confuse the get/recv method. As such, its return value is not necessarily a complete line when the socket is non-blocking. getlines Usage: @lines = $obj->getlines; This is a lot like `@lines = <$filehandle>', except that it doesn't let stdio confuse the get/recv method. It's unreliable on non-blocking sockets. It will produce a fatal (but trappable) error if not called in list context. (In other words, it uses the die() builtin when not called in list context.) getparam Usage: $value = $obj->getparam($key, $defval, $def_if_undef); $value = $obj->getparam($key, $defval); $value = $obj->getparam($key); Returns the current setting for the named parameter (in the current object), or the specified default value if the parameter is not in the object's current parameter list. If the optional `$def_if_undef' parameter is true, then undefined values will be treated the same as non-existent keys, and thus will return the supplied default value (`$defval'). getparams Usage: %hash = $obj->getparams(\@keynames, $noundefs); %hash = $obj->getparams(\@keynames); $llen = $obj->getparams(\@keynames, $noundefs); $llen = $obj->getparams(\@keynames); Returns a hash as a list (not a reference) consisting of the key-value pairs corresponding to the specified keyname list. Only those keys which exist in the current parameter list of the object will be returned. If the `$noundefs' parameter is present and true, then existing keys with undefined values will be suppressed as with non-existent keys. If called in scalar context, returns the number of values which would have been returned in list context. (This is twice the number of key-value pairs, in case that wasn't clear.) getropt Usage: $optsetting = $obj->getropt($level, $option); $optsetting = $obj->getropt($optname); Returns the raw value from a call to the getsockopt() builtin. If both the `$level' and $option arguments are given as numbers, the getsockopt() call will be made even if the given socket option is not registered with the object. Otherwise, the return value for unregistered options will be undef with the value of $! set as described below for the getsopt method. gets Usage: $line = $obj->gets; This is a simulation of `scalar(<$filehandle>)' that doesn't let stdio confuse the get/recv method. (The gets method is just an alias for the getline method, for partial compatibility with the POSIX module.) This method is deprecated. Use the getline method by that name, instead. The gets method may disappear in a future release. getsockinfo Usage: ($localsockaddr, $peersockaddr) = $obj->getsockinfo; $peersockaddr = $obj->getsockinfo; Attempts to determine connection parameters associated with the object. If a getsockname() call on the associated filehandle succeeds, the srcaddr object parameter is set to that returned sockaddr. If a getpeername() call on the associated filehandle succeeds, the dstaddr parameter is set to that returned sockaddr. In scalar context, if both socket addresses were found, the getpeername() value is returned, otherwise undef is returned. In list context, the getsockname() and getpeername() values are returned, unless both are undefined. Derived classes normally override this method with one which provides friendlier return information appropriate to the derived class, and which establishes more of the object parameters. getsopt Usage: @optvals = $obj->getsopt($level, $option); @optvals = $obj->getsopt($optname); Returns the unpacked values from a call to the getsockopt() builtin. In order to do the unpacking, the socket option must have been registered with the object. See the additional discussion of socket options in `' in this node below. Since registered socket options are known by name as well as by their level and option values, it is possible to make calls using only the option name. If the name is not registered with the object, the return value is the same as that for `getsopt $obj -1,-1', which is an empty return array and $! set appropriately (should be `EINVAL'). Examples: ($sotype) = $obj->getsopt('SO_TYPE'); @malinger = $obj->getsopt(SOL_SOCKET, SO_LINGER); ($sodebug) = $obj->getsopt('SOL_SOCKET', 'SO_DEBUG'); init Usage: return undef unless $self->init; Verifies that all previous parameter assignments are valid (via checkparams). Returns the incoming object on success, and undef on failure. This method is normally called from the new method appropriate to the class of the created object. ioctl Usage: $rval = $obj->ioctl($func, $value); Returns the result of an ioctl() call on the associated I/O stream. isbound Usage: $ok = $obj->isbound; Returns true if the object's bind method has been used successfully, and the binding is still in effect. If this method has not been overridden by a derived class, the value is the saved return value of the call to the bind() builtin (if it was called). isconnected Usage: $ok = $obj->isconnected; Returns true if the object's connect method has been used successfully to establish a "session", and that session is still connected. If this method has not been overridden by a derived class, the value is the saved return value of the call to the connect() builtin (if it was called). isconnecting Usage: $ok = $obj->isconnecting; Returns true if the object's connect method has been used with a timeout or on a non-blocking socket, and the connect() did not complete. In other words, the failure from the connect() builtin indicated that the operation was still in progress. (A rejected connection or a connection which exceeded the operating system's timeout is said to have completed unsuccessfully, rather than not to have completed.) isopen Usage: $ok = $obj->isopen; Returns true if the object currently has a socket attached to its associated filehandle, and false otherwise. If this method has not been overridden by a derived class, the value is the saved return value of the call to the socket() builtin (if it was called). listen Usage: $ok = $obj->listen($maxqueue); $ok = $obj->listen; Makes a call to the listen() builtin on the filehandle associated with the object. Propagates the return value from listen(). If the `$maxqueue' parameter is missing, it defaults to the value of the object's maxqueue parameter, or the value of `SOMAXCONN'. If the `SOMAXCONN' constant is not available in your configuration, the default value used for the listen method is 5. This method will fail if the object is not bound and cannot be made bound by a simple call to its bind method. new Usage: $obj = $classname->new(); $obj = $classname->new(\%parameters); Returns a newly-initialised object of the given class. If called for a class other than `Net::Gen', no validation of the supplied parameters will be performed. (This is so that the derived class can add the parameter validation it needs to the object before allowing validation.) new_from_fd new_from_fh Usage: $obj = $classname->new_from_fh(*FH); $obj = $classname->new_from_fh(\*FH); $obj = $classname->new_from_fd(fileno($fh)); Returns a newly-initialised object of the given class, open on a newly-dup()ed copy of the given filehandle or file descriptor. As many of the standard object parameters as possible will be determined from the passed filehandle. This is determined (in part) by calling the corresponding new, init, and getsockinfo methods for the new object. Only real filehandles or file descriptor numbers are allowed as arguments. This method makes no attempt to resolve filehandle names. Yes, despite having two names, there's really just one method. open Usage: $ok = $obj->open; Makes a call to the socket() builtin, using the current object parameters to determine the desired protocol family, socket type, and protocol number. If the object was already open, its stopio method will be called before socket() is called again. The object parameters consulted (and possibly updated) are PF, AF, proto, type, and blocking. Returns true if the socket() call results in an open filehandle, undef otherwise. param_saver paramSaver Usage: my $savedstuff = $obj->param_saver(@param_names); my $savedstuff = $obj->paramSaver(@param_names); Saves the values (or lack thereof) for the indicated parameter names by wrapping them (and the original object) in an object blessed into an alternate package. When this `saver' object is destroyed (typically because the `my' variable went out of scope), the previous values of the parameters for the original object will be restored. This allows for temporary changes to an object's parameter settings without the worry of whether an inopportune die() will prevent the restoration of the original settings. An example (from the connect method): my $saveblocking = $self->param_saver('blocking'); (This is used when there is a timeout parameter for the object.) print PRINT See `' in this node for details, as this method is just an alias for the put method. The PRINT alias is for the support of tied filehandles. PRINTF Usage: $ok = $obj->PRINTF($format, @args); $ok = printf TIEDFH $format, @args; This method uses the sprintf() builtin and the PRINT method to send the @args values to the filehandle associated with the object, using the $format format string. It exists for the support of tied filehandles. put Usage: $ok = $obj->put(@whatever); $ok = put $obj @whatever; This method uses the print() builtin to send the @whatever arguments to the filehandle associated with the object. That filehandle is always marked for autoflushing by the open method, so the method is in effect equivalent to this: $ok = $obj->send(join($, , @whatever) . $\ , 0); However, since multiple fwrite() calls are sometimes involved in the actual use of print(), this method can be more efficient than the above code sample for large strings in the argument list. It's a bad idea except on stream sockets (`SOCK_STREAM') though, since the record boundaries are unpredictable through `stdio'. It's also a bad idea on non-blocking sockets, since the amount of data actually written to the socket is unknown. This method makes no attempt to trap `SIGPIPE'. READ Usage: $numread = $obj->READ($buffer, $maxlen); $numread = $obj->READ($buffer, $maxlen, $offset); $numread = read(TIEDFH, $buffer, $maxlen); $numread = read(TIEDFH, $buffer, $maxlen, $offset); This method uses the recv method (with a flags argument of 0) to emulate the read() and sysread() builtins. This is specifically for the support of tied filehandles. Like the emulated builtins, this method returns the number of bytes successfully read, or undef on error. READLINE Usage: $line = $obj->READLINE; @lines = $obj->READLINE; $line = readline(TIEDFH); # or $line = ; @lines = readline(TIEDFH); # or @lines = ; This method supports the use of the <> (or readline()) operator on tied filehandles. In scalar context, it uses the getline method. In list context, it reads all remaining input on the socket (until eof, which makes this unsuitable for connectionless socket types such as UDP), and splits it into lines based on the current value of the $/ variable. The return value is unreliable for non-blocking sockets. RECV Usage: $from = $obj->RECV($buffer, $maxlen, $flags); $from = $obj->RECV($buffer, $maxlen); $from = $obj->RECV($buffer); This method calls the recv() method with the arguments and return rearranged to match the recv() builtin. This is for the support of tied filehandles. recv Usage: $record = $obj->recv($maxlen, $flags, $whence); $record = $obj->recv($maxlen, $flags); $record = $obj->recv($maxlen); $record = $obj->recv; This method calls the recv() builtin, and returns a buffer (if one is received) or undef on eof or error. If an eof is seen on the socket (as checked with its ckeof method), then $! will be 0 on return. If the `$whence' argument is supplied, it will be filled in with the sending socket address if possible. If the $flags argument is not supplied, it defaults to 0. If the `$maxlen' argument is not supplied, it is defaulted to the receive buffer size of the associated filehandle (if known), or the preferred blocksize of the associated filehandle (if known, which it usually won't be), or 8192. select Usage: ($nfound, $timeleft, $rbool, $wbool, $xbool) = $obj->select($doread, $dowrite, $doxcept, $timeout); $nfound = $obj->select($doread, $dowrite, $doxcept, $timeout); Issues a 4-argument select() call for the associated I/O stream. All arguments are optional. The $timeout argument is the same as the fourth argument to the select() builtin. The first three are booleans, used to determine whether the method should include the object's I/O stream in the corresponding parameter to the select() call. The return in list context is the standard two values from select(), follwed by booleans indicating whether the actual select() call found reading, writing, or exception to be true. In scalar context, the routine returns only the count of the number of matching conditions. This is probably only useful when you're checking just one of the three possible conditions. SEND send Usage: $ok = $obj->send($buffer, $flags, $destsockaddr); $ok = $obj->send($buffer, $flags); $ok = $obj->send($buffer); This method calls the send() builtin (three- or four-argument form). The $flags parameter is defaulted to 0 if not supplied. If the `$destsockaddr' value is missing or undefined, and the socket is connected (`$obj->isconnected' returns true), then the three-argument form of the send() builtin will be used. Otherwise, the `$destsockaddr' parameter will be defaulted from the last recv() peer address for the same kind of message (depending on whether `MSG_OOB' is set in the $flags parameter). A defined `$destsockaddr' will result in a four-argument send() call. The return value from the send() builtin is returned. This method makes no attempt to trap `SIGPIPE'. sendto Usage: $ok = $obj->sendto($buffer, $destsockaddr, $flags); $ok = $obj->sendto($buffer, $destsockaddr); This method calls the send() builtin (four-argument form). The $flags parameter is defaulted to 0 if not supplied. The return value from the send() builtin is returned. This method makes no attempt to trap `SIGPIPE'. setparam Usage: $ok = $obj->setparam($key, $value, $newonly, $checkup); $ok = $obj->setparam($key, $value, $newonly); $ok = $obj->setparam($key, $value); Sets a single new parameter. Uses the setparams method, and has the same rules for the handling of the `$newonly' and `$checkup' parameters. Returns 1 if the set was successful, and undef otherwise. setparams Usage: $ok = $obj->setparams(\%newparams, $newonly, $checkup); $ok = $obj->setparams(\%newparams, $newonly); $ok = $obj->setparams(\%newparams); Sets new parameters from the given hashref, with validation. This is done in a loop over the *key, value* pairs from the `newparams' parameter. The precise nature of the validation depends on the `$newonly' and `$checkup' parameters (which are optional), but in all cases the keys to be set are checked against those registered with the object. If the `$newonly' parameter is negative, the value from the hashref will only be set if there is not already a defined value associated with that key, but the skipping of the setting of the value is silent. If the `$newonly' parameter is not negative or if there is no existing defined value, if the `$checkup' parameter is false then the setting of the new value is skipped if the new value is identical to the old value. If those checks don't cause the setting of a new value to be skipped, then if the `$newonly' parameter is positive and there is already a defined value for the specified key, a warning will be issued and the new value will not be set. If none of the above checks cause the setting of a new value to be skipped, but if the specified key has a validation routine, that routine will be called with the given object, the current key, and the proposed new value as parameters. It is allowed for the validation routine to alter the new-value argument to change what will be set. (This is useful when changing a hostname to be in canonical form, for example.) If the validation routine returns a non-null string, that will be used to issue a warning, and the new value will not be set. If the validation routine returns a null string (or if there is no validation routine), the new value will (finally) get set for the given key. The setparams method returns 1 if all parameters were successfully set, and undef otherwise. setropt Usage: $ok = $obj->setropt($level, $option, $rawvalue); $ok = $obj->setropt($optname, $rawvalue); Returns the result from a call to the setsockopt() builtin. If the $level and $option arguments are both given as numbers, the setsockopt() call will be made even if the option is not registered with the object. Otherwise, unregistered options will fail as for the setsopt method, below. setsopt Usage: $ok = $obj->setsopt($level, $option, @optvalues); $ok = $obj->setsopt($optname, @optvalues); Returns the result from a call to the setsockopt() builtin. In order to be able to pack the `@optvalues', the option must be registered with the object, just as described in `' in this node above. shutdown Usage: $ok = $obj->shutdown($how); $ok = $obj->shutdown; Calls the shutdown() builtin on the filehandle associated with the object. This method is a no-op, returning 1, if the filehandle is not connected. The `$how' parameter is as per the shutdown() builtin, which in turn should be as described in the shutdown(2) manpage. If the `$how' parameter is not present, it is assumed to be `SHUT_RDWR' (which is 2 on most UNIX systems). Returns 1 if it has nothing to do, otherwise propagates the return from the shutdown() builtin. stopio Usage: $ok = $obj->stopio; Calls the close() builtin on the filehandle associated with the object, unless that filehandle is already closed. Returns 1 or the return value from the close() builtin. This method is primarily for the use of server modules which need to avoid shutdown calls at inappropriate times. This method calls the delparams method for the keys of srcaddr and dstaddr. unbind Usage: $obj->unbind; Removes any saved binding for the object. Unless the object is currently connected, this will result in a call to its close method, in order to ensure that any previous binding is removed. Even if the object is connected, the srcaddrlist object parameter is removed (via the object's delparams method). The return value from this method is indeterminate. wasconnected Usage: $was = $obj->wasconnected; Returns true if the object has had a successful connect() completion since it was last opened. Returns false after a close() or on a new object. Also returns true if `$obj->isconnecting' is true. WRITE Usage: $nwritten = $obj->WRITE($buf, $len); $nwritten = $obj->WRITE($buf, $len, $offset); $nwritten = syswrite(TIEDFH, $buf, $len); $nwritten = syswrite(TIEDFH, $buf, $len, $offset); This method exists for support of syswrite() on tied filehandles. It calls the syswrite() builtin on the underlying filehandle with the same parameters. Protected Methods ----------------- Yes, I know that Perl doesn't really have protected methods as such. However, these are the methods which are only useful for implementing derived classes, and not for the general user. ckeof Usage: $wasiteof = $obj->ckeof; After a 0-length read in the get() routine, it calls this method to determine whether such a 0-length read meant EOF. The default method supplied here checks for non-blocking sockets (if necessary), and for a `SOCK_STREAM' socket. If EOF_NONBLOCK is true, or if the VAL_O_NONBLOCK flag was not set in the fcntl() flags for the socket, or if the error code was not VAL_EAGAIN, and the socket is of type `SOCK_STREAM', then this method returns true. It returns a false value otherwise. This method is overridable for classes like `Net::Dnet', which support `SOCK_SEQPACKET' and need to make a protocol-family-specific check to tell a 0-length packet from EOF. initsockopts Usage: $classname->initsockopts($level, \%optiondesc); Given a prototype optiondesc hash ref, updates it to include all the data needed for the values it can find, and deletes the ones it can't. For example, here's a single entry from such a prototype optiondesc: 'SO_LINGER' => ['II'], Given that, and the $level of `SOL_SOCKET', and the incoming class name of `Net::Gen', initsockopts will attempt to evaluate `SO_LINGER' in package `Net::Gen', and if it succeeds it will fill out the rest of the information in the associated array ref, and add another key to the hash ref for the value of `SO_LINGER' (which is 128 on my system). If it can't evaluate that psuedo-constant, it will simply delete that entry from the referenced hash. Assuming a successful evaluation of this entry, the resulting entries would look like this: 'SO_LINGER' => ['II', SO_LINGER+0, SOL_SOCKET+0, 2], SO_LINGER+0 => ['II', SO_LINGER+0, SOL_SOCKET+0, 2], (All right, so the expressions would be known values, but maybe you get the idea.) A completed optiondesc hash is a set of key-value pairs where the value is an array ref with the following elements: [pack template, option value, option level, pack array len] Such a completed optiondesc is one of the required arguments to the register_options method (see below). register_options registerOptions Usage: $obj->register_options($levelname, $level, \%optiondesc); This method attaches the socket options specified by the given option descriptions hash ref and the given level (as text and as a number) to the object. The registered set of socket options is in fact a hashref of hashrefs, where the keys are the level names and level numbers, and the values are the optiondesc hash refs which get registered. Example: $self->register_options('SOL_SOCKET', SOL_SOCKET+0, \%sockopts); register_param_handlers registerParamHandlers Usage: $obj->register_param_handlers(\@keynames, \@keyhandlers); $obj->register_param_handlers(\%key_handler_pairs); This method registers the referenced keynames (if they haven't already been registered), and establishes the referenced keyhandlers as validation routines for those keynames. Each element of the keyhandlers array must be a code reference. When the setparams method invokes the handler, it will be called with three arguments: the target object, the keyname in question, and the proposed new value (which may be undef, especially if being called from the delparams method). See the other discussion of validation routines in the setparams method description, above. register_param_keys registerParamKeys Usage: $obj->register_param_keys(\@keynames); This method registers the referenced keynames as valid parameters for setparams and the like for this object. The new methods can store arbitrary parameter values, but the init method will later ensure that all those keys eventually got registered. This out-of-order setup is allowed because of possible cross-dependencies between the various parameters, so they have to be set before they can be validated (in some cases). _accessor Usage: $value = $obj->_accessor($what); $oldvalue = $obj->_accessor($what, $newvalue); This method implements the use of the known parameter keys as get/set methods. It's used by the customised AUTOLOAD to generate such accessor functions as they're referenced. See `"blocking"' in this node above for an example. Known Socket Options -------------------- These are the socket options known to the `Net::Gen' module itself: `SO_ACCEPTCONN', `SO_BROADCAST', `SO_DEBUG', `SO_DONTROUTE', `SO_ERROR', `SO_EXPANDED_RIGHTS', `SO_FAMILY', `SO_KEEPALIVE', `SO_LINGER', `SO_OOBINLINE', `SO_PAIRABLE', `SO_RCVBUF', `SO_RCVLOWAT', `SO_RCVTIMEO', `SO_REUSEADDR', `SO_REUSEPORT', `SO_SNDBUF', `SO_SNDLOWAT', `SO_SNDTIMEO', `SO_STATE', `SO_TYPE', `SO_USELOOPBACK', `SO_XSE' Known Object Parameters ----------------------- These are the object parameters registered by the `Net::Gen' module itself: AF Address family (will default from PF, and vice versa). blocking Set to 0 when a socket has been marked as non-blocking, and to 1 otherwise. If it's undef, it'll be treated as though it were set to 1. The use of anything which even looks like `stdio' calls on non-blocking sockets as at your own risk. If you don't know how to work with non-blocking sockets already, the results of trying them may surprise you. dstaddr The result of getpeername(), or an ephemeral proposed connect() address. dstaddrlist A reference to an array of socket addresses to try for connect(). maxqueue An override of the default maximum queue depth parameter for listen(). This will be used if the $maxqueue argument to listen() is not supplied. netgen_fakeconnect This parameter is set true to keep the connect method from really calling the connect() built-in if the socket has not had an source address specified and it is not bound. This is used by the `Net::UNIX' and `Net::UDP' modules to keep from exercising a bug in some socket implementations with respect to how datagram sockets are handled. (This was specifically done in response to quirks of Solaris 2.5.1.) Instead, the connect method simply sets the dstaddr object parameter, which the send method will respect. PF Protocol family for this object. proto The protocol to pass to the socket() call (often defaulted to 0). reuseaddr A boolean, indicating whether the bind method should do a setsockopt() call to set `SO_REUSEADDR' to 1. reuseport A boolean, indicating whether the bind method should do a setsockopt() call to set `SO_REUSEPORT' to 1. srcaddr The result of getsockname(), or an ephemeral proposed bind() address. srcaddrlist A reference to an array of socket addresses to try for bind(). timeout The maximum time to wait for connect() or accept() attempts to succeed. See the discussion of timeouts and non-blocking sockets in `' in this node above. type The socket type to create (`SOCK_STREAM', `SOCK_DGRAM', etc.) Non-Method Subroutines ---------------------- pack_sockaddr Usage: $connect_address = pack_sockaddr($family, $fam_addr); Returns a packed `struct sockaddr' corresponding to the provided $family (which must be a number) and the address-family-specific $fam_addr (pre-packed). unpack_sockaddr Usage: ($family, $fam_addr) = unpack_sockaddr($packed_address); The inverse of pack_sockaddr(). Various socket-related errno values. See `":errnos"' in this node for the list. These routines will always be defined, but they will return 0 if the corresponding error symbol was not found on your system. EOF_NONBLOCK Returns a boolean value depending on whether a read from a non-blocking socket can distinguish an end-of-file condition from a no-data-available condition. This corresponds to the value available from the Config module as `$Config::Config{'d_eofnblk'}'), except that EOF_NONBLOCK is always defined. RD_NODATA Gives the integer return value found by the Configure script for a read() system call on a non-blocking socket which has no data available. This is similar to the string representation of the value available from the Config module as `$Config::Config{'rd_nodata'}'. VAL_EAGAIN Gives the value of the error symbol found by the Configure script which is set by a non-blocking filehandle when no data is available. This differs from the value available from the Config module (`$Config::Config{'eagain'}') in that the latter is a string, typically `"EAGAIN"'. VAL_O_NONBLOCK Gives the value found by the Configure script for setting a filehandle non-blocking. The value available from the Config module is a string representing the value found (`$Config::Config{'o_nonblock'}'), whereas the value from VAL_O_NONBLOCK is an integer, suitable for passing to sysopen() or for eventual use in fcntl(). Exports ------- default None. exportable `AF_APPLETALK' `AF_CCITT' `AF_CHAOS' `AF_CTF' `AF_DATAKIT' `AF_DECnet' `AF_DLI' `AF_ECMA' `AF_HYLINK' `AF_IMPLINK' `AF_INET' `AF_ISO' `AF_LAST' `AF_LAT' `AF_LINK' `AF_NETMAN' `AF_NS' `AF_OSI' `AF_PUP' `AF_ROUTE' `AF_SNA' `AF_UNIX' `AF_UNSPEC' `AF_USER' `AF_WAN' `AF_X25' `EADDRINUSE' `EADDRNOTAVAIL' `EAFNOSUPPORT' `EAGAIN' `EALREADY' `EBADF' `EBADMSG' `ECONNABORTED' `ECONNREFUSED' `ECONNRESET' `EDESTADDRREQ' `EHOSTDOWN' `EHOSTUNREACH' `EINPROGRESS' `EINVAL' `EISCONN' `EMSGSIZE' `ENETDOWN' `ENETRESET' `ENETUNREACH' `ENOBUFS' `ENODATA' `ENOENT' `ENOPROTOOPT' `ENOSR' `ENOSTR' `ENOTCONN' `ENOTSOCK' EOF_NONBLOCK `EOPNOTSUPP' `EPFNOSUPPORT' `EPROTO' `EPROTONOSUPPORT' `EPROTOTYPE' `ESHUTDOWN' `ESOCKTNOSUPPORT' `ETIME' `ETIMEDOUT' `ETOOMANYREFS' `EWOULDBLOCK' pack_sockaddr `PF_APPLETALK' `PF_CCITT' `PF_CHAOS' `PF_CTF' `PF_DATAKIT' `PF_DECnet' `PF_DLI' `PF_ECMA' `PF_HYLINK' `PF_IMPLINK' `PF_INET' `PF_ISO' `PF_LAST' `PF_LAT' `PF_LINK' `PF_NETMAN' `PF_NS' `PF_OSI' `PF_PUP' `PF_ROUTE' `PF_SNA' `PF_UNIX' `PF_UNSPEC' `PF_USER' `PF_WAN' `PF_X25' RD_NODATA `SHUT_RD' `SHUT_RDWR' `SHUT_WR' `SOCK_DGRAM' `SOCK_RAW' `SOCK_RDM' `SOCK_SEQPACKET' `SOCK_STREAM' `SOL_SOCKET' `SOMAXCONN' `SO_ACCEPTCONN' `SO_BROADCAST' `SO_DEBUG' `SO_DONTROUTE' `SO_ERROR' `SO_EXPANDED_RIGHTS' `SO_FAMILY' `SO_KEEPALIVE' `SO_LINGER' `SO_OOBINLINE' `SO_PAIRABLE' `SO_RCVBUF' `SO_RCVLOWAT' `SO_RCVTIMEO' `SO_REUSEADDR' `SO_REUSEPORT' `SO_SNDBUF' `SO_SNDLOWAT' `SO_SNDTIMEO' `SO_STATE' `SO_TYPE' `SO_USELOOPBACK' `SO_XSE' unpack_sockaddr VAL_EAGAIN VAL_O_NONBLOCK tags The following *:tags* are available for grouping exported items together: :af `AF_APPLETALK' `AF_CCITT' `AF_CHAOS' `AF_CTF' `AF_DATAKIT' `AF_DECnet' `AF_DLI' `AF_ECMA' `AF_HYLINK' `AF_IMPLINK' `AF_INET' `AF_ISO' `AF_LAST' `AF_LAT' `AF_LINK' `AF_NETMAN' `AF_NS' `AF_OSI' `AF_PUP' `AF_ROUTE' `AF_SNA' `AF_UNIX' `AF_UNSPEC' `AF_USER' `AF_WAN' `AF_X25' :errnos `EADDRINUSE' `EADDRNOTAVAIL' `EAFNOSUPPORT' `EAGAIN' `EALREADY' `EBADF' `EBADMSG' `ECONNABORTED' `ECONNREFUSED' `ECONNRESET' `EDESTADDRREQ' `EHOSTDOWN' `EHOSTUNREACH' `EINPROGRESS' `EINVAL' `EISCONN' `EMSGSIZE' `ENETDOWN' `ENETRESET' `ENETUNREACH' `ENOBUFS' `ENODATA' `ENOENT' `ENOPROTOOPT' `ENOSR' `ENOSTR' `ENOTCONN' `ENOTSOCK' `EOPNOTSUPP' `EPFNOSUPPORT' `EPROTO' `EPROTONOSUPPORT' `EPROTOTYPE' `ESHUTDOWN' `ESOCKTNOSUPPORT' `ETIME' `ETIMEDOUT' `ETOOMANYREFS' `EWOULDBLOCK' :families The union of the :af and :pf tags. :NonBlockVals :non_block_vals EOF_NONBLOCK RD_NODATA VAL_EAGAIN VAL_O_NONBLOCK :pf `PF_APPLETALK' `PF_CCITT' `PF_CHAOS' `PF_CTF' `PF_DATAKIT' `PF_DECnet' `PF_DLI' `PF_ECMA' `PF_HYLINK' `PF_IMPLINK' `PF_INET' `PF_ISO' `PF_LAST' `PF_LAT' `PF_LINK' `PF_NETMAN' `PF_NS' `PF_OSI' `PF_PUP' `PF_ROUTE' `PF_SNA' `PF_UNIX' `PF_UNSPEC' `PF_USER' `PF_WAN' `PF_X25' :routines pack_sockaddr unpack_sockaddr :shutflags `SHUT_RD' `SHUT_WR' `SHUT_RDWR' :sockopts `SO_ACCEPTCONN' `SO_BROADCAST' `SO_DEBUG' `SO_DONTROUTE' `SO_ERROR' `SO_EXPANDED_RIGHTS' `SO_FAMILY' `SO_KEEPALIVE' `SO_LINGER' `SO_OOBINLINE' `SO_PAIRABLE' `SO_RCVBUF' `SO_RCVLOWAT' `SO_RCVTIMEO' `SO_REUSEADDR' `SO_REUSEPORT' `SO_SNDBUF' `SO_SNDLOWAT' `SO_SNDTIMEO' `SO_STATE' `SO_TYPE' `SO_USELOOPBACK' `SO_XSE' :sockvals `SOL_SOCKET' `SOCK_STREAM' `SOCK_DGRAM' `SOCK_RAW' `SOCK_RDM' `SOCK_SEQPACKET' :ALL All of the above. THREADING STATUS ================ This module has been tested with threaded perls, and should be as thread-safe as perl itself. (As of 5.005_03 and 5.005_57, that's not all that safe just yet.) SEE ALSO ======== Net::Inet(3), Net::UNIX(3), Net::Dnet(3) AUTHOR ====== Spider Boardman