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
32extern "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 */
52int 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 */
66int 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 */
78int 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 */
98char 	*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 */
118char 	*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 */
133int	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 */
148const 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 */
177char 	*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 */
202char *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 */
230int	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 */
243u_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 */
256int	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 */
296int	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 */
321int	volmgt_release(char *dev);
322
323#ifdef	__cplusplus
324}
325#endif
326
327#endif	/* _VOLMGT_H */
328