Manual Pages for UNIX Operating System command usage for man volmgt_acquire

Volume Management Library Functions       volmgt_acquire(3VOLMGT)



NAME
     volmgt_acquire - reserve removable media device

SYNOPSIS
     cc [ flag ... ] file ... -lvolmgt [ library ... ]
     #include 

     #include 



     int volmgt_acquire(char *dev, char *id, int ovr, char **err, pid_t *pidp);


DESCRIPTION
     This function is obsolete. The management of removable media
     by  the  Volume Management feature, including vold, has been
     replaced by software that supports the Hardware  Abstraction
     Layer (HAL). Programmatic support for HAL is through the HAL
     APIs, which are documented on the HAL web site. See  hal(5).
     The return value of this function is undefined.


     The  volmgt_acquire() routine reserves the  removable  media
     device  specified  as  dev. volmgt_acquire() operates in two
     different modes, depending on whether or not volume  manage-
     ment is running.


     If  volume management  is running, volmgt_acquire() attempts
     to  reserve  the  removable  media  device specified as dev.
     Specify dev as  either a symbolic device name (for  example,
     floppy0)   or  a  physical  device  pathname  (for  example,
     /dsk/unnamed_floppy).


     If  volume  management   is  not  running,  volmgt_acquire()
     requires  callers  to specify a physical device pathname for
     dev. Specifying  dev as a  symbolic   device  name  is   not
     acceptable.  In this mode,  volmgt_acquire() relies entirely
     on the major and minor numbers of the  device  to  determine
     whether or not the device is reserved.


     If  dev is free,  volmgt_acquire() updates the internal dev-
     ice reservation database with the caller's process id  (pid)
     and the specified id string.


     If  dev is reserved  by  another  process,  the  reservation
     attempt fails and  volmgt_acquire():




SunOS 5.11           Last change: 8 Mar 2007                    1






Volume Management Library Functions       volmgt_acquire(3VOLMGT)



         o    sets errno to EBUSY

         o    fills the caller's id value in the array pointed to
              by err

         o    fills in the  pid to which the pointer  pidp points
              with the  pid of the process which holds the reser-
              vation,   if the supplied pidp is non-zero


     If the override  ovr is non-zero,  the  call  overrides  the
     device reservation.

RETURN VALUES
     The return from this function is undefined.

ERRORS
     The  volmgt_acquire() routine fails if one or  more  of  the
     following are true:

     EINVAL    One of the specified arguments is invalid or miss-
               ing.


     EBUSY     dev is already reserved by  another  process  (and
               ovr was not set to a non-zero value)


EXAMPLES
     Example 1 Using volmgt_acquire()


     In the following example, volume management is  running  and
     the first floppy drive is reserved, accessed and released.


       #include 
       char *errp;
       if (!volmgt_acquire("floppy0", "FileMgr", 0, NULL,
           &errp, NULL)) {
               /* handle error case */
               ...
       }
       /* floppy acquired - now access it */
       if (!volmgt_release("floppy0")) {
               /* handle error case */
               ...
       }


     Example 2 Using  volmgt_acquire()  To  Override  A  Lock  On
     Another Process



SunOS 5.11           Last change: 8 Mar 2007                    2






Volume Management Library Functions       volmgt_acquire(3VOLMGT)



     The following example shows how callers can override a  lock
     on another process using  volmgt_acquire().


       char *errp, buf[20];
       int override = 0;
       pid_t pid;
       if (!volmgt_acquire("floppy0", "FileMgr", 0, &errp,
           &pid)) {
             if (errno == EBUSY) {
                    (void) printf("override %s (pid=%ld)?\n",
                       errp, pid); {
                    (void) fgets(buf, 20, stdin);
                    if (buf[0] == 'y') {
                          override++;
                    }
              } else {
                    /* handle other errors */
                    ...
              }
       }
       if (override) {
             if (!volmgt_acquire("floppy0", "FileMgr", 1,
                 &errp, NULL)) {
                    /* really give up this time! */
                    ...
             }
       }


ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:



     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | MT-Level                    | MT-Safe                     |
    |_____________________________|_____________________________|
    | Interface Stability         | Obsolete                    |
    |_____________________________|_____________________________|


SEE ALSO
     free(3C),   malloc(3C),   volmgt_release(3VOLMGT),    attri-
     butes(5), hal(5)

NOTES
     When returning a string through  err, volmgt_acquire() allo-
     cates  a  memory  area  using   malloc(3C).  Use free(3C) to



SunOS 5.11           Last change: 8 Mar 2007                    3






Volume Management Library Functions       volmgt_acquire(3VOLMGT)



     release the memory area  when no longer needed.


     The ovr argument is intended to allow  callers  to  override
     the  current device reservation. It is assumed that the cal-
     ling application has determined that the current reservation
     can safely be cleared. See  EXAMPLES.
















































SunOS 5.11           Last change: 8 Mar 2007                    4