src/lxc/lxclock.h

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