File::Signature - Detect changes to a file's content or attributes.
use File::Signature; my $sig = File::Signature->new('/some/file'); # If you have a stringified signature stored in $string # you can create a File::Signature object from it. my $sig = File::Signature->new_from_string($string); if (my $err = $sig->error) { warn $err, "\n"; } # You can use a signature object to re-check the same file. if ( $sig->is_same() ) { print "Ok. The signature is the same.\n" } if ( $sig->changed() ) { print "Uh Oh! The signature has changed.\n" } my @digests = $sig->old_and_new('digest'); my @inodes = $sig->old_and_new('ino'); my @modes = $sig->old_and_new('mode'); my @uid = $sig->old_and_new('uid'); my @gid = $sig->old_and_new('gid'); my @mtime = $sig->old_and_new('mtime'); # A slightly more worthwhile use... my @fields = $sig->changed(); for my $field (@fields) { printf "$field was: %s but changed to %s.\n", $sig->old_and_new($field); }
This perl library uses perl5 objects to assist in determining whether a file's contents or attributes have changed. It maintains several pieces of information about the file: a digest (currently only MD5 is supported), its inode number, its mode, the uid of its owner, the gid of its group owner, and its last modification time. A File::Signature object is closely associated with a single pathname. It provides a way to compare the state of a file over different points in time; it isn't useful for comparing different files.
This module provides a way to monitor files for changes. It implements an object oriented interface to file "signatures." In the case of this module, a signature includes an MD5 digest (other digests may be added later), the file's size, its inode number, its mode, its owner's uid, its group's gid, and its mtime. This information is associated with a file by the file's "pathname." The pathname is considered to be the file's unique identifier. In reality, a file may have more than one pathname, but this module doesn't recognize that. It will simply treat two differing pathnames as two different files, even if they refer to the same file.
As this module checks whether a file changes over time, a minimal use of it would include the time when the signature was created and a different time when the signature is regenerated and compared with the previous one. The amount of time between these checks is arbitrary. This module makes it easy to save a signature object and then load it and check for consistency at a later time, whether seconds or years have passed.
This constructor requires a pathname argument. If one is not provided, it will throw an exception (i.e. croak.) If the pathname cannot be stat()'d or if it cannot be read, the object returned will hold an error accessible via the error() instance method. The pathname should be absolute and, if it isn't it well be resolved to an absolute pathname unless the "allow_relative_paths" configure option is provided. See "configure()" below.
This constructor takes a single argument, a previously stringified signature object, and returns a new signature object created from the string.
If there was a non-fatal error when the object was constructed or when the last check was performed, a signature error object is returned instead. This method determines whether the object is an error object. It returns false if it isn't and a true value if it is. The true value in that case will be a human readable error message in scalar context or, in list context, list containing a "failure" message, the pathname, and an optional system error message.
Updates the signature and checks whether it is the same. It returns true if it is and false if it isn't. It will throw an exception (i.e. croak) if the current signature object reports an error.
Updates the signature and checks whether it is has changed. It returns true if it has and false if it hasn't. It will throw an exception (i.e. croak) if the current signature object reports an error.
This method requires a fieldname to be passes as a string. It returns a two-element list consisting of the previous and current value for the field with the supplied fieldname. If the fieldname is not recognized, it will return undef. This is used primarily to determine what has changed once a change has been detected with is_same() or changed(). The currently accepted fieldnames are any of qw( digest ino mode uid gid size mtime pathname ). Note that the old and new pathname fields should always be the same.
This is used to configure special behavior for all instances. The options are passes as hash where the keys are option names and the values are the desired settings. The following keys are recognized:
This key may be either 'bin', 'hex', or 'b64' and will determine whether the digest will be stored as a binary string, a string of hexadecimals, or a base64 encoded string. The default is 'hex', but that should not be relied upon as it may change in the future. An unrecognized value will result in a binary string representation just as if 'bin' had been the value. If a binary string is used, the "stringify_separator" should not be changed from "\0"!
A true value for this key will result in relative paths being permitted as the pathname for signature objects. Usually, when a relative pathname is given in a call to the new() constructor, the absolute path is determined. This option disables that behavior. Changing this option is NOT RECOMMENDED.
This option changes the field separator that is used when a signature object is stringified. By default this separator is a null ("\0"). It can be changed to any string but the string used must never appear in any of the fields. This includes the fields of signature error objects which sometimes contain system generated error messages. For example, colons and forward slashes are bad choices. Changing this option is NOT RECOMMENDED.
This is a list of all exceptions that thrown by File::Signature:
Thrown by configure() and new_from_string() when called with no arguments.
Thrown by configure() when called with an odd number of arguments. (It is to be called with a hash.)
Thrown by new_from_string() when called with an empty string.
Thrown by new_from_string() when something that looks like a stringified error object results in the wrong number of fields.
Thrown by new_from_string() when something that looks like a stringified signature object results in the wrong number of fields.
Thrown by new() when called without an argument.
Thrown by new() when called without a null string as an argument.
Thrown by is_same(), changed(), and old_and_new() when called on an error object.
None.
$Log: Signature.pm,v $ Revision 1.9 2003/08/12 19:53:03 jeremy Fixups to tests. Revision 1.8 2003/08/11 16:53:41 jeremy Fixed bad POD. Revision 1.7 2003/06/13 03:58:32 jeremy Bug fixes, doc updates, minor changes. Revision 1.6 2003/06/12 02:49:37 jeremy _throw_exception() fixed. Additional error states handled in constructors. Revision 1.5 2003/06/10 22:03:11 jeremy POD updates. Revision 1.4 2003/06/08 12:59:25 jeremy POD changes. Revision 1.3 2003/06/08 12:36:24 jeremy More minor prepping for RCS. Revision 1.2 2003/06/08 12:33:38 jeremy Minor touch-ups for RCS prepping.
"stat" in perlfunc, MD5::Digest, stat(2)
Mention other useful documentation such as the documentation of related modules or operating system documentation (such as man pages in UNIX), or any relevant external documentation such as RFCs or standards.
Jeremy Madea, <jdm@pobox.com>
Copyright (C) 2003 by Jeremy Madea. All rights reserved.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install File::Signature, copy and paste the appropriate command in to your terminal.
cpanm
cpanm File::Signature
CPAN shell
perl -MCPAN -e shell install File::Signature
For more information on module installation, please visit the detailed CPAN module installation guide.