CRYPT_FILE(1) User Contributed Perl Documentation CRYPT_FILE(1)NAMEcrypt_file - Encrypt (and decrypt) Perl files
SYNOPSIScrypt_file [--list-file=<file>]
[--dir=<dir>]... [--recurse]
[--test] [--silent]
[--in-place] [--edit-mode=<mode>] [--bak-file-expr[=<expr>]]
[--out-file-expr=<expr>]
[--crypt-mode=<mode>]
[--version] [--help] [--manpage]
[<file-spec>...]
ARGUMENTS
<file-spec>
Specify one or more files on which to perform the encryption or
decryption. Each file specifier may be one of:
· An absolute file path;
· A relative file path;
· A shell-style file glob expression.
This list of file specifiers, together with any more read from the
file specified by the --list-file option (if present), is used to
build the input file list as follows:
· Each absolute file path is added directly to the input file
list;
· Each relative file path is tested against each directory in the
search directory list in turn until the first existing file
path is found, which is then added to the input file list;
· Each file glob expression is expanded against every directory
in the search directory list in turn, and all the resulting
file paths are then added to the input file list.
Note that typical UNIX shells will expand glob expressions
before calling the program unless the expressions are quoted
(normally with single quotes). The default Win32 cmd.exe shell
does not do this, and does not remove single quotes from
arguments either, so beware!
By default, the search directory list is just the current working
directory, but other directories may be specified instead by using
one or more --dir options.
If there are no file specifiers given, or if there is a single input
file specifier consisting of just a single dash given, then input is
read from <STDIN> instead.
OPTIONS-l <file>, --list-file=<file>
Specify a file that lists file specifiers to use in building the
input file list (one file specifier per line).
This file may be used as well as, or instead of, file specifiers
given as arguments to this script.
See "ARGUMENTS" for more details on file specifiers.
-d <dir>, --dir=<dir>
Specify one or more directories to assign to the search directory
list that is used to resolve relative file paths and/or expand file
glob expressions in the list of input file specifiers.
Multiple directories can be assigned to the list by specifying
multiple --dir options and/or specifying multiple directories
separated by the path separator character with a single --dir
option.
To determine what the path separator character is on your system
type the following:
perl -V:path_sep
By default, the search directory list is just the current working
directory. If one or more directories are specified via this
option then they replace the default, so if you want to include the
current working directory as well as other directories then you
will have to explicitly specify that too.
-r, --recurse
Specify that when expanding any file glob expressions in the list
of input file specifiers, each glob should be expanded in all sub-
directories (recursively) of each directory in the search directory
list.
This option does not affect the resolution of relative file paths
in the list of input file specifiers.
-t, --test
Run the script in test-only mode.
The input file list will be printed to "STDOUT", but no other
action is taken. No input files are edited, and no backup files or
output files are created.
-s, --silent
Run the script in silent mode.
The name of each input file is normally printed on "STDERR" before
it is processed, followed by an "OK" message (and/or a warning or
error message if anything went wrong) when the processing of that
file is complete. Running in silent mode suppresses the output of
the filename and "OK" message; any relevant warnings and/or error
messages are still output.
-i, --in-place
Specify that each input file should be processed "in-place", i.e.
the input file is overwritten with the output, rather than the
output being sent either to "STDOUT" or else to an output file as
specified by the --out-file-expr option.
This option is ignored if the input file list is empty and input is
being read from "STDIN" instead.
-e <mode>, --edit-mode=<mode>
Specify how in-place editing should be performed:
memory
The entire contents of the input file are read into memory,
processed in memory, and then written back out to the input
file.
tempfile
The contents of the input file are processed and written out to
a temporary file in chunks of at most "BUFSIZ" bytes at a time,
and then the temporary file is renamed to the input file.
The default mode is "memory", which should be safe for most
purposes given that Perl source code files are typically not very
large, but the "tempfile" mode should be considered instead if this
is likely to cause out-of-memory errors due to the size of the
files, e.g. if the files have very large "__DATA__" sections.
The "tempfile" mode also has another useful advantage when combined
with the "encrypted" or "decrypted" --crypt-mode option values:
The file processing becomes safely re-runnable in the event of any
errors on a first run because each input file is not touched until
the final step in its processing when the temporary file that has
been used up until then is renamed to it. Renaming a file is
normally an atomic operation at the filesystem level, so even if
the processing is interrupted or killed part-way through, each
input file will be left either untouched or else fully encrypted or
decrypted; there will be no partially written files left (other
than temporary files, which are cleaned up if at all possible).
Combined with, say, --crypt-mode=encrypted, this mode can therefore
safely be used to run, and, if necessary, re-run, on a set of input
files until they have all be successfully encrypted.
This option only applies when input files are being processed "in-
place", and implies the --in-place option if that is not already
present.
-b [<expr>], --bak-file-expr[=<expr>]
Specify an expression from which to determine the name of a backup
file to create before processing each input file.
The optional expr value works in a similar way to the value for
perl's own -i option, with a couple of enhancements:
· If the expr contains one or more "*", "?" or "[" characters
then
· Each "*" character is replaced with the input file's
basename (i.e. with the directory path removed from the
start);
· Each "?" character is replaced with the input file's
basename minus the extension (i.e. the same as the basename
used above, but with whatever matches "/\..*?$/" removed
from the end);
· Each "[" character is replaced with the input file's
extension (i.e. the part that was removed from the basename
above).
The resulting expression is then used as the name of the backup
file.
· Otherwise, the expr is appended to the input filename to make
the name of the backup file.
In each case, the backup file is created in the same directory as
the input file itself.
The default expr value is "*.bak".
This option only applies when input files are being processed "in-
place", and implies the --in-place option if that is not already
present.
-o <expr>, --out-file-expr=<expr>
Specify an expression from which to determine the name of an output
file to send the output to when processing each input file.
The mandatory expr value works in exactly the same way as the expr
value to the --bak-file-expr option described above, except that if
the input file list is empty and input is being read from "STDIN"
instead then the expr is used as the actual path (either absolute
or relative to the current directory) of the output file itself.
This option is mutually exclusive with the --in-place option; if
both options are specified then --in-place will be used and
--out-file-expr is ignored.
The output is written to "STDOUT" by default.
-c <mode>, --crypt-mode=<mode>
Specify what action, if any, to perform on each file:
auto
The crypt mode is determined automatically on a per-file basis
by reading the beginning of the file. If the beginning is
use Filter::Crypto::Decrypt;
then the file is presumed to be in an encrypted state already
so the mode will be set to "decrypt"; otherwise the mode will
be set to "encrypt".
encrypt
Each input file is encrypted. Produces a warning if a file
looks like it is already in an encrypted state, i.e. already
begins with a "use Filter::Crypto::Decrypt;" statement.
decrypt
Each input file is decrypted. Produces a warning if a file
looks like it is already in a decrypted state, i.e. does not
begin with a "use Filter::Crypto::Decrypt;" statement.
encrypted
Each input file is encrypted unless it looks like it is already
in an encrypted state, i.e. already begins with a "use
Filter::Crypto::Decrypt;" statement.
decrypted
Each input file is decrypted unless it looks like it is already
in a decrypted state, i.e. does not begin with a "use
Filter::Crypto::Decrypt;" statement.
The default mode is "auto".
-v, --version
Display the script name and version, and then exit.
-h, --help | --?
Display a help page listing the arguments and options, and then
exit.
-m, --manpage | --doc
Display the entire manual page, and then exit.
Options may be introduced with a double dash, a single dash, a plus
sign or (on Win32) a forward slash; case does not matter; an equals
sign may be used or omitted between option names and values; long
option names may be abbreviated to uniqueness.
Options may also be placed between non-option arguments, and option
processing may be stopped at any point in the command-line by inserting
a double dash.
EXIT STATUS
0 The script exited normally.
1 The script exited after printing the version, help or manpage.
2 Invalid command-line arguments.
>2 An error occurred.
DIAGNOSTICS
Warnings and Error Messages
This script may produce the following diagnostic messages. They are
classified as follows (a la perldiag):
(W) A warning (optional).
(F) A fatal error (trappable).
(I) An internal error that you should never see (trappable).
Warnings of the format "%s: Error: ..." and "%s: Warning: ..." are
produced from within the main loop over the input file list. Those
that say "Error:" are severe warnings that result in the processing of
the specified input file to be aborted; in such cases, the script moves
onto the next file in the list. Those that say "Warning:" are less
serious warnings; in those cases, the script continues the processing
of the file concerned. Other messages come from elsewhere in the
script.
Can't cd back to '%s': %s
(F) Could not change back to the specified directory after changing
into one of its sub-directories during a (possibly recursive) scan
of the search directory list while attempting to expand a file glob
expression in the list of input file specifiers. The system error
message corresponding to the standard C library "errno" variable is
also given.
Can't cd to '%s' from '%s': %s
(W) Could not change directory as indicated during a (possibly
recursive) scan of the search directory list while attempting to
expand a file glob expression in the list of input file specifiers.
The search down that particular branch of the directory tree will
be aborted, but other branches and search directories will continue
to be scanned. The system error message corresponding to the
standard C library "errno" variable is also given.
Can't close list file '%s' after reading: %s
(W) The specified list file (i.e. the file given by the --list-file
option) could not be closed after reading the list of input file
specifiers from it. The system error message corresponding to the
standard C library "errno" variable is also given.
Can't close temporary file '%s': %s
(W) The specified temporary file could not be closed during the
clean up of temporary files just before exiting when a SIGINT has
been caught. The system error message corresponding to the
standard C library "errno" variable is also given.
Can't delete temporary file '%s': %s
(W) The specified temporary file could not be deleted during the
clean up of temporary files just before exiting when a SIGINT has
been caught, or when removing an unneeded temporary file when an
input file was found to already be in the requested state. The
system error message corresponding to the standard C library
"errno" variable is also given.
Can't open list file '%s' for reading: %s
(F) The specified list file (i.e. the file given by the --list-file
option) from which to read the list of input file specifiers could
not be opened for reading. The system error message corresponding
to the standard C library "errno" variable is also given.
Caught SIGINT. Cleaning up temporary files before exiting
(W) The script has received an "interrupt" signal, e.g. the user
may have pressed Ctrl+C. The signal is caught so that temporary
files, used when editing files in-place with --edit-mode=tempfile,
can be cleaned up before exiting.
%s: Error: Can't copy to backup file '%s': %s
(W) The specified input file could not be copied to the specified
backup file. The system error message corresponding to the
standard C library "errno" variable is also given.
%s: Error: Can't make file writable: %s
(W) [Win32 only.] The specified input file could not be made
writable. On Win32 (only), the input file must be writable when
editing files in-place using temporary files in order for the final
step (in which the temporary file is renamed to the input file) to
succeed. (On other systems, the ability to perform a rename is
controlled by the permissions on the parent directory.) The system
error message corresponding to the standard C library "errno"
variable is also given.
%s: Error: Can't rename temporary file '%s' to input file: %s
(W) The specified temporary file could not be renamed to the
specified input file. This is the final step of the process when
editing files in-place using temporary files. The system error
message corresponding to the standard C library "errno" variable is
also given.
%s: Error: Can't stat file: %s
(W) Could not retrieve file information about the specified input
file. This information is required when editing files in-place
using temporary files in order to set the same file permissions on
the temporary file as are on the input file before renaming the
temporary file to the input file. The system error message
corresponding to the standard C library "errno" variable is also
given.
%s: Error: crypt_file() failed: %s
(W) The call to the "crypt_file()" function to perform the actual
encryption or decryption failed. The last error message from the
Filter::Crypto::CryptFile module is also given.
No such file '%s'
(W) The specified input file specifier could not be resolved,
either as an absolute file path, or as a relative file path or a
file glob expression with respect to the current working directory
or any of the directories specified with the --dir option.
Unknown edit mode '%s'
(I) The mode specified for editing files in-place (i.e. the mode
given by the --edit-mode option) was not recognized and was not
caught by the option processing code run at the start of the
script, causing an unexpected error later on.
Unknown warning type '%s'
(I) The subroutine called internally when outputting warning
messages was passed a warning type that it does not recognize.
%s: Warning: Can't close temporary file '%s' after writing: %s
(W) The filehandle opened on the temporary file being used to edit
the specified input file in-place could not be closed after writing
data to it. The system error message corresponding to the standard
C library "errno" variable is also given.
%s: Warning: Can't set permissions on temporary file '%s': %s
(W) Could not set the file permissions on the temporary file to be
the same as are on the specified input file. This is done when
editing files in-place using temporary files so that the file
permissions are left unchanged after the editing has been
completed. The system error message corresponding to the standard
C library "errno" variable is also given.
EXAMPLES
These examples assume standard UNIX shell quoting and redirection
syntax apply. On Win32, you should replace single-quoted arguments
with double-quoted arguments. (The redirection syntax is unchanged.)
Process test.pl, writing output to testenc.pl:
crypt_file <test.pl >testenc.pl
crypt_file test.pl >testenc.pl
crypt_file-o '?enc.pl' test.pl
Process test.pl in-place, making a backup copy as test.pl.bak:
crypt_file-i -b '*.bak' test.pl
Process test.pl in-place, with no backup copy:
crypt_file-i test.pl
Process all *.pl files within /tmp and all sub-directories in-place:
crypt_file-i -d /tmp -r '*.pl'
ENVIRONMENT
PERL_CRYPT_FILE_OPTS
Specify options to be prepended to the list of command-line options
before the option processing takes place.
Note that as far as quoting and escaping is concerned, the
environment variable value is interpreted in the same way as the
Bourne shell would interpret the corresponding command-line.
SEE ALSO
Filter::Crypto, Filter::Crypto::CryptFile.
AUTHOR
Steve Hay <shay@cpan.org>
COPYRIGHT
Copyright (C) 2004-2006, 2012, 2014 Steve Hay. All rights reserved.
LICENCE
This script is free software; you can redistribute it and/or modify it
under the same terms as Perl itself, i.e. under the terms of either the
GNU General Public License or the Artistic License, as specified in the
LICENCE file.
VERSION
Version 2.07
DATE
28 Feb 2015
HISTORY
See the Changes file.
perl v5.20.2 2015-02-28 CRYPT_FILE(1)
