github.com/kubiko/snapd@v0.0.0-20201013125620-d4f3094d9ddf/cmd/libsnap-confine-private/locking.h (about)

     1  /*
     2   * Copyright (C) 2017-2018 Canonical Ltd
     3   *
     4   * This program is free software: you can redistribute it and/or modify
     5   * it under the terms of the GNU General Public License version 3 as
     6   * published by the Free Software Foundation.
     7   *
     8   * This program is distributed in the hope that it will be useful,
     9   * but WITHOUT ANY WARRANTY; without even the implied warranty of
    10   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    11   * GNU General Public License for more details.
    12   *
    13   * You should have received a copy of the GNU General Public License
    14   * along with this program.  If not, see <http://www.gnu.org/licenses/>.
    15   *
    16   */
    17  #ifndef SNAP_CONFINE_LOCKING_H
    18  #define SNAP_CONFINE_LOCKING_H
    19  
    20  // Include config.h which pulls in _GNU_SOURCE which in turn allows sys/types.h
    21  // to define O_PATH. Since locking.h is included from locking.c this is
    22  // required to see O_PATH there.
    23  #ifdef HAVE_CONFIG_H
    24  #include "config.h"
    25  #endif
    26  
    27  #include <sys/types.h>
    28  
    29  /**
    30   * Obtain a flock-based, exclusive, globally scoped, lock.
    31   *
    32   * The actual lock is placed in "/run/snap/ns/.lock"
    33   *
    34   * If the lock cannot be acquired for three seconds (via
    35   * sc_enable_sanity_timeout) then the function fails and the process dies.
    36   *
    37   * The return value needs to be passed to sc_unlock(), there is no need to
    38   * check for errors as the function will die() on any problem.
    39   **/
    40  int sc_lock_global(void);
    41  
    42  /**
    43   * Obtain a flock-based, exclusive, snap-scoped, lock.
    44   *
    45   * The actual lock is placed in "/run/snapd/ns/$SNAP_NAME.lock"
    46   * It should be acquired only when holding the global lock.
    47   *
    48   * If the lock cannot be acquired for three seconds (via
    49   * sc_enable_sanity_timeout) then the function fails and the process dies.
    50   *
    51   * The return value needs to be passed to sc_unlock(), there is no need to
    52   * check for errors as the function will die() on any problem.
    53   **/
    54  int sc_lock_snap(const char *snap_name);
    55  
    56  /**
    57   * Verify that a flock-based, exclusive, snap-scoped, lock is held.
    58   *
    59   * If the lock is not held the process dies. The details about the lock
    60   * are exactly the same as for sc_lock_snap().
    61   **/
    62  void sc_verify_snap_lock(const char *snap_name);
    63  
    64  /**
    65   * Obtain a flock-based, exclusive, snap-scoped, lock.
    66   *
    67   * The actual lock is placed in "/run/snapd/ns/$SNAP_NAME.$UID.lock"
    68   * It should be acquired only when holding the snap-specific lock.
    69   *
    70   * If the lock cannot be acquired for three seconds (via
    71   * sc_enable_sanity_timeout) then the function fails and the process dies.
    72   * The return value needs to be passed to sc_unlock(), there is no need to
    73   * check for errors as the function will die() on any problem.
    74   **/
    75  int sc_lock_snap_user(const char *snap_name, uid_t uid);
    76  
    77  /**
    78   * Release a flock-based lock.
    79   *
    80   * All kinds of locks can be unlocked the same way. This function simply
    81   * unlocks the lock and closes the file descriptor.
    82   **/
    83  void sc_unlock(int lock_fd);
    84  
    85  /**
    86   * Enable a sanity-check timeout.
    87   *
    88   * The timeout is based on good-old alarm(2) and is intended to break a
    89   * suspended system call, such as flock, after a few seconds. The built-in
    90   * timeout is primed for three seconds. After that any sleeping system calls
    91   * are interrupted and a flag is set.
    92   *
    93   * The call should be paired with sc_disable_sanity_check_timeout() that
    94   * disables the alarm and acts on the flag, aborting the process if the timeout
    95   * gets exceeded.
    96   **/
    97  void sc_enable_sanity_timeout(void);
    98  
    99  /**
   100   * Disable sanity-check timeout and abort the process if it expired.
   101   *
   102   * This call has to be paired with sc_enable_sanity_timeout(), see the function
   103   * description for more details.
   104   **/
   105  void sc_disable_sanity_timeout(void);
   106  
   107  #endif				// SNAP_CONFINE_LOCKING_H