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 */ 328