git.gag.com Git - debian/amanda/blob - common-src/util.h

   1 /*
   2  * Amanda, The Advanced Maryland Automatic Network Disk Archiver
   3  * Copyright (c) 1999 University of Maryland at College Park
   4  * All Rights Reserved.
   5  *
   6  * Permission to use, copy, modify, distribute, and sell this software and its
   7  * documentation for any purpose is hereby granted without fee, provided that
   8  * the above copyright notice appear in all copies and that both that
   9  * copyright notice and this permission notice appear in supporting
  10  * documentation, and that the name of U.M. not be used in advertising or
  11  * publicity pertaining to distribution of the software without specific,
  12  * written prior permission.  U.M. makes no representations about the
  13  * suitability of this software for any purpose.  It is provided "as is"
  14  * without express or implied warranty.
  15  *
  16  * U.M. DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL
  17  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL U.M.
  18  * BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  19  * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
  20  * OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
  21  * CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  22  *
  23  * Authors: the Amanda Development Team.  Its members are listed in a
  24  * file named AUTHORS, in the root directory of this distribution.
  25  */
  26 /*
  27  * $Id: util.h,v 1.17 2006/07/26 15:17:36 martinea Exp $
  28  */
  29 #ifndef UTIL_H
  30 #define UTIL_H
  31
  32 #include "amanda.h"
  33 #include "sl.h"
  34
  35 #include <glib.h>
  36 #include <glib-object.h>
  37 #include <regex.h>
  38
  39 #include "glib-util.h"
  40
  41 #define BIGINT  INT_MAX
  42
  43 #define BSTRNCMP(a,b)  strncmp(a, b, strlen(b))
  44
  45 /* internal types and variables */
  46
  47
  48 ssize_t fullread(int, void *, size_t);
  49 ssize_t fullwrite(int, const void *, size_t);
  50
  51 int     connect_portrange(sockaddr_union *, in_port_t, in_port_t, char *,
  52                           sockaddr_union *, int);
  53 int     bind_portrange(int, sockaddr_union *, in_port_t, in_port_t,
  54                        char *);
  55
  56 char *  construct_datestamp(time_t *t);
  57 char *  construct_timestamp(time_t *t);
  58
  59 /*@only@*//*@null@*/char *quote_string(const char *str);
  60 /*@only@*//*@null@*/char *unquote_string(const char *str);
  61 int     needs_quotes(const char * str);
  62
  63 char *  sanitize_string(const char *str);
  64 int     copy_file(char *dst, char *src, char **errmsg);
  65
  66 /*
  67  *   validate_email return 0 if the following characters are present
  68  *   * ( ) < > [ ] , ; : ! $ \ / "
  69  *   else returns 1
  70  */
  71 int validate_mailto(const char *mailto);
  72
  73 /* This function is a portable reimplementation of readdir(). It
  74  * returns a newly-allocated string, that should be freed with
  75  * free(). Returns NULL on error or end of directory.
  76  * It is reentrant, with the following exceptions:
  77  * - This function cannot be run at the same time as readdir() or
  78  *   readdir64().
  79  * - This function cannot be run simultaneously on the same directory
  80  *   handle. */
  81 char * portable_readdir(DIR*);
  82
  83 typedef gboolean (*SearchDirectoryFunctor)(const char * filename,
  84                                            gpointer user_data);
  85 /* This function will search the given directory handle for files
  86    matching the given POSIX extended regular expression.
  87    For each matching file, the functor will be called with the given
  88    user data. Stops when the functor returns FALSE, or all files have
  89    been searched. Returns the number of matching files. */
  90 int search_directory(DIR * handle, const char * regex,
  91                      SearchDirectoryFunctor functor, gpointer user_data);
  92
  93 /* This function extracts a substring match from a regular expression
  94    match result, and copies it into a newly allocated string. Example
  95    usage to get the first matched substring:
  96    substring = find_regmatch(whole_string, pmatch[1])
  97    Note that pmatch[0] yields the entire matching portion of the string. */
  98 char* find_regex_substring(const char* base_string, const regmatch_t match);
  99
 100 void free_new_argv(int new_argc, char **new_argv);
 101
 102 /* Like strcmp(a, b), except that NULL strings are sorted before non-NULL
 103  * strings, instead of segfaulting. */
 104 int compare_possibly_null_strings(const char * a, const char * b);
 105
 106 /* Does g_thread_init(), along with anything else that should be done
 107  * before/after thread setup. It's OK to call this function more than once.
 108  * Returns TRUE if threads are supported. */
 109 gboolean amanda_thread_init(void);
 110
 111 /* Given a hostname, call getaddrinfo to resolve it.  Optionally get the
 112  * entire set of results (if res is not NULL) and the canonical name of
 113  * the host (if canonname is not NULL).  The canonical name might
 114  * expand e.g., www.domain.com to server3.webfarm.hosting.com.
 115  *
 116  * If not NULL, the caller is responsible for freeing res with freeaddrinfo().
 117  * Similarly, the caller is responsible for freeing canonname if it is
 118  * not NULL.
 119  *
 120  * @param hostname: the hostname to start with
 121  * @param res: (result) if not NULL, the results from getaddrinfo()
 122  * @param canonname: (result) if not NULL, the canonical name of the host
 123  * @returns: newly allocated canonical hostname, or NULL if no
 124  * canonical hostname was available.
 125  */
 126 int resolve_hostname(const char *hostname, int socktype,
 127                      struct addrinfo **res, char **canonname);
 128
 129 /* Interpret a status (as returned from wait() and friends)
 130  * into a human-readable sentence.
 131  *
 132  * Caller is responsible for freeing the resulting string.
 133  * The resulting string has already been translated.
 134  *
 135  * The macro definition allows this to work even when amwait_t
 136  * is 'union wait' (4.3BSD).  The cast is safe because the two
 137  * argument types are interchangeable.
 138  *
 139  * @param subject: subject of the sentence (program name, etc.)
 140  * @param status: the exit status
 141  * @returns: newly allocated string describing status
 142  */
 143 #define str_exit_status(subject, status) \
 144     _str_exit_status((subject), *(amwait_t *)&(status))
 145 char *_str_exit_status(char *subject, amwait_t status);
 146
 147 /*
 148  * Userid manipulation
 149  */
 150
 151 /* Check that the current uid and euid are set to a specific user,
 152  * calling error() if not. Does nothing if CHECK_USERID is not
 153  * defined.
 154  *
 155  * @param who: one of the RUNNING_AS_* constants, below.
 156  */
 157 typedef enum {
 158         /* userid is 0 */
 159     RUNNING_AS_ROOT,
 160
 161         /* userid belongs to dumpuser (from config) */
 162     RUNNING_AS_DUMPUSER,
 163
 164         /* prefer that userid belongs to dumpuser, but accept when userid belongs to
 165          * CLIENT_LOGIN with a debug-log message (needed because amandad always runs
 166          * as CLIENT_LOGIN, even on server) */
 167     RUNNING_AS_DUMPUSER_PREFERRED,
 168
 169         /* userid belongs to CLIENT_LOGIN (from --with-user) */
 170     RUNNING_AS_CLIENT_LOGIN,
 171
 172     RUNNING_AS_USER_MASK = (1 << 8) - 1,
 173         /* '&' this on to only check the uid, not the euid; use this for programs
 174          * that will call become_root() */
 175     RUNNING_AS_UID_ONLY = 1 << 8
 176 } running_as_flags;
 177
 178 void check_running_as(running_as_flags who);
 179
 180 /* Drop and regain root priviledges; used from setuid-root binaries which only
 181  * need to be root for certain operations. Does nothing if SINGLE_USERID is
 182  * defined.
 183  *
 184  * @param need_root: if true, try to assume root priviledges; otherwise, drop
 185  * priviledges.
 186  * @returns: true if the priviledge change succeeded
 187  */
 188 int set_root_privs(int need_root);
 189
 190 /* Become root completely, by setting the uid to 0.  This is used by setuid-root
 191  * apps which will exec subprocesses which will also need root priviledges.  Does
 192  * nothing if SINGLE_USERID is defined.
 193  *
 194  * @returns: true if the priviledge change succeeded
 195  */
 196 int become_root(void);
 197
 198 /*
 199  * Process parameters
 200  */
 201
 202 /* Set the name of the process.  The parameter is copied, and remains
 203  * the responsibility of the caller on return. This value is used in log
 204  * messages and other output throughout Amanda.
 205  *
 206  * @param pname: the new process name
 207  */
 208 void set_pname(char *pname);
 209
 210 /* Get the current process name; the result is in a static buffer, and
 211  * should *not* be free()d by the caller.
 212  *
 213  * @returns: process name
 214  */
 215 char *get_pname(void);
 216
 217 /*
 218  * Readline support
 219  *
 220  * This either includes the system readline header we found in configure,
 221  * or prototypes some simple stub functions that are used instead.
 222  */
 223
 224 #ifdef HAVE_READLINE
 225 #  ifdef HAVE_READLINE_READLINE_H
 226 #    include <readline/readline.h>
 227 #    ifdef HAVE_READLINE_HISTORY_H
 228 #      include <readline/history.h>
 229 #    endif
 230 #  else
 231 #    ifdef HAVE_READLINE_H
 232 #      include <readline.h>
 233 #      ifdef HAVE_HISTORY_H
 234 #        include <history.h>
 235 #      endif
 236 #    endif
 237 #  endif
 238 #else
 239
 240 char *  readline(const char *prompt);
 241 void    add_history(const char *line);
 242
 243 #endif
 244
 245 #endif  /* UTIL_H */