Volume Management Library Functions       volmgtacquire(3VOLMGT)



NAME
     volmgtacquire - reserve removable media device

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

     #include 



     int volmgtacquire(char *dev, char *id, int ovr, char **err, pidt *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  volmgtacquire() routine reserves the  removable  media
     device  specified  as  dev. volmgtacquire() operates in two
     different modes, depending on whether or not volume  manage-
     ment is running.


     If  volume management  is running, volmgtacquire() 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/unnamedfloppy).


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


     If  dev is free,  volmgtacquire() 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  volmgtacquire():




SunOS 5.11           Last change: 8 Mar 2007                    1






Volume Management Library Functions       volmgtacquire(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.

ERORS
     The  volmgtacquire() 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 volmgtacquire()


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


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


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



SunOS 5.11           Last change: 8 Mar 2007                    2






Volume Management Library Functions       volmgtacquire(3VOLMGT)



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


       char *errp, buf[20];
       int override = 0;
       pidt pid;
       if (!volmgtacquire("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 (!volmgtacquire("floppy0", "FileMgr", 1,
                 &errp, NUL)) {
                    /* really give up this time! */
                    ...
             }
       }


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



     
           ATRIBUTE TYPE               ATRIBUTE VALUE       
    
     MT-Level                     MT-Safe                     
    
     Interface Stability          Obsolete                    
    


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

NOTES
     When returning a string through  err, volmgtacquire() 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       volmgtacquire(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