Author image Karthik Krishnamurthy


Unix::Conf::ConfIO - This is an internal module for handling line at a time I/O for configuration files, with caching, locking and security support.


Open a configuration file and get a Unix::Conf::ConfIO object.

    use Unix::Conf;

    my $conf = Unix::Conf->_open_conf (
        NAME            => 'some_file',
        SECURE_OPEN     => 1,
        LOCK_STYLE      => 'dotlock',
    $conf->die ('DEAD') unless ($conf);

    # use the file in various ways
    print while (<$conf>);
    $conf->setline (10, "this is the 11th line\n");
    $conf->close ();


ConfIO is designed to be a class for handling I/O for configuration files with support for locking and security. At the time of creation all the data in the file is read in and stored in an array, where each line is assumed to be one line of the file. It is the responsibility of the user to ensure that while appending or setting lines, the data ends in a newline. While this is not enforced it could cause the lineno counter to get confused.

open ()
    NAME        => 'PATHNAME',
        FH                      => filehandle                   # filehandle, reference to a filehandle
    MODE        => FILE_OPEN_MODE,      # default is O_RDWR | O_CREAT
    PERMS       => FILE_CREATION_PERMS, # default is 0600
    LOCK_STYLE  => 'flock'/'dotlock',   # default is 'flock'
    SECURE_OPEN => 0/1,                 # default is 0 (disabled)
    PERSIST     => 0/1,                 # default is 0 (disabled)

Class constructor. Creates a ConfIO object which is associated with the file. Releasing the object automatically syncs with the disk version of the file. Passing an open filehandle with FH creates a Unix::Conf::ConfIO object representing the open file. Take care to open FH in both read & write mode, because Unix::Conf::ConfIO reads in the whole file into an in core array as of now. MODE and PERMS are the same as for sysopen. LOCK_STYLE is for choosing between different locking methods. 'dotlock' is used for locking '/etc/passwd', '/etc/shadow', '/etc/group', '/etc/gshadow'. 'flock' is the default locking style. If the value of SECURE_OPEN is 1, it enables a check to see if PATHNAME is secure. PERSIST is used to keep files open till release () or release_all () is called even though the object may go out of scope in the calling code. It reduces the overhead of managing ancillary files. Otherwise the file locks associated with the file would be released for these anciallary files. TODO: Need to implement ability to accept open filehandles, IO::Handle, IO::File objects too. NOTE: This method should not be used directly. Instead use Unix::Conf::_open_conf () which has the same syntax.

    use Unix::Conf;
    my $conf;
    $conf = Unix::Conf->_open_conf (
        NAME                    => '/etc/passwd',
        SECURE_OPEN             => 1,
        LOCK_STYLE              => 'dotlock',
    ) or $conf->die ("Could not open '/etc/passwd'");

        # or attach a filehandle to a Unix::Conf object.
    $conf = Unix::Conf->_open_conf (
                FH                              => FH,          # or any object that represents an open filehandle
    ) or $conf->die ("Could not attach FH");
close ()

Object method. Syncs the cache to disk and releases the lock on the file unless the file was opened with PERSIST enabled. However the cache of data is maintained in the hope that it will still be useful and obviate the necessity for a read of all the data. Returns true or an Err object in case of error.

release ()

Object method. Closes the file and releases the lock if opened with PERSIST. Returns true or an Err object in case of error.

release_all ()

Class method. Closes all files opened with PERSIST by a specific class. This can be called from the destructor for that class, allowing hassle free operation for ancillary files. Returns true or an Err object in case of error.

dirty ()

Object method. Mark the file cache as dirty explicitly.

name ()

Object method. Returns the name of the associated file.

rewind ()

Object method. Rewind the file to the beginning of the data.

next_lineno ()

Object method. Returns max lineno + 1.

set_scalar ()

Object method. Pass reference to a scalar. The file data will be set to the value of the scalar. Returns true.

getlines ()

Object method. Returns reference to the cache array. NOTE: If the caller then changes the array in anyway it is his/her responsibility to mark the cache as dirty.

setlines ()

Object method. Store the array referenced by ARRAY_REF as the file cache. It is assumed that each element of the file will be a line of data with a trailing newline, though it is not a necessity. Returns true or an Err object in case of error.

delete ()

Object method. Delete all lines in the file. Returns true or an Err object in case of error.

lineno ()

Object method. Get/set the current lineno of the ConfIO object.

getline ()

Object method. Returns the next line.

setline ()

Object method. Set LINENO to value of SCALAR. Returns true or an Err object in case of error.

append ()

Object method. Append LIST to the end of the file. Returns true or an Err object in case of error.

delete_lines ()

Object method. Delete from START_LINENO to END_LINENO including. Returns true or an Err object in case of error.

ungetline ()

Object method. Rewind the current lineno pointer. Returns true.




This module should accept a scalar representing a file too.


None that I know of.


This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with the program; if not, write to the Free Software Foundation, Inc. :

59 Temple Place, Suite 330, Boston, MA 02111-1307


Copyright (c) 2002, Karthik Krishnamurthy <>.

1 POD Error

The following errors were encountered while parsing the POD:

Around line 772:

You forgot a '=back' before '=head1'