2 * Copyright (c) 2009-2012 Zmanda, Inc. All Rights Reserved.
4 * This program is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU General Public License
6 * as published by the Free Software Foundation; either version 2
7 * of the License, or (at your option) any later version.
9 * This program is distributed in the hope that it will be useful, but
10 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
11 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * You should have received a copy of the GNU General Public License along
15 * with this program; if not, write to the Free Software Foundation, Inc.,
16 * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
18 * Contact information: Zmanda Inc., 465 S. Mathilda Ave., Suite 300
19 * Sunnyvale, CA 94085, USA, or: http://www.zmanda.com
26 Amanda::Util - Runtime support for Amanda applications
28 =head1 Application Initialization
30 Application initialization generally looks like this:
32 use Amanda::Config qw( :init );
33 use Amanda::Util qw( :constants );
36 Amanda::Util::setup_application("myapp", "server", $CONTEXT_CMDLINE);
37 # .. command-line processing ..
38 Amanda::Config::config_init(...);
39 Amanda::Util::finish_setup($RUNNING_AS_DUMPUSER);
41 Amanda::Util::finish_application();
45 =item setup_application($name, $type, $context)
47 Set up the operating environment for an application, without requiring
50 C<$name> is the name of the application, used in log messages, etc.
51 C<$type> is usualy one of "server" or "client". It specifies the
52 subdirectory in which debug logfiles will be created. C<$context>
53 indicates the usual manner in which this application is invoked; one
54 of C<$CONTEXT_CMDLINE> for a user-invoked command-line utility (e.g.,
55 C<amadmin>) which should send human-readable error messages to stderr;
56 C<$CONTEXT_DAEMON> for a program started by C<amandad>, e.g.,
57 C<sendbackup>; or C<$CONTEXT_SCRIPTUTIL> for a small program used from
58 shell scripts, e.g., C<amgetconf>
60 Based on C<$type> and C<$context>, this function does the following:
66 sets up debug logging;
70 configures internationalization
78 sets the current working directory to the debug or temporary
83 closes any unnecessary file descriptors as a security meaasure;
87 ignores C<SIGPIPE>; and
91 sets the appropriate target for error messages.
95 =item finish_setup($running_as_flags)
97 Perform final initialization tasks that require a loaded
98 configuration. Specifically, move the debug log into a
99 configuration-specific subdirectory, and check that the current userid
100 is appropriate for this applciation.
102 The user is specified by one of the following flags, which are
103 available in export tag C<:check_running_as_flags>:
105 $RUNNING_AS_ANY # any user is OK
106 $RUNNING_AS_ROOT # root
107 $RUNNING_AS_DUMPUSER # dumpuser, from configuration
108 $RUNNING_AS_DUMPUSER_PREFERRED # dumpuser, but client_login is OK too
109 $RUNNING_AS_CLIENT_LOGIN # client_login (--with-user at build time)
111 If the flag C<$RUNNING_AS_UID_ONLY> is bit-or'd into
112 C<$running_as_flags>, then the euid is ignored; this is used for
113 programs that expect to be setuid-root.
115 =item finish_application()
117 Remove old debug files.
118 All applications should call this before exiting.
120 =item get_original_cwd()
122 Return the original current directory with C<get_original_cwd>.
126 Print the version and exit. This is intended to be used in C<GetOptions> invocations, e.g.,
130 'version' => \&Amanda::Util::version_opt,
137 These functions read and write the entire requested size to a file
138 descriptor, even if the underlying syscall returns early. Note that
139 they do not operate on Perl file handles.
141 If fewer than C<$size> bytes are written, C<full_write> returns the
142 number of bytes actually written and sets C<$!> appropriately. When
143 reading, if fewer than C<$size> bytes are read due to a normal EOF,
144 then C<$!> is zero; otherwise, it contains the appropriate error
147 Unlike C<POSIX::read>, C<full_read> returns a scalar containing the
148 bytes it read from the file descriptor.
152 =item full_read($fd, $size)
154 =item full_write($fd, $buf, $size)
158 =head1 Miscellaneous Utilities
164 Return a "safe" environment hash. For non-setuid programs, this means
165 filtering out any localization variables.
167 =item get_fs_usage(file)
169 This is a wrapper around the Gnulib function of the same name. On success, it returns
172 blocksize Size of a block
173 blocks Total blocks on disk
174 bfree Free blocks available to superuser
175 bavail Free blocks available to non-superuser
176 bavail_top_bit_set 1 if fsu_bavail represents a value < 0
177 files Total file nodes
178 ffree Free file nodes
180 On failure, it returns nothing, and C<$!> should be set. If C<$!> is 0, then
181 this is a system which cannot measure usage without a C<disk> argument, which
182 this wrapper does not support.
184 =item is_pid_alive(pid)
186 Return 1 is the process with that pid is still alive.
188 =item weaken_ref($ref)
190 This is exactly the same as C<Scalar::Util::weaken>, but available in all
191 supported versions of perl.
195 Return the number of microseconds since the UNIX epoch.
199 Invoke the C<fsync> syscall.
201 =item set_blocking($fd, $blocking)
203 Set or clear the C<O_NONBLOCK> fd flag on $fd; returns a negative value on
204 failure, or 0 on success.
206 =item openbsd_fd_inform()
208 Due to a particularly poor user-space implementation of threading on OpenBSD,
209 executables that are run with nonstandard file descriptors open (fd > 2) find
210 those descriptors to be in a nonblocking state. This particularly affects
211 amandad services, which begin with several file descriptors in the 50's open.
213 This function "informs" the C library about these descriptors by making an
214 C<fcntl(fd, F_GETFL)> call. This is otherwise harmless, and is only perfomed
217 =item built_with_component($comp)
219 Returns true if Amanda was built with the given component. Component names are
220 in C<config/amanda/components.m4>.
226 These are thin wrappers over functions in C<common-src/stream.h> and other related
233 my $family = $Amanda::Util::AF_INET;
234 my $bufsize = $Amanda::Util::STREAM_BUFSIZE;
235 my ($listensock, $port) = Amanda::Util::stream_server(
236 $family, $bufsize, $bufsize, $priv);
238 This function creates a new socket and binds it to a port, returning both the
239 socket and port. If the socket is -1, then an error occurred and is available
240 in C<$!>. The constants C<$AF_INET> and C<$STREAM_BUFSIZE> are universally
241 used when calling this function. If the final argument, C<$priv>, is true,
242 then a the function opens a privileged port (below 1024).
246 my $sock = Amanda::Util::stream_accept(
247 $listen_sock, $timeout, $bufsize, $bufsize);
249 This function accepts a connection on a listening socket. If the connection is
250 not made within C<$timeout> seconds, or some other error occurs, then the
251 function returns -1. The bufsize arguments are applied to the new socket.
255 my $ok = Amanda::Util::check_security($socket, $userstr);
257 This function takes a socket descriptor and a string of the form C<"USER foo">
258 and performs BSD-style checks on that descriptor. These include verifying
259 round-trip DNS sanity; check that the user is in C<.rhosts> or C<.amandahosts>,
260 and checking that the remote port is reserved. Returns an error string on
261 error, or C<undef> on success.
265 =head1 String Utilities
269 =item quote_string($str)
271 Quote a string using Amanda's quoting algorithm. Strings with no
272 whitespace, control, or quote characters are returned unchanged. An
273 empty string is represented as the two-character string C<"">.
274 Otherwise, tab, newline, carriage return, form-feed, backslash, and
275 double-quote (C<">) characters are escaped with a backslash and the
276 string is surrounded by double quotes.
278 =item unquote_string($str)
280 Unquote a string as quoted with C<quote_string>.
282 =item skip_quoted_string($str)
284 my($q, $remaider) = skip_quoted_string($str)
286 Return the first quoted string and the remainder of the string, as separated by
287 any whitespace. Note that the remainder of the string does not include the
288 single separating whitespace character, but will include any subsequent
289 whitespace. The C<$q> is not unquoted.
291 =item C<split_quoted_strings($str)>
293 Split string on unquoted whitespace. Multiple consecutive spaces are I<not>
294 collapsed into a single space: C<"x y"> (with two spaces) parses as C<( "x",
295 "", "y")>. The strings are unquoted before they are returned. An empty string
296 is split into C<( "" )>. This method is generally used for parsing IPC messages,
297 where blank space is significant and well-controlled.
299 =item C<split_quoted_strings_friendly($str)>
301 Similar to C<split_quoted_strings>, but intended for user-friendly uses. In
302 particular, this function treats any sequence of zero or more whitespace
303 characters as a separator, rather than the more strict interpretation applied
304 by C<split_quoted_strings>. All of the strings are unquoted.
306 All of these quoting-related functions are available under the export
309 =item hexencode($str)
311 Encode a string using URI-style hexadecimal encoding.
312 Non-alphanumeric characters will be replaced with "%xx"
313 where "xx" is the two-digit hexadecimal representation of the character.
315 =item hexdecode($str)
317 Decode a string using URI-style hexadecimal encoding.
319 Both C<hexencode> and C<hexdecode> are available under the export tag C<:encoding>
321 =item expand_braced_alternates($str)
322 =item collapse_braced_alternates(\@list)
324 These two functions handle "braced alternates", which is a syntax
325 borrowed, partially, from shells. Comma-separated strings enclosed in
326 curly braces expand into multiple alternatives for the entire string.
329 "{foo,bar,bat}" [ "foo", "bar", "bat" ]
330 "foo{1,2}bar" [ "foo1bar", "foo2bar" ]
331 "foo{1\,2,3}bar" [ "foo1,2bar", "foo3bar" ]
332 "{a,b}-{1,2}" [ "a-1", "a-2", "b-1", "b-2" ]
334 Note that nested braces are not processed. Braces, commas, and
335 backslashes may be escaped with backslashes.
337 As a special case for numeric ranges, if the braces contain only digits
338 followed by two dots followed by more digits, and the digits sort in the
339 correct order, then they will be treated as a sequence. If the first number in
340 the sequence has leading zeroes, then all generated numbers will have that
341 length, padded with leading zeroes.
343 "tape-{01..10}" [ "tape-01", "tape-02", "tape-03", "tape-04",
344 "tape-05", "tape-06", "tape-07", "tape-08",
345 "tape-09", "tape-10" ]
347 On error, C<expand_braced_altnerates> returns undef. These two functions are
348 available in the export tag C<:alternates>.
350 =item generate_timestamp()
352 Generate a timestamp from the current time, obeying the
353 'USETIMESTAMPS' config parameter. The Amanda configuration must
356 =item sanitise_filename($fn)
358 "Santitises" a filename by replacing any characters that might have special
359 meaning to a filesystem with underscores. This operation is I<not> reversible,
360 and distinct input filenames I<may> produce identical output filenames.
362 =item unmarshal_tapespec($tapespec)
363 =item marshal_tapespec($filelist)
365 These functions convert between a tapespec -- formerly, and confusingly, called
366 a "tapelist" -- and a perl data structure like
368 [ $label1 => [ $filenum1, $filenum2, .. ],
369 $label2 => [ $filenum1, $filenum2, .. ],
372 Note that a non-tapespec C<$string> will be unmarshalled as C<[ $string, [] ]>.
378 Amanda provides a basic mechanism to lock a file and read its contents. This
379 uses operating-system facilities to acquire an advisory lock, so non-Amanda
380 applications are not prevented from modifying the file while it is locked.
382 To create a lock object, call the C<file_lock> constructor, passing the
385 my $fl = Amanda::Util::file_lock->new($filename)
387 then, three ways to lock the file:
389 $fl->lock_wr(); # take a write lock (exclusive)
390 $fl->lock_rd(); # take a read lock
391 $fl->lock(); # take a write lock and reads the contents of
392 # the file into memory.
394 they return -1 on failure, 0 if the lock is taken or 1 if the lock in not
395 taken (you can retry later).
397 to access the data in memory
399 my $state = $fl->data();
401 to change the file contents, call C<write>:
403 $fl->write($new_contents);
405 and unlock the lock with
409 Note that the file will be automatically unlocked if the C<file_lock> object is
412 =head1 Simple File Reading & Writing
414 For reading small files directly into memory with little code
415 overhead, we can use C<slurp>.
417 my $data = slurp $filename;
419 After processing the data, we can write it back to file with C<burp>. This
420 function always completely overwrites the file.
422 burp $filename, $header;
424 These functions can (and should) be exported to the main namespace
428 The following functions are available to match strings against patterns using
429 the rules described in amanda(8):
431 match_host($pat, $str);
432 match_disk($pat, $str);
433 match_datestamp($pat, $str);
434 match_level($pat, $str);