xref: /illumos-gate/usr/src/lib/libvolmgt/volmgt.h (revision 1da57d551424de5a9d469760be7c4b4d4f10a755)
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