usr/src/lib/libvolmgt/volmgt.h

   1 /*
   2  * CDDL HEADER START
   3  *
   4  * The contents of this file are subject to the terms of the
   5  * Common Development and Distribution License, Version 1.0 only
   6  * (the "License").  You may not use this file except in compliance
   7  * with the License.
   8  *
   9  * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
  10  * or http://www.opensolaris.org/os/licensing.
  11  * See the License for the specific language governing permissions
  12  * and limitations under the License.
  13  *
  14  * When distributing Covered Code, include this CDDL HEADER in each
  15  * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  16  * If applicable, add the following below this CDDL HEADER, with the
  17  * fields enclosed by brackets "[]" replaced with your own identifying
  18  * information: Portions Copyright [yyyy] [name of copyright owner]
  19  *
  20  * CDDL HEADER END
  21  */
  22 /*
  23  * Copyright (c) 1993, by Sun Microsystems, Inc.
  24  */
  25
  26 #ifndef _VOLMGT_H
  27 #define _VOLMGT_H
  28
  29 #pragma ident   "%Z%%M% %I%     %E% SMI"
  30
  31 #ifdef  __cplusplus
  32 extern "C" {
  33 #endif
  34
  35 #include <sys/types.h>
  36
  37 /*
  38  * volmgt_check:
  39  *      have volume management look at its devices to check
  40  *      for media having arrived.  Since volume management can't
  41  *      automatically check all types of devices, this function is provided
  42  *      to allow applications to cause the check to happen automatically.
  43  *
  44  * arguments:
  45  *      path - the name of the device in /dev.  For example,
  46  *        /dev/rdiskette.  If path is NULL, all "checkable" devices are
  47  *        checked.
  48  *
  49  * return value(s):
  50  *      TRUE if media was found in the device, FALSE if not.
  51  */
  52 int volmgt_check(char *path);
  53
  54 /*
  55  * volmgt_inuse:
  56  *      check to see if volume management is currently
  57  *      managing a particular device.
  58  *
  59  * arguments:
  60  *      path - the name of the device in /dev.  For example,
  61  *        "/dev/rdiskette".
  62  *
  63  * return value(s):
  64  *      TRUE if volume management is managing the device, FALSE if not.
  65  */
  66 int volmgt_inuse(char *path);
  67
  68 /*
  69  * volmgt_running:
  70  *      check to see if volume management is running.
  71  *
  72  * arguments:
  73  *      none.
  74  *
  75  * return value(s):
  76  *      TRUE if volume management is running, FALSE if not.
  77  */
  78 int volmgt_running(void);
  79
  80 /*
  81  * volmgt_symname:
  82  *      Returns the volume management symbolic name
  83  *      for a given device.  If an application wants to determine
  84  *      what the symbolic name (e.g. "floppy0") for the /dev/rdiskette
  85  *      device would be, this is the function to use.
  86  *
  87  * arguments:
  88  *      path - a string containing the /dev device name.  For example,
  89  *      "/dev/diskette" or "/dev/rdiskette".
  90  *
  91  * return value(s):
  92  *      pointer to a string containing the symbolic name.
  93  *
  94  *      NULL indicates that volume management isn't managing that device.
  95  *
  96  *      The string must be free(3)'d.
  97  */
  98 char    *volmgt_symname(char *path);
  99
 100 /*
 101  * volmgt_symdev:
 102  *      Returns the device given the volume management
 103  *      symbolic name. If an application wants to determine
 104  *      what the device associated with a particular symbolic name
 105  *      might be, this is the function to use.
 106  *
 107  * arguments:
 108  *      path - a string containing the symbolic device name.  For example,
 109  *      "cdrom0" or "floppy0".
 110  *
 111  * return value(s):
 112  *      pointer to a string containing the /dev name.
 113  *
 114  *      NULL indicates that volume management isn't managing that device.
 115  *
 116  *      The string must be free(3)'d.
 117  */
 118 char    *volmgt_symdev(char *symname);
 119
 120 /*
 121  * volmgt_ownspath:
 122  *      check to see if the given path is contained in
 123  *      the volume management name space.
 124  *
 125  * arguments:
 126  *      path - string containing the path.
 127  *
 128  * return value(s):
 129  *      TRUE if the path is owned by volume management, FALSE if not.
 130  *      Will return FALSE if volume management isn't running.
 131  *
 132  */
 133 int     volmgt_ownspath(char *path);
 134
 135 /*
 136  * volmgt_root:
 137  *      return the root of where the volume management
 138  *      name space is mounted.
 139  *
 140  * arguments:
 141  *      none.
 142  *
 143  * return value(s):
 144  *      Returns a pointer to a string containing the path to the
 145  *      volume management root (e.g. "/vol").
 146  *      Will return NULL if volume management isn't running.
 147  */
 148 const char      *volmgt_root(void);
 149
 150 /*
 151  * media_findname:
 152  *      try to come up with the character device when
 153  *      provided with a starting point.  This interface provides the
 154  *      application programmer to provide "user friendly" names and
 155  *      easily determine the "/vol" name.
 156  *
 157  * arguments:
 158  *      start - a string describing a device.  This string can be:
 159  *              - a full path name to a device (insures it's a
 160  *                character device by using getfullrawname()).
 161  *              - a full path name to a volume management media name
 162  *                with partitions (will return the lowest numbered
 163  *                raw partition.
 164  *              - the name of a piece of media (e.g. "fred").
 165  *              - a symbolic device name (e.g. floppy0, cdrom0, etc)
 166  *              - a name like "floppy" or "cdrom".  Will pick the lowest
 167  *                numbered device with media in it.
 168  *
 169  * return value(s):
 170  *      A pointer to a string that contains the character device
 171  *      most appropriate to the "start" argument.
 172  *
 173  *      NULL indicates that we were unable to find media based on "start".
 174  *
 175  *      The string must be free(3)'d.
 176  */
 177 char    *media_findname(char *start);
 178
 179 /*
 180  * media_getattr:
 181  *      returns the value for an attribute for a piece of
 182  *      removable media.
 183  *
 184  * arguments:
 185  *      path - Path to the media in /vol.  Can be the block or character
 186  *              device.
 187  *
 188  *      attr - name of the attribute.
 189  *
 190  * return value(s):
 191  *      returns NULL or a pointer to a string that contains the value for
 192  *      the requested attribute.
 193  *
 194  *      NULL can mean:
 195  *       - the media doesn't exist
 196  *       - there is no more space for malloc(3)
 197  *       - the attribute doesn't exist for the named media
 198  *       - the attribute is a boolean and is FALSE
 199  *
 200  *      the pointer to the string must be free'd with free(3).
 201  */
 202 char *media_getattr(char *path, char *attr);
 203
 204 /*
 205  * media_setattr:
 206  *      set an attribute for a piece of media to a
 207  *      particular value.
 208  *
 209  * arguments:
 210  *      path - Path to the media in /vol.  Can be the block or character
 211  *              device.
 212  *
 213  *      attr - name of the attribute.
 214  *
 215  *      value - value of the attribute.  If value == "", the flag is
 216  *          considered to be a boolean that is TRUE.  If value == 0, it
 217  *          is considered to be a FALSE boolean.
 218  *
 219  * return value(s):
 220  *      TRUE on success, FALSE for failure.
 221  *
 222  *      Can fail because:
 223  *              - don't have permission to set the attribute because caller
 224  *                is not the owner of the media and attribute is a "system"
 225  *                attribute.
 226  *
 227  *              - don't have permission to set the attribute because the
 228  *                attribute is a "system" attribute and is read-only.
 229  */
 230 int     media_setattr(char *path, char *attr, char *value);
 231
 232 /*
 233  * media_getid:
 234  *      return the "id" of a piece of media.
 235  *
 236  * arguments:
 237  *      path - Path to the media in /vol.  Can be the block or character
 238  *              device.
 239  * return value(s):
 240  *      returns a u_longlong_t that is the "id" of the volume.
 241  *
 242  */
 243 u_longlong_t    media_getid(char *path);
 244
 245 /*
 246  * volmgt_feature_enabled:
 247  *      check to see if a volume management feature is available
 248  *
 249  * arguments:
 250  *      feat_str - a string containing the feature to be checked for
 251  *
 252  * return value(s):
 253  *      returns non-zero if the specified feature is available
 254  *      in volume management, else return zero
 255  */
 256 int     volmgt_feature_enabled(char *feat_str);
 257
 258 /*
 259  * volmgt_acquire
 260  *      try to acquire the volmgt advisory device reservation
 261  *      for a specific device. -- if volmgt isn't running then try to
 262  *      reserve the device specified
 263  *
 264  * arguments:
 265  *      dev - a device name to attempt reserving.  This string can be:
 266  *              - a full path name to a device in /vol if volmgt is running
 267  *              - a symbolic device name (e.g. floppy0) if volmgt is running
 268  *              - a /dev pathname if volmgt is not running
 269  *
 270  *      id  - a reservation string that hopefully describes the application
 271  *              making this reservation.
 272  *
 273  *      ovr - an override indicator.  If set to non-zero, the caller requests
 274  *              that this reservation be made unconditionally.
 275  *
 276  *      err - the address of a char ptr that will updated to point to the
 277  *              id argument used when the current device was reserved.  This
 278  *              is only used when the current reservation attempt fails due
 279  *              to an already existing reservation for this device.
 280  *
 281  *      pidp - a pointer to a pid_t type.  If this argument is not NULL
 282  *              and the requested device is already reserved, the process
 283  *              id of the reservation owner will be returned in this
 284  *              location.
 285  *
 286  *
 287  * return value(s):
 288  *      A non-zero indicator if successful.
 289  *
 290  *      A zero indicator if unsuccessful.  If errno is EBUSY, then the err
 291  *      argument will be set to point to the string that the process currently
 292  *      holding the reservation supplied when reserving the device.  It is up
 293  *      to the caller to release the storage occupied by the string via
 294  *      free(3C) when no longer needed.
 295  */
 296 int     volmgt_acquire(char *dev, char *id, int ovr, char **err, pid_t *pidp);
 297
 298 /*
 299  * the max length for the "id" string in volmgt_acquire
 300  */
 301 #define VOL_RSV_MAXIDLEN        256
 302
 303 /*
 304  * volmgt_release:
 305  *      try to release the volmgt advisory device reservation
 306  *      for a specific device.
 307  *
 308  * arguments:
 309  *      dev - a device name to attempt reserving.  This string can be:
 310  *              - a full path name to a device in /vol if volmgt is running
 311  *              - a symbolic device name (e.g. floppy0) if volmgt is running
 312  *              - a /dev pathname if volmgt is not running
 313  *
 314  * return value(s):
 315  *      A non-zero indicator if successful
 316  *      A zero indicator if unsuccessful
 317  *
 318  * preconditions:
 319  *      none
 320  */
 321 int     volmgt_release(char *dev);
 322
 323 #ifdef  __cplusplus
 324 }
 325 #endif
 326
 327 #endif  /* _VOLMGT_H */