MEDIA_FINDNAME(3VOLMGT) Volume Management Library Functions

NAME

media_findname - convert a supplied name into an absolute pathname
that can be used to access removable media

SYNOPSIS

cc [ flag ... ] file ... -lvolmgt [ library ... ]
#include <volmgt.h>


char *media_findname(char *start);

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(7). The return value of this
function is undefined.


media_findname() converts the supplied start string into an absolute
pathname that can then be used to access a particular piece of media.


The start parameter can be one of the following types of
specifications:

/dev/...
An absolute pathname in /dev, such as
/dev/rdiskette0, in which case a copy of that
string is returned (see NOTES on this page).


volume_name
The volume name for a particular volume, such as
fred (see fdformat(1) for a description of how to
label floppies).


volmgt_symname
The symbolic name for a device, such as floppy0 or
cdrom2.


media_type
The generic media type name. For example, floppy
or cdrom. In this case media_findname() looks for
the first piece of media that matches that media
type, starting at 0 (zero) and continuing on until
a match is found (or some fairly large maximum
number is reached). In this case, if a match is
found, a copy of the pathname to the volume found
is returned.

RETURN VALUES

The return from this function is undefined.

ERRORS

For cases where the supplied start parameter is an absolute pathname,
media_findname() can fail, returning a null string pointer, if an
lstat(2) of that supplied pathname fails. Also, if the supplied
absolute pathname is a symbolic link, media_findname() can fail if a
readlink(2) of that symbolic link fails, or if a stat(2) of the
pathname pointed to by that symbolic link fails, or if any of the
following is true:

ENXIO
The specified absolute pathname was not a character special
device, and it was not a directory with a character special
device in it.

EXAMPLES

Example 1: Sample programs of the media_findname() function.

The following example attempts to find what the pathname is to a
piece of media called fred. Notice that a volmgt_check() is done
first (see the NOTES section on this page).


(void) volmgt_check(NULL);
if ((nm = media_findname("fred")) != NULL) {
(void) printf("media named \"fred\" is at \"%s\"\n", nm);
} else {
(void) printf("media named \"fred\" not found\n");
}


This example looks for whatever volume is in the first floppy drive,
letting media_findname() call volmgt_check() if and only if no floppy
is currently known to be the first floppy drive.


if ((nm = media_findname("floppy0")) != NULL) {
(void) printf("path to floppy0 is \"%s\"\n", nm);
} else {
(void) printf("nothing in floppy0\n");
}

ATTRIBUTES

See attributes(7) for descriptions of the following attributes:


+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|MT-Level | MT-Unsafe |
+--------------------+-----------------+
|Interface Stability | Obsolete |
+--------------------+-----------------+

SEE ALSO

fdformat(1), lstat(2), readlink(2), stat(2), free(3C), malloc(3C),
volmgt_check(3VOLMGT), volmgt_inuse(3VOLMGT), volmgt_root(3VOLMGT),
volmgt_running(3VOLMGT), volmgt_symname(3VOLMGT), attributes(7),
hal(7)

NOTES

If media_findname() cannot find a match for the supplied name, it
performs a volmgt_check(3VOLMGT) and tries again, so it can be more
efficient to perform volmgt_check() before calling media_findname().


Upon success media_findname() returns a pointer to string which has
been allocated; this should be freed when no longer in use (see
free(3C)).

March 2, 2007 MEDIA_FINDNAME(3VOLMGT)