NAME

Proc::PID::File - a module to manage process id files

SYNOPSIS

use Proc::PID::File;
$pf = Proc::PID::File->new();
die "Already running!" if $pf->alive();

DESCRIPTION

This Perl module is useful for writers of daemons and other processes that need to tell whether they are already running. The module manages *nix-style pidfiles, which are files that store a process identifier, and provides a simple interface for determining whether the program being run is already alive. A programmer can thus avoid running multiple instances of a daemon.

The module provides both an object-oriented interface, as well as a regular procedural function set.

OO Interface

The following methods are provided:

new [hash[-ref]]

This method is used to create an instance of the module. It automatically calls the ->file() method described below and receives the same paramters. For a listing of valid keys in this has please refer to the aforementioned method documentation below.

In addition to the above, the following constitute valid keys:

debug

Turns debugging output on.

file [hash[-ref]]

Use this method to set the path of the pidfile. The method receives an optional hash (or alternatively a hash reference) of options, which includes those listed below, from which it makes a path of the format: $dir/$name.pid.

dir Specifies the directory to place the pid file. If left unspecified, defaults to /var/run.

name Indicates the name of the current process. When not specified, defaults to basename($0).

alive

Returns true when the calling process is already running. Please note that this call must be made *after* daemonisation i.e. subsequent to the call to fork().

read

Returns the process id currently stored in the file set. If unable to open the file for read, the method die()s with an error message.

write

Causes for the current process id to be written to the set file. The process die()s upon failure to write to the file.

remove

This method is used to delete the pidfile and is automatically called by DESTROY method. It should thus be unnecessary to call it directly.

Procedural interface

The module can also export its functionality into the caller's namespace. The functions exported generally correspond to those in the OO interface but follow the naming format: pid_file_<name>.

As an exception, instead of calling ->new() the user will need to call pid_file_set before making any other calls.

- exempli gratia -

  use Proc::PID::File qw(:all);
  pid_file_set( dir => "/var/run", name => "mydaemon" );
  die "Already running!" if pid_file_alive();
	

AUTHOR

Erick Calder <ecalder@cpan.org>

ACKNOWLEDGEMENTS

1k thx to Steven Haryanto <steven@haryan.to> on whose original package (Proc::RID_File) this work is based.

LICENSE

Copyright (C) 2000-2002, All rights reserved.

This module is free software; you may redistribute it and/or modify it under the same terms as Perl itself.

CHANGES

$Log: File.pm,v $ Revision 1.2 2002/09/20 06:38:45 ekkis - ripped out the procedure interface, concentrating on oo - added modified PODs

cpanm Proc::PID::File

perl -MCPAN -e shell
install Proc::PID::File