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.
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.
Remove old debug files. All applications should call this before exiting.
Return the original current directory with get_original_cwd
.
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.
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.
This is exactly the same as Scalar::Util::weaken
, but available in all supported versions of perl.
Return the number of microseconds since the UNIX epoch.
Invoke the fsync
syscall.
Set or clear the O_NONBLOCK
fd flag on $fd; returns a negative value on failure, or 0 on success.
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.
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 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 a string as quoted with quote_string
.
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
.
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.
Decode a string using URI-style hexadecimal encoding.
Both hexencode
and hexdecode
are available under the export tag :encoding
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 a timestamp from the current time, obeying the 'USETIMESTAMPS' config parameter. The Amanda configuration must already be loaded.
"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.
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 Mar 19 07:08:17 2019 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.