Amanda modules list
List of All Modules
All Amanda Releases



Amanda::Util - Runtime support for Amanda applications

Application Initialization

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 ..
  # ..
setup_application($name, $type, $context)

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.,

    # ...
    'version' => \&Amanda::Util::version_opt,

File Handling

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.

full_read($fd, $size)
full_write($fd, $buf, $size)

Miscellaneous Utilities


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_blocking($fd, $blocking)

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.

TCP Utilities

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.

String Utilities


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 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.


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

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 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.

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, [] ].

Locking Files

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:


and unlock the lock with


Note that the file will be automatically unlocked if the file_lock object is garbage-collected.

Simple File Reading & Writing

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.