1volmgt_acquire(3VOLMGT)Volume Management Library Functionvsolmgt_acquire(3VOLMGT)
2
3
4

NAME

6       volmgt_acquire - reserve removable media device
7

SYNOPSIS

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

DESCRIPTION

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

RETURN VALUES

67       The return from this function is undefined.
68

ERRORS

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

EXAMPLES

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

ATTRIBUTES

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

SEE ALSO

150       free(3C), malloc(3C), volmgt_release(3VOLMGT), attributes(5), hal(5)
151

NOTES

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)
Impressum