1volmgt_acquire(3VOLMGT)Volume Management Library Functionvsolmgt_acquire(3VOLMGT)
2
3
4
6 volmgt_acquire - reserve removable media device
7
9 cc [ flag ... ] file ... -lvolmgt [ library ... ]
10 #include <sys/types.h>
11
12 #include <volmgt.h>
13
14
15
16 int volmgt_acquire(char *dev, char *id, int ovr, char **err, pid_t *pidp);
17
18
20 This function is obsolete. The management of removable media by the
21 Volume Management feature, including vold, has been replaced by soft‐
22 ware that supports the Hardware Abstraction Layer (HAL). Programmatic
23 support for HAL is through the HAL APIs, which are documented on the
24 HAL web site. See hal(5). The return value of this function is unde‐
25 fined.
26
27
28 The volmgt_acquire() routine reserves the removable media device spec‐
29 ified as dev. volmgt_acquire() operates in two different modes,
30 depending on whether or not volume management is running.
31
32
33 If volume management is running, volmgt_acquire() attempts to reserve
34 the removable media device specified as dev. Specify dev as either a
35 symbolic device name (for example, floppy0) or a physical device path‐
36 name (for example, /dsk/unnamed_floppy).
37
38
39 If volume management is not running, volmgt_acquire() requires call‐
40 ers to specify a physical device pathname for dev. Specifying dev as
41 a symbolic device name is not acceptable. In this mode,
42 volmgt_acquire() relies entirely on the major and minor numbers of the
43 device to determine whether or not the device is reserved.
44
45
46 If dev is free, volmgt_acquire() updates the internal device reserva‐
47 tion database with the caller's process id (pid) and the specified id
48 string.
49
50
51 If dev is reserved by another process, the reservation attempt fails
52 and volmgt_acquire():
53
54 o sets errno to EBUSY
55
56 o fills the caller's id value in the array pointed to by err
57
58 o fills in the pid to which the pointer pidp points with the
59 pid of the process which holds the reservation, if the
60 supplied pidp is non-zero
61
62
63 If the override ovr is non-zero, the call overrides the device reser‐
64 vation.
65
67 The return from this function is undefined.
68
70 The volmgt_acquire() routine fails if one or more of the following are
71 true:
72
73 EINVAL One of the specified arguments is invalid or missing.
74
75
76 EBUSY dev is already reserved by another process (and ovr was not
77 set to a non-zero value)
78
79
81 Example 1 Using volmgt_acquire()
82
83
84 In the following example, volume management is running and the first
85 floppy drive is reserved, accessed and released.
86
87
88 #include <volmgt.h>
89 char *errp;
90 if (!volmgt_acquire("floppy0", "FileMgr", 0, NULL,
91 &errp, NULL)) {
92 /* handle error case */
93 ...
94 }
95 /* floppy acquired - now access it */
96 if (!volmgt_release("floppy0")) {
97 /* handle error case */
98 ...
99 }
100
101
102 Example 2 Using volmgt_acquire() To Override A Lock On Another Process
103
104
105 The following example shows how callers can override a lock on another
106 process using volmgt_acquire().
107
108
109 char *errp, buf[20];
110 int override = 0;
111 pid_t pid;
112 if (!volmgt_acquire("floppy0", "FileMgr", 0, &errp,
113 &pid)) {
114 if (errno == EBUSY) {
115 (void) printf("override %s (pid=%ld)?\n",
116 errp, pid); {
117 (void) fgets(buf, 20, stdin);
118 if (buf[0] == 'y') {
119 override++;
120 }
121 } else {
122 /* handle other errors */
123 ...
124 }
125 }
126 if (override) {
127 if (!volmgt_acquire("floppy0", "FileMgr", 1,
128 &errp, NULL)) {
129 /* really give up this time! */
130 ...
131 }
132 }
133
134
136 See attributes(5) for descriptions of the following attributes:
137
138
139
140
141 ┌─────────────────────────────┬─────────────────────────────┐
142 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
143 ├─────────────────────────────┼─────────────────────────────┤
144 │MT-Level │MT-Safe │
145 ├─────────────────────────────┼─────────────────────────────┤
146 │Interface Stability │Obsolete │
147 └─────────────────────────────┴─────────────────────────────┘
148
150 free(3C), malloc(3C), volmgt_release(3VOLMGT), attributes(5), hal(5)
151
153 When returning a string through err, volmgt_acquire() allocates a mem‐
154 ory area using malloc(3C). Use free(3C) to release the memory area
155 when no longer needed.
156
157
158 The ovr argument is intended to allow callers to override the current
159 device reservation. It is assumed that the calling application has
160 determined that the current reservation can safely be cleared. See
161 EXAMPLES.
162
163
164
165SunOS 5.11 8 Mar 2007 volmgt_acquire(3VOLMGT)