'\" te
.\" Copyright (c) 1996, 2011, Oracle and/or its affiliates. All rights reserved.
.TH volmgt_acquire 3VOLMGT "7 Jul 2011" "SunOS 5.11" "Volume Management Library Functions"
.SH NAME
volmgt_acquire \- reserve removable media device
.SH SYNOPSIS
.LP
.nf
\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lvolmgt\fR [ \fIlibrary\fR ... ]
#include <sys/types.h>

#include <volmgt.h>

\fBint\fR \fBvolmgt_acquire\fR(\fBchar *\fR\fIdev\fR, \fBchar *\fR\fIid\fR, \fBint\fR \fIovr\fR, \fBchar **\fR\fIerr\fR, \fBpid_t *\fR\fIpidp\fR);
.fi

.SH DESCRIPTION
.sp
.LP
This function is obsolete. The management of removable media by the Volume Management feature, including \fBvold\fR, 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 \fBhal\fR(5). The return value of this function is undefined.
.sp
.LP
The  \fBvolmgt_acquire()\fR routine reserves the removable media device specified as  \fIdev\fR. \fBvolmgt_acquire()\fR operates in two different modes, depending on whether or not volume management is running.
.sp
.LP
If  volume management is running, \fBvolmgt_acquire()\fR attempts to reserve the removable media device specified as \fIdev\fR. Specify \fIdev\fR as either a symbolic device name or a physical device pathname.
.sp
.LP
If  volume management is not running, \fBvolmgt_acquire()\fR requires callers to specify a physical device pathname for \fIdev\fR. Specifying \fIdev\fR as a symbolic device name is not acceptable. In this mode, \fBvolmgt_acquire()\fR relies entirely on the major and minor numbers of the device to determine whether or not the device is reserved.
.sp
.LP
If  \fIdev\fR is free,  \fBvolmgt_acquire()\fR updates the internal device reservation database with the caller's process id  (\fIpid\fR) and the specified \fBid\fR string.
.sp
.LP
If  \fIdev\fR is reserved  by another process, the reservation attempt fails and \fBvolmgt_acquire()\fR:
.RS +4
.TP
.ie t \(bu
.el o
sets \fBerrno\fR to \fBEBUSY\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
fills the caller's \fBid\fR value in the array pointed to by \fIerr\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
fills in the  \fIpid\fR to which the pointer  \fIpidp\fR points with the  \fIpid\fR of the process which holds the reservation,   if the supplied \fIpidp\fR is non-zero.
.RE
.sp
.LP
If the override \fIovr\fR is non-zero, the call overrides the device reservation.
.SH RETURN VALUES
.sp
.LP
The return from this function is undefined.
.SH ERRORS
.sp
.LP
The  \fBvolmgt_acquire()\fR routine fails if one or more of the following are true:
.sp
.ne 2
.mk
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 10n
.rt  
One of the specified arguments is invalid or missing.
.RE

.sp
.ne 2
.mk
.na
\fB\fBEBUSY\fR\fR
.ad
.RS 10n
.rt  
\fIdev\fR is already reserved by another process (and \fIovr\fR was not set to a non-zero value)
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
MT-LevelMT-Safe
_
Interface StabilityObsolete
.TE

.SH SEE ALSO
.sp
.LP
\fBfree\fR(3C), \fBmalloc\fR(3C), \fBvolmgt_release\fR(3VOLMGT), \fBattributes\fR(5), \fBhal\fR(5)
.SH NOTES
.sp
.LP
When returning a string through  \fIerr\fR, \fBvolmgt_acquire()\fR allocates a memory area using  \fBmalloc\fR(3C). Use \fBfree\fR(3C) to release the memory area when no longer needed.
.sp
.LP
The \fIovr\fR 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.