xref: /titanic_50/usr/src/man/man3volmgt/volmgt_acquire.3volmgt (revision e0731422366620894c16c1ee6515551c5f00733d)
te
Copyright (c) 1996, Sun Microsystems, Inc. All Rights Reserved
The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
VOLMGT_ACQUIRE 3VOLMGT "Mar 8, 2007"
NAME
volmgt_acquire - reserve removable media device
SYNOPSIS

cc [ flag ... ] file ... -lvolmgt [ library ... ]
#include <sys/types.h>

#include <volmgt.h>



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 management 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 device 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(\|):

sets errno to EBUSY

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

fills in the pid to which the pointer pidp points with the pid of the process which holds the reservation, 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 missing.

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 <volmgt.h>
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

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)?\en",
 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 attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE
MT-Level MT-Safe
Interface Stability Obsolete
SEE ALSO

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

NOTES

When returning a string through err, volmgt_acquire() allocates a memory area using malloc(3C). Use free(3C) to 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 calling application has determined that the current reservation can safely be cleared. See EXAMPLES.