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