libmpathvalid/mpath_valid.h

   1 /*
   2  * Copyright (C) 2015 Red Hat, Inc.
   3  *
   4  * This file is part of the device-mapper multipath userspace tools.
   5  *
   6  * This program is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU Lesser General Public License
   8  * as published by the Free Software Foundation; either version 2
   9  * of the License, or (at your option) any later version.
  10  *
  11  * This program is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14  * GNU Lesser General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU Lesser General Public License
  17  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  18  */
  19
  20 #ifndef LIB_MPATH_VALID_H
  21 #define LIB_MPATH_VALID_H
  22
  23 #ifdef __cpluscplus
  24 extern "C" {
  25 #endif
  26
  27 enum mpath_valid_mode {
  28         MPATH_DEFAULT,
  29         MPATH_STRICT,
  30         MPATH_SMART,
  31         MPATH_GREEDY,
  32         MPATH_MODE_ERROR,
  33 };
  34
  35 /*
  36  * MPATH_IS_VALID_NO_CHECK is used to indicate that it is safe to skip
  37  * checks to see if the device has already been released to the system
  38  * for use by things other that multipath.
  39  * MPATH_IS_MAYBE_VALID is used to indicate that this device would
  40  * be a valid multipath path device if another device with the same
  41  * wwid existed */
  42 enum mpath_valid_result {
  43         MPATH_IS_ERROR = -1,
  44         MPATH_IS_NOT_VALID,
  45         MPATH_IS_VALID,
  46         MPATH_IS_VALID_NO_CHECK,
  47         MPATH_IS_MAYBE_VALID,
  48 };
  49
  50 enum mpath_valid_log_style {
  51         MPATH_LOG_STDERR = -1,          /* log to STDERR */
  52         MPATH_LOG_STDERR_TIMESTAMP,     /* log to STDERR, with timestamps */
  53         MPATH_LOG_SYSLOG,               /* log to system log */
  54 };
  55
  56 enum mpath_valid_verbosity {
  57         MPATH_LOG_PRIO_NOLOG = -1,      /* log nothing */
  58         MPATH_LOG_PRIO_ERR,
  59         MPATH_LOG_PRIO_WARN,
  60         MPATH_LOG_PRIO_NOTICE,
  61         MPATH_LOG_PRIO_INFO,
  62         MPATH_LOG_PRIO_DEBUG,
  63 };
  64
  65 /* Function declarations */
  66
  67 /*
  68  * DESCRIPTION:
  69  *      Initialize the device mapper multipath configuration. This
  70  *      function must be invoked before calling any other
  71  *      libmpathvalid functions. Call mpathvalid_exit() to cleanup.
  72  * @verbosity: the logging level (mpath_valid_verbosity)
  73  * @log_style: the logging style (mpath_valid_log_style)
  74  *
  75  * RESTRICTIONS:
  76  *      Calling mpathvalid_init() after calling mpathvalid_exit() has no
  77  *      effect.
  78  *
  79  * RETURNS: 0 = Success, -1 = Failure
  80  */
  81 int mpathvalid_init(int verbosity, int log_style);
  82
  83
  84 /*
  85  * DESCRIPTION:
  86  *      Reread the multipath configuration files and reinitialize
  87  *      the device mapper multipath configuration. This function can
  88  *      be called as many times as necessary.
  89  *
  90  * RETURNS: 0 = Success, -1 = Failure
  91  */
  92 int mpathvalid_reload_config(void);
  93
  94
  95 /*
  96  * DESCRIPTION:
  97  *      Release the device mapper multipath configuration. This
  98  *      function must be called to cleanup resources allocated by
  99  *      mpathvalid_init(). After calling this function, no further
 100  *      libmpathvalid functions may be called.
 101  *
 102  * RETURNS: 0 = Success, -1 = Failure
 103  */
 104 int mpathvalid_exit(void);
 105
 106 /*
 107  * DESCRIPTION:
 108  *      Return the configured find_multipaths claim mode, using the
 109  *      configuration from either mpathvalid_init() or
 110  *      mpathvalid_reload_config()
 111  *
 112  * RETURNS:
 113  *      MPATH_STRICT, MPATH_SMART, MPATH_GREEDY, or MPATH_MODE_ERROR
 114  *
 115  *      MPATH_STRICT     = find_multiapths (yes|on|no|off)
 116  *      MPATH_SMART      = find_multipaths smart
 117  *      MPATH_GREEDY     = find_multipaths greedy
 118  *      MPATH_MODE_ERROR = multipath configuration not initialized
 119  */
 120 unsigned int mpathvalid_get_mode(void);
 121 /*
 122  * DESCRIPTION:
 123  *      Return whether device-mapper multipath claims a path device,
 124  *      using the configuration read from either mpathvalid_init() or
 125  *      mpathvalid_reload_config(). If the device is either claimed or
 126  *      potentially claimed (MPATH_IS_VALID, MPATH_IS_VALID_NO_CHECK,
 127  *      or MPATH_IS_MAYBE_VALID) and wwid is not NULL, then *wiid will
 128  *      be set to point to the wwid of device. If set, *wwid must be
 129  *      freed by the caller. path_wwids is an obptional parameter that
 130  *      points to an array of wwids, that were returned from previous
 131  *      calls to mpathvalid_is_path(). These are wwids of existing
 132  *      devices that are or potentially are claimed by device-mapper
 133  *      multipath. path_wwids is used with the MPATH_SMART claim mode,
 134  *      to claim devices when another device with the same wwid exists.
 135  *      nr_paths must either be set to the number of elements of
 136  *      path_wwids, or 0, if path_wwids is NULL.
 137  * @name: The kernel name of the device. input argument
 138  * @mode: the find_multipaths claim mode (mpath_valid_mode). input argument
 139  * @wwid: address of a pointer to the path wwid, or NULL. Output argument.
 140  *        Set if path is/may be claimed. If set, must be freed by caller
 141  * @path_wwids: Array of pointers to path wwids, or NULL. input argument
 142  * @nr_paths: number of elements in path_wwids array. input argument.
 143  *
 144  * RETURNS: device claim result (mpath_valid_result)
 145  *          Also sets *wwid if wwid is not NULL, and the claim result is
 146  *          MPATH_IS_VALID, MPATH_IS_VALID_NO_CHECK, or
 147  *          MPATH_IS_MAYBE_VALID
 148  */
 149 int mpathvalid_is_path(const char *name, unsigned int mode, char **wwid,
 150                        const char **path_wwids, unsigned int nr_paths);
 151
 152 #ifdef __cplusplus
 153 }
 154 #endif
 155 #endif /* LIB_PATH_VALID_H */