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

   1 /*
   2  * Amanda, The Advanced Maryland Automatic Network Disk Archiver
   3  * Copyright (c) 1991-1999 University of Maryland at College Park
   4  * Copyright (c) 2007-2012 Zmanda, Inc.  All Rights Reserved.
   5  * All Rights Reserved.
   6  *
   7  * Permission to use, copy, modify, distribute, and sell this software and its
   8  * documentation for any purpose is hereby granted without fee, provided that
   9  * the above copyright notice appear in all copies and that both that
  10  * copyright notice and this permission notice appear in supporting
  11  * documentation, and that the name of U.M. not be used in advertising or
  12  * publicity pertaining to distribution of the software without specific,
  13  * written prior permission.  U.M. makes no representations about the
  14  * suitability of this software for any purpose.  It is provided "as is"
  15  * without express or implied warranty.
  16  *
  17  * U.M. DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL
  18  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL U.M.
  19  * BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  20  * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
  21  * OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
  22  * CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  23  *
  24  * Authors: the Amanda Development Team.  Its members are listed in a
  25  * file named AUTHORS, in the root directory of this distribution.
  26  */
  27
  28 /* Moved from amanda.h and amflock.c by Dustin J. Mitchell <dustin@zmanda.com> */
  29
  30 /*
  31  * New interface
  32  */
  33
  34 typedef struct file_lock {
  35     /* the entire contents of the locked file */
  36     char *data;
  37     size_t len;
  38
  39     /* do not touch! */
  40     gboolean locked;
  41     int fd;
  42     char *filename;
  43 } file_lock;
  44
  45 /* Create a new, unlocked file_lock object
  46  *
  47  * @param filename: filename of the file to lock
  48  */
  49 file_lock *file_lock_new(const char *filename);
  50
  51 /* Free a file_lock object, unlocking it in the process
  52  * if necessary.
  53  *
  54  * @param lock: the file_lock object
  55  */
  56 void file_lock_free(file_lock *lock);
  57
  58 /* Lock a file and read its contents.  This function will create the file if it
  59  * doesn't already exist, in which case lock->data will be NULL and lock->len
  60  * will be 0.
  61  *
  62  * If the file cannot be locked, this function will not block, but will return
  63  * 1.  Callers must poll for lock release, if it is desired.  This is for
  64  * compatibility with the GMainLoop, which does not allow arbitrary blocking.
  65  *
  66  * The lock represented by this function applies both within the current
  67  * process (excluding other threads) and across all Amanda processes on the
  68  * system, assuming that the filename is specified identically.  On
  69  * sufficiently modern systems, it will also function propertly across NFS
  70  * mounts.
  71  *
  72  * Becuse this function may use fcntl to implement the locking, it is critical
  73  * that the locked filename not be opened for any other reason while the lock
  74  * is held, as this may unintentionally release the lock.
  75  *
  76  * @param lock: the file_lock object @returns: -1 on error, 0 on success, 1 on
  77  * a busy lock (see above)
  78  */
  79 int file_lock_lock(file_lock *lock);
  80
  81 /* Lock the file in write or read mode, the file is not read
  82  *
  83  * @param lock: the file_lock object @returns: -1 on error, 0 on success, 1 on
  84  * a busy lock (see above)
  85  */
  86 int file_lock_lock_wr(file_lock *lock);
  87 int file_lock_lock_rd(file_lock *lock);
  88
  89 /* Return 1 if the object is already locked
  90  */
  91 int file_lock_locked(file_lock *lock);
  92
  93 /* Write the given data to the locked file, and reset the file_lock
  94  * data member to point to a copy of the new data.  This does not unlock
  95  * the file.
  96  *
  97  * @param lock: the file_lock object
  98  * @param data: data to write
  99  * @param len: size of data
 100  * @returns: -1 on error (with errno set), 0 on succes
 101  */
 102 int file_lock_write(file_lock *lock, const char *data, size_t len);
 103
 104 /* Unlock a locked file, without first re-writing it to disk.
 105  *
 106  * @param lock: the file_lock object
 107  * @returns: -1 on error (with errno set), 0 on succes
 108  */
 109 int file_lock_unlock(file_lock *lock);
 110
 111 /*
 112  * Old interface
 113  */
 114
 115 /*
 116  * Get a file lock (for read/write files).
 117  */
 118 int amflock(int fd, char *resource);
 119
 120 /*
 121  * Get a file lock (for read-only files).
 122  */
 123 int amroflock(int fd, char *resource);
 124
 125 /*
 126  * Release a file lock.
 127  */
 128 int amfunlock(int fd, char *resource);
 129
 130 /* Implementation interface */
 131 typedef int (*amflock_fn)(int, char *);
 132 typedef struct amflock_impl_s {
 133     amflock_fn amflock_impl;
 134     amflock_fn amroflock_impl;
 135     amflock_fn amfunlock_impl;
 136     char *impl_name;
 137 } amflock_impl_t;