media_findname(3VOLMGT) 				Volume Management Library Functions				   media_findname(3VOLMGT)

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

       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).

       /vol/... 	       An absolute Volume Management pathname, such as /vol/dev/aliases/floppy0 or /vol/dsk/fred. If this  supplied  path-
			       name  is not a symbolic link, then a copy of that pathname is returned. If the supplied pathname is a symbolic link
			       then it is dereferenced and a copy of that dereferenced pathname is returned.

       volume_name	       The Volume Management volume name for a particular volume, such as fred (see fdformat(1) for a description  of  how
			       to label floppies). In this case a pathname in the Volume Management namespace is returned.

       volmgt_symname	       The Volume Management symbolic name for a device, such as floppy0 or cdrom2 (see volfs(7FS) for more information on
			       Volume Management symbolic names), in which  case a pathname in the Volume Management namespace is returned.

       media_type	       The Volume Management 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

       Upon successful completion media_findname() returns a pointer to the pathname found.  In the case of an error a null pointer is returned.

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  read-
       link(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  Volume  Management  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"
", nm);
       } else {
	      (void) printf("media named "fred" not found
");
       }

       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"
", nm);
       } else {
	       (void) printf("nothing in floppy0
");
       }

ATTRIBUTES

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

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |MT-Unsafe 		   |
       +-----------------------------+-----------------------------+

SEE ALSO

       cc(1B),	fdformat(1),  vold(1M),  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(5), volfs(7FS)

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 effi-
       cient 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)).

SunOS 5.10							    31 Dec 1996 					   media_findname(3VOLMGT)