Amanda::Util - Runtime support for Amanda applications
Application initialization generally looks like this:
use Amanda::Config qw( :init ); use Amanda::Util qw( :constants ); use Amanda::Debug;
Amanda::Util::setup_application("myapp", "server", $CONTEXT_CMDLINE);
# .. command-line processing ..
Amanda::Config::config_init(...);
Amanda::Util::finish_setup($RUNNING_AS_DUMPUSER);
# ..
Amanda::Util::finish_application();
Set up the operating environment for an application, without requiring any configuration.
$name is the name of the application, used in log messages, etc.
$type is usualy one of "server" or "client". It specifies the
subdirectory in which debug logfiles will be created. $context
indicates the usual manner in which this application is invoked; one
of $CONTEXT_CMDLINE for a user-invoked command-line utility (e.g.,
amadmin) which should send human-readable error messages to stderr;
$CONTEXT_DAEMON for a program started by amandad, e.g.,
sendbackup; or $CONTEXT_SCRIPTUTIL for a small program used from
shell scripts, e.g., amgetconf
Based on $type and $context, this function does the following:
sets up debug logging;
configures internationalization
sets the umask;
sets the current working directory to the debug or temporary directory;
closes any unnecessary file descriptors as a security meaasure;
ignores SIGPIPE; and
sets the appropriate target for error messages.
finish_setup($running_as_flags)Perform final initialization tasks that require a loaded configuration. Specifically, move the debug log into a configuration-specific subdirectory, and check that the current userid is appropriate for this applciation.
The user is specified by one of the following flags, which are
available in export tag :check_running_as_flags:
$RUNNING_AS_ANY # any user is OK $RUNNING_AS_ROOT # root $RUNNING_AS_DUMPUSER # dumpuser, from configuration $RUNNING_AS_DUMPUSER_PREFERRED # dumpuser, but client_login is OK too $RUNNING_AS_CLIENT_LOGIN # client_login (--with-user at build time)
If the flag $RUNNING_AS_UID_ONLY is bit-or'd into
$running_as_flags, then the euid is ignored; this is used for
programs that expect to be setuid-root.
finish_application()Remove old debug files. All applications should call this before exiting.
get_original_cwd()Return the original current directory with get_original_cwd.
version_opt()Print the version and exit. This is intended to be used in GetOptions invocations, e.g.,
GetOptions(
# ...
'version' => \&Amanda::Util::version_opt,
);
These functions read and write the entire requested size to a file descriptor, even if the underlying syscall returns early. Note that they do not operate on Perl file handles.
If fewer than $size bytes are written, full_write returns the
number of bytes actually written and sets $! appropriately. When
reading, if fewer than $size bytes are read due to a normal EOF,
then $! is zero; otherwise, it contains the appropriate error
message.
Unlike POSIX::read, full_read returns a scalar containing the
bytes it read from the file descriptor.
safe_env()Return a "safe" environment hash. For non-setuid programs, this means filtering out any localization variables.
This is a wrapper around the Gnulib function of the same name. On success, it returns a hash with keys:
blocksize Size of a block blocks Total blocks on disk bfree Free blocks available to superuser bavail Free blocks available to non-superuser bavail_top_bit_set 1 if fsu_bavail represents a value < 0 files Total file nodes ffree Free file nodes
On failure, it returns nothing, and $! should be set. If $! is 0, then
this is a system which cannot measure usage without a disk argument, which
this wrapper does not support.
Return 1 is the process with that pid is still alive.
weaken_ref($ref)This is exactly the same as Scalar::Util::weaken, but available in all
supported versions of perl.
gettimeofday()Return the number of microseconds since the UNIX epoch.
fsync($fd)Invoke the fsync syscall.
Set or clear the O_NONBLOCK fd flag on $fd; returns a negative value on
failure, or 0 on success.
openbsd_fd_inform()Due to a particularly poor user-space implementation of threading on OpenBSD, executables that are run with nonstandard file descriptors open (fd > 2) find those descriptors to be in a nonblocking state. This particularly affects amandad services, which begin with several file descriptors in the 50's open.
This function "informs" the C library about these descriptors by making an
fcntl(fd, F_GETFL) call. This is otherwise harmless, and is only perfomed
on OpenBSD.
built_with_component($comp)Returns true if Amanda was built with the given component. Component names are
in config/amanda/components.m4.
These are thin wrappers over functions in common-src/stream.h and other related
functions.
my $family = $Amanda::Util::AF_INET;
my $bufsize = $Amanda::Util::STREAM_BUFSIZE;
my ($listensock, $port) = Amanda::Util::stream_server(
$family, $bufsize, $bufsize, $priv);
This function creates a new socket and binds it to a port, returning both the
socket and port. If the socket is -1, then an error occurred and is available
in $!. The constants $AF_INET and $STREAM_BUFSIZE are universally
used when calling this function. If the final argument, $priv, is true,
then a the function opens a privileged port (below 1024).
my $sock = Amanda::Util::stream_accept(
$listen_sock, $timeout, $bufsize, $bufsize);
This function accepts a connection on a listening socket. If the connection is
not made within $timeout seconds, or some other error occurs, then the
function returns -1. The bufsize arguments are applied to the new socket.
my $ok = Amanda::Util::check_security($socket, $userstr);
This function takes a socket descriptor and a string of the form "USER foo"
and performs BSD-style checks on that descriptor. These include verifying
round-trip DNS sanity; check that the user is in .rhosts or .amandahosts,
and checking that the remote port is reserved. Returns an error string on
error, or undef on success.
quote_string($str)Quote a string using Amanda's quoting algorithm. Strings with no
whitespace, control, or quote characters are returned unchanged. An
empty string is represented as the two-character string "".
Otherwise, tab, newline, carriage return, form-feed, backslash, and
double-quote (") characters are escaped with a backslash and the
string is surrounded by double quotes.
unquote_string($str)Unquote a string as quoted with quote_string.
skip_quoted_string($str)my($q, $remaider) = skip_quoted_string($str)
Return the first quoted string and the remainder of the string, as separated by
any whitespace. Note that the remainder of the string does not include the
single separating whitespace character, but will include any subsequent
whitespace. The $q is not unquoted.
split_quoted_strings($str)Split string on unquoted whitespace. Multiple consecutive spaces are not
collapsed into a single space: "x y" (with two spaces) parses as ( "x",
"", "y"). The strings are unquoted before they are returned. An empty string
is split into ( "" ). This method is generally used for parsing IPC messages,
where blank space is significant and well-controlled.
split_quoted_strings_friendly($str)Similar to split_quoted_strings, but intended for user-friendly uses. In
particular, this function treats any sequence of zero or more whitespace
characters as a separator, rather than the more strict interpretation applied
by split_quoted_strings. All of the strings are unquoted.
All of these quoting-related functions are available under the export
tag :quoting.
hexencode($str)Encode a string using URI-style hexadecimal encoding. Non-alphanumeric characters will be replaced with "%xx" where "xx" is the two-digit hexadecimal representation of the character.
hexdecode($str)Decode a string using URI-style hexadecimal encoding.
Both hexencode and hexdecode are available under the export tag :encoding
expand_braced_alternates($str)
=item collapse_braced_alternates(\@list)These two functions handle "braced alternates", which is a syntax borrowed, partially, from shells. Comma-separated strings enclosed in curly braces expand into multiple alternatives for the entire string. For example:
"{foo,bar,bat}" [ "foo", "bar", "bat" ]
"foo{1,2}bar" [ "foo1bar", "foo2bar" ]
"foo{1\,2,3}bar" [ "foo1,2bar", "foo3bar" ]
"{a,b}-{1,2}" [ "a-1", "a-2", "b-1", "b-2" ]
Note that nested braces are not processed. Braces, commas, and backslashes may be escaped with backslashes.
As a special case for numeric ranges, if the braces contain only digits followed by two dots followed by more digits, and the digits sort in the correct order, then they will be treated as a sequence. If the first number in the sequence has leading zeroes, then all generated numbers will have that length, padded with leading zeroes.
"tape-{01..10}" [ "tape-01", "tape-02", "tape-03", "tape-04",
"tape-05", "tape-06", "tape-07", "tape-08",
"tape-09", "tape-10" ]
On error, expand_braced_altnerates returns undef. These two functions are
available in the export tag :alternates.
generate_timestamp()Generate a timestamp from the current time, obeying the 'USETIMESTAMPS' config parameter. The Amanda configuration must already be loaded.
sanitise_filename($fn)"Santitises" a filename by replacing any characters that might have special meaning to a filesystem with underscores. This operation is not reversible, and distinct input filenames may produce identical output filenames.
unmarshal_tapespec($tapespec)
=item marshal_tapespec($filelist)These functions convert between a tapespec -- formerly, and confusingly, called a "tapelist" -- and a perl data structure like
[ $label1 => [ $filenum1, $filenum2, .. ],
$label2 => [ $filenum1, $filenum2, .. ],
]
Note that a non-tapespec $string will be unmarshalled as [ $string, [] ].
Amanda provides a basic mechanism to lock a file and read its contents. This uses operating-system facilities to acquire an advisory lock, so non-Amanda applications are not prevented from modifying the file while it is locked.
To create a lock object, call the file_lock constructor, passing the
filename to lock:
my $fl = Amanda::Util::file_lock->new($filename)
then, three ways to lock the file:
$fl->lock_wr(); # take a write lock (exclusive)
$fl->lock_rd(); # take a read lock
$fl->lock(); # take a write lock and reads the contents of
# the file into memory.
they return -1 on failure, 0 if the lock is taken or 1 if the lock in not taken (you can retry later).
to access the data in memory
my $state = $fl->data();
to change the file contents, call write:
$fl->write($new_contents);
and unlock the lock with
$fl->unlock();
Note that the file will be automatically unlocked if the file_lock object is
garbage-collected.
For reading small files directly into memory with little code
overhead, we can use slurp.
my $data = slurp $filename;
After processing the data, we can write it back to file with burp. This
function always completely overwrites the file.
burp $filename, $header;
These functions can (and should) be exported to the main namespace
The following functions are available to match strings against patterns using the rules described in amanda(8):
match_host($pat, $str); match_disk($pat, $str); match_datestamp($pat, $str); match_level($pat, $str);
This page was automatically generated Tue Feb 21 19:14:01 2012 from the Amanda source tree, and documents the most recent development version of Amanda. For documentation specific to the version of Amanda on your system, use the 'perldoc' command.