|
|
| |
ConfigFile(3) |
User Contributed Perl Documentation |
ConfigFile(3) |
Unix::ConfigFile - Perl interface to various Unix configuration files
The Unix::ConfigFile module provides a base class from which the other
Unix::*File modules are derived. It provides some basic facilities like file
opening, locking, and closing. You do not need to use this module directly
unless you are developing a derived module for an unsupported configuration
file. However, some of the methods documented here are intended for public use
by users of Unix::ConfigFile submodules, so you may find this documentation
useful even if you are not developing your own module.
The ConfigFile object also provides a sequencing API for modules
that wish to preserve the order of the configuration file they read and
write. The sequencer maintains a list of arbitrary data that a submodule may
append, insert, and delete from. Use of the sequencer is completely
optional.
A module that subclasses from Unix::ConfigFile must, at a minimum,
provide two methods, called "read" and "write". Both
methods will receive a filehandle as a parameter (besides the regular object
parameter). The read method is called after the file is opened. It is
expected to read in the configuration file and initialize the
subclass-specific data structures associated with the object. The write
method is called when an object is committed and is expected to write out
the new configuration to the supplied filehandle.
This writes any changes you have made to the object back to disk. If you do not
call commit, none of your changes will be reflected in the file you are
modifying. Commit may not be called on files opened in read-only mode. There
are some optional parameters that may be provided; these are passed in the
form of key => value pairs. The "backup" option allows you to
specify a file extension that will be used to save a backup of the original
file. The "writeopts" option passes module-specific options through
to the write method. It will accept any scalar for its value; typically this
will be a list or hash reference. Commit returns 1 on success and 0 on
failure.
This method encrypts the supplied plaintext password using a random salt and
returns the encrypted password. Note that this method does not actually make
any use of the object that it is invoked on, and could be called as a class
method.
The new method constructs a new ConfigFile (or subclass) object using the
specified FILENAME. There are several optional parameters that may be
specified. Options must be passed as keyed pairs in the form of option =>
value. Valid options are "locking", "lockfile",
"mode", and "readopts". The locking option determines what
style of file locking is used; available styles are "dotlock",
"flock", and "none". The default locking style is
"dotlock". The "none" locking style causes no locking to
be done, and all lock and unlock requests will return success. The lockfile
option can be used to specify the lock filename used with dotlocking. The
default is "FILENAME.lock", where FILENAME is the name of the file
being opened. The mode option allows the file open mode to be specified. The
default mode is "r+" (read/write), but "r" and
"w" are accepted as well. Finally, the readopts option allows
module-specific options to be passed through to the read method. It will
accept any scalar for its value; typically this will be a list or hash
reference.
This is a utility function that may be called as an object or class method. As
the name suggests, this method is basically a version of the join function
that incorporates line wrapping. The specified list will be joined together,
with each list element separated by the specified delimiter. The first line of
output will be prefixed with the HEAD parameter. If a line exceeds the length
parameter, output is wrapped to the next line and the INDENT parameter is used
to prefix the line. In addition, the TAIL parameter will be added to the end
of every line generated except the final one. There is one case where the
resulting string can exceed the specified line length - if a single list
element, plus HEAD or INDENT, exceeds that length. One final feature is that
if the HEAD or INDENT parameters contain the text '%n', it will be replaced
with the current line number, beginning at 0.
Returns the current sequence list associated with the object. This is a list of
arbitrary data maintained by a ConfigFile submodule. The ConfigFile module
does not care what is contained in the list.
Appends that specified data to the end of the sequence list.
Inserts the data into the sequence list before the data that matches the
specified key.
Removes the data from the sequence list that matches the specified key.
Steve Snodgrass, ssnodgra@fore.com
Unix::AliasFile, Unix::AutomountFile, Unix::GroupFile, Unix::PasswdFile
Visit the GSP FreeBSD Man Page Interface. Output converted with ManDoc. |