src/lxc/lxclock.h

   1 /*! \file
   2  *
   3  * liblxcapi
   4  *
   5  * Copyright © 2012 Serge Hallyn <serge.hallyn@ubuntu.com>.
   6  * Copyright © 2012 Canonical Ltd.
   7  *
   8  *  This library is free software; you can redistribute it and/or
   9  *  modify it under the terms of the GNU Lesser General Public
  10  *  License as published by the Free Software Foundation; either
  11  *  version 2.1 of the License, or (at your option) any later version.
  12  *
  13  *  This library is distributed in the hope that it will be useful,
  14  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16  *  Lesser General Public License for more details.
  17  *
  18  *  You should have received a copy of the GNU Lesser General Public
  19  *  License along with this library; if not, write to the Free Software
  20  *  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
  21  */
  22
  23 #ifndef __LXC_LXCLOCK_H
  24 #define __LXC_LXCLOCK_H
  25
  26 #include <fcntl.h>
  27 #include <semaphore.h>
  28 #include <string.h>
  29 #include <sys/file.h>
  30 #include <sys/stat.h>
  31 #include <time.h>
  32 #include <unistd.h>
  33
  34 #ifndef F_OFD_GETLK
  35 #define F_OFD_GETLK     36
  36 #endif
  37
  38 #ifndef F_OFD_SETLK
  39 #define F_OFD_SETLK     37
  40 #endif
  41
  42 #ifndef F_OFD_SETLKW
  43 #define F_OFD_SETLKW    38
  44 #endif
  45
  46 #define LXC_LOCK_ANON_SEM 1 /*!< Anonymous semaphore lock */
  47 #define LXC_LOCK_FLOCK    2 /*!< flock(2) lock */
  48
  49 /* private */
  50 /*!
  51  * LXC Lock
  52 */
  53 struct lxc_lock {
  54         short type; /*!< Lock type */
  55
  56         union {
  57                 sem_t *sem; /*!< Anonymous semaphore (LXC_LOCK_ANON_SEM) */
  58                 /*! LXC_LOCK_FLOCK details */
  59                 struct {
  60                         int   fd; /*!< fd on which a lock is held (if not -1) */
  61                         char *fname; /*!< Name of lock */
  62                 } f;
  63         } u; /*!< Container for lock type elements */
  64 };
  65
  66 /*!
  67  * \brief Create a new (unlocked) lock.
  68  *
  69  * \param lxcpath lxcpath lock should relate to.
  70  * \param name Name for lock.
  71  *
  72  * \return Newly-allocated lxclock on success, \c NULL on failure.
  73
  74  * \note If \p name is not given, create an unnamed semaphore
  75  *  (used to protect against racing threads).
  76  *
  77  * \note Note that an unnamed sem was malloced by us and needs to be freed.
  78  *
  79  * \internal \ref sem is initialized to a value of \c 1.
  80  * A 'sem_t *' which can be passed to \ref lxclock() and \ref lxcunlock()
  81  * will be placed in \c l->u.sem.
  82  *
  83  * If \ref lxcpath and \ref name are given (both must be given if either is
  84  * given) then a lockfile is created as \c /run/lxc/lock/$lxcpath/.$name if root,
  85  * or \c $XDG_RUNTIME_DIR/lxc/lock/$lxcpath/.$name if non-root.
  86  * The lock is used to protect the containers on-disk representation.
  87  *
  88  * \internal This function allocates the pathname for the given lock in memory
  89  * such that it can be can quickly opened and locked by \ref lxclock().
  90  * \c l->u.f.fname will contain the malloc'ed name (which must be
  91  * freed when the container is freed), and \c u.f.fd = -1.
  92  *
  93  */
  94 extern struct lxc_lock *lxc_newlock(const char *lxcpath, const char *name);
  95
  96 /*!
  97  * \brief Take an existing lock.
  98  *
  99  * \param lock Lock to operate on.
 100  * \param timeout Seconds to wait to take lock (\c 0 signifies an
 101  * indefinite wait).
 102  *
 103  * \return \c 0 if lock obtained, \c -2 on failure to set timeout,
 104  *  or \c -1 on any other error (\c errno will be set by \c sem_wait(3)
 105  * or \c fcntl(2)).
 106  *
 107  * \note \p timeout is (currently?) only supported for privlock, not
 108  * for slock.  Since currently there is not a single use of the timeout
 109  * (except in the test case) I may remove the support for it in sem as
 110  * well.
 111  */
 112 extern int lxclock(struct lxc_lock *lock, int timeout);
 113
 114 /*!
 115  * \brief Unlock specified lock previously locked using \ref lxclock().
 116  *
 117  * \param lock \ref lxc_lock.
 118  *
 119  * \return \c 0 on success, \c -2 if provided lock was not already held,
 120  * otherwise \c -1 with \c errno saved from \c fcntl(2) or sem_post function.
 121  */
 122 extern int lxcunlock(struct lxc_lock *lock);
 123
 124 /*!
 125  * \brief Free a lock created by \ref lxc_newlock().
 126  *
 127  * \param lock Lock.
 128  */
 129 extern void lxc_putlock(struct lxc_lock *lock);
 130
 131 /*!
 132  * \brief Lock the current process.
 133  */
 134 extern void process_lock(void);
 135
 136 /*!
 137  * \brief Unlock the current process.
 138  */
 139 extern void process_unlock(void);
 140
 141 struct lxc_container;
 142
 143 /*!
 144  * \brief Lock the containers memory.
 145  *
 146  * \param c Container.
 147  *
 148  * \return As for \ref lxclock().
 149  */
 150 extern int container_mem_lock(struct lxc_container *c);
 151
 152 /*!
 153  * \brief Unlock the containers memory.
 154  *
 155  * \param c Container.
 156  */
 157 extern void container_mem_unlock(struct lxc_container *c);
 158
 159 /*!
 160  * \brief Lock the containers disk data.
 161  *
 162  * \param c Container.
 163  *
 164  * \return \c 0 on success, or an \ref lxclock() error return
 165  * values on error.
 166  */
 167 extern int container_disk_lock(struct lxc_container *c);
 168
 169 /*!
 170  * \brief Unlock the containers disk data.
 171  *
 172  * \param c Container.
 173  *
 174  */
 175 extern void container_disk_unlock(struct lxc_container *c);
 176
 177 #endif