usr/src/man/man3volmgt/media_findname.3volmgt

   1 '\" te
   2 .\"  Copyright (c) 1995, Sun Microsystems, Inc.  All Rights Reserved
   3 .\" 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.
   4 .\"  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
   5 .\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH MEDIA_FINDNAME 3VOLMGT "Mar 2, 2007"
   7 .SH NAME
   8 media_findname \- convert a supplied name into an absolute pathname that can be
   9 used to access removable media
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 \fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lvolmgt\fR [ \fIlibrary\fR ... ]
  14 #include <volmgt.h>
  15
  16
  17
  18 \fBchar *\fR\fBmedia_findname\fR(\fBchar *\fR\fIstart\fR);
  19 .fi
  20
  21 .SH DESCRIPTION
  22 .sp
  23 .LP
  24 This function is obsolete. The management of removable media by the Volume
  25 Management feature, including \fBvold\fR, has been replaced by software that
  26 supports the Hardware Abstraction Layer (HAL). Programmatic support for HAL is
  27 through the HAL APIs, which are documented on the HAL web site. See
  28 \fBhal\fR(5). The return value of this function is undefined.
  29 .sp
  30 .LP
  31 \fBmedia_findname()\fR converts the supplied \fIstart\fR string into an
  32 absolute pathname that can then be used to access a particular piece of media.
  33 .sp
  34 .LP
  35 The \fIstart\fR parameter can be one of the following types of specifications:
  36 .sp
  37 .ne 2
  38 .na
  39 \fB\fB/dev/\fR\|.\|.\|.\fR
  40 .ad
  41 .RS 18n
  42 An absolute pathname in \fB/dev\fR, such as \fB/dev/rdiskette0\fR, in which
  43 case a copy of that string is returned (see \fBNOTES\fR on this page).
  44 .RE
  45
  46 .sp
  47 .ne 2
  48 .na
  49 \fB\fIvolume_name\fR\fR
  50 .ad
  51 .RS 18n
  52 The volume name for a particular volume, such as \fBfred\fR (see
  53 \fBfdformat\fR(1) for a description of how to label floppies).
  54 .RE
  55
  56 .sp
  57 .ne 2
  58 .na
  59 \fB\fIvolmgt_symname\fR\fR
  60 .ad
  61 .RS 18n
  62 The symbolic name for a device, such as \fBfloppy0\fR or \fBcdrom2\fR.
  63 .RE
  64
  65 .sp
  66 .ne 2
  67 .na
  68 \fB\fImedia_type\fR\fR
  69 .ad
  70 .RS 18n
  71 The generic media type name.  For example, \fBfloppy\fR or \fBcdrom\fR. In this
  72 case \fBmedia_findname()\fR looks for the first piece of media that matches
  73 that media type, starting at 0 (zero) and continuing on until a match is found
  74 (or some fairly large maximum number is reached).  In this case, if a match is
  75 found, a copy of the pathname to the volume found is returned.
  76 .RE
  77
  78 .SH RETURN VALUES
  79 .sp
  80 .LP
  81 The return from this function is undefined.
  82 .SH ERRORS
  83 .sp
  84 .LP
  85 For cases where the supplied \fIstart\fR parameter is an absolute pathname,
  86 \fBmedia_findname()\fR can fail, returning a null string pointer, if an
  87 \fBlstat\fR(2) of that supplied pathname fails. Also, if the supplied absolute
  88 pathname is a symbolic link, \fBmedia_findname()\fR can fail if a
  89 \fBreadlink\fR(2) of that symbolic link fails, or if a \fBstat\fR(2) of the
  90 pathname pointed to by that symbolic link fails, or if any of the following is
  91 true:
  92 .sp
  93 .ne 2
  94 .na
  95 \fB\fBENXIO\fR\fR
  96 .ad
  97 .RS 9n
  98 The specified absolute pathname was not a character special device, and it was
  99 not a directory with a character special device in it.
 100 .RE
 101
 102 .SH EXAMPLES
 103 .LP
 104 \fBExample 1 \fRSample programs of the \fBmedia_findname()\fR function.
 105 .sp
 106 .LP
 107 The following example attempts to find what the pathname is to a piece of media
 108 called fred.  Notice that a \fBvolmgt_check()\fR is done first (see the
 109 \fBNOTES\fR section on this page).
 110
 111 .sp
 112 .in +2
 113 .nf
 114 \fB(void) volmgt_check(NULL);
 115 if ((nm = media_findname("fred")) != NULL) {
 116         (void) printf("media named \e"fred\e" is at \e"%s\e"\en", nm);
 117 } else {
 118           (void) printf("media named \e"fred\e" not found\en");
 119 }\fR
 120 .fi
 121 .in -2
 122
 123 .sp
 124 .LP
 125 This example looks for whatever volume is in the first floppy drive, letting
 126 \fBmedia_findname()\fR call \fBvolmgt_check()\fR if and only if no floppy is
 127 currently known to be the first floppy drive.
 128
 129 .sp
 130 .in +2
 131 .nf
 132 \fBif ((nm = media_findname("floppy0")) != NULL) {
 133         (void) printf("path to floppy0 is \e"%s\e"\en", nm);
 134 } else {
 135         (void) printf("nothing in floppy0\en");
 136 }\fR
 137 .fi
 138 .in -2
 139
 140 .SH ATTRIBUTES
 141 .sp
 142 .LP
 143 See \fBattributes\fR(5) for descriptions of the following attributes:
 144 .sp
 145
 146 .sp
 147 .TS
 148 box;
 149 c | c
 150 l | l .
 151 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 152 _
 153 MT-Level        MT-Unsafe
 154 _
 155 Interface Stability     Obsolete
 156 .TE
 157
 158 .SH SEE ALSO
 159 .sp
 160 .LP
 161 \fBfdformat\fR(1), \fBlstat\fR(2), \fBreadlink\fR(2), \fBstat\fR(2),
 162 \fBfree\fR(3C), \fBmalloc\fR(3C), \fBvolmgt_check\fR(3VOLMGT),
 163 \fBvolmgt_inuse\fR(3VOLMGT), \fBvolmgt_root\fR(3VOLMGT),
 164 \fBvolmgt_running\fR(3VOLMGT), \fBvolmgt_symname\fR(3VOLMGT),
 165 \fBattributes\fR(5), \fBhal\fR(5)
 166 .SH NOTES
 167 .sp
 168 .LP
 169 If \fBmedia_findname()\fR cannot find a match for the supplied name, it
 170 performs a \fBvolmgt_check\fR(3VOLMGT) and tries again, so it can be more
 171 efficient to perform \fBvolmgt_check()\fR before calling
 172 \fBmedia_findname()\fR.
 173 .sp
 174 .LP
 175 Upon success  \fBmedia_findname()\fR returns a pointer to string which has been
 176 allocated; this should be freed when no longer in use (see \fBfree\fR(3C)).