lib/libutil/opendisk.3

   1 .\"     $NetBSD: opendisk.3,v 1.11 2008/04/30 13:10:52 martin Exp $
   2 .\"
   3 .\" Copyright (c) 1997, 2001 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Luke Mewburn.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .Dd December 11, 2001
  31 .Dt OPENDISK 3
  32 .Os
  33 .Sh NAME
  34 .Nm opendisk
  35 .Nd open a disk partition
  36 .Sh LIBRARY
  37 .Lb libutil
  38 .Sh SYNOPSIS
  39 .In util.h
  40 .Ft int
  41 .Fo opendisk
  42 .Fa "const char *path"
  43 .Fa "int flags"
  44 .Fa "char *buf"
  45 .Fa "size_t buflen"
  46 .Fa "int iscooked"
  47 .Fc
  48 .Sh DESCRIPTION
  49 .Fn opendisk
  50 opens
  51 .Fa path ,
  52 for reading and/or writing as specified by the argument
  53 .Fa flags
  54 using
  55 .Xr open 2 ,
  56 and the file descriptor is returned to the caller.
  57 .Fa buf
  58 is used to store the resultant filename.
  59 .Fa buflen
  60 is the size, in bytes, of the array referenced by
  61 .Fa buf
  62 (usually
  63 .Dv MAXPATHLEN
  64 bytes).
  65 .Fa iscooked
  66 controls which paths in
  67 .Pa /dev
  68 are tried.
  69 .Pp
  70 .Fn opendisk
  71 attempts to open the following variations of
  72 .Fa path ,
  73 in order:
  74 .Bl -tag -width "/dev/rpathX"
  75 .It Pa path
  76 The pathname as given.
  77 .It Pa path Ns Em X
  78 .Fa path
  79 with a suffix of
  80 .Sq Em X ,
  81 where
  82 .Sq Em X
  83 represents the raw partition of the device, as determined by
  84 .Xr getrawpartition 3 ,
  85 usually
  86 .Dq c .
  87 .El
  88 .Pp
  89 If
  90 .Fa path
  91 does not contain a
  92 slash
  93 .Pq Dq / ,
  94 the following variations are attempted:
  95 .Pp
  96 .Bl -dash -offset indent
  97 .It
  98 If
  99 .Fa iscooked
 100 is zero:
 101 .Pp
 102 .Bl -tag -width "/dev/rpathX"
 103 .It Pa /dev/rpath
 104 .Fa path
 105 with a prefix of
 106 .Dq Pa /dev/r .
 107 .It Pa /dev/rpath Ns Em X
 108 .Fa path
 109 with a prefix of
 110 .Dq Pa /dev/r
 111 and a suffix of
 112 .Sq Em X
 113 (q.v.).
 114 .El
 115 .It
 116 If
 117 .Fa iscooked
 118 is non-zero:
 119 .Bl -tag -width "/dev/rpathX"
 120 .It Pa /dev/path
 121 .Fa path
 122 with a prefix of
 123 .Dq Pa /dev/ .
 124 .It Pa /dev/path Ns Em X
 125 .Fa path
 126 with a prefix of
 127 .Dq Pa /dev/
 128 and a suffix of
 129 .Sq Em X
 130 (q.v.).
 131 .El
 132 .El
 133 .Sh RETURN VALUES
 134 An open file descriptor, or -1 if the
 135 .Xr open 2
 136 failed.
 137 .Sh ERRORS
 138 .Fn opendisk
 139 may set
 140 .Va errno
 141 to one of the following values:
 142 .Bl -tag -width Er
 143 .It Bq Er EINVAL
 144 .Dv O_CREAT
 145 was set in
 146 .Fa flags ,
 147 or
 148 .Xr getrawpartition 3
 149 didn't return a valid partition.
 150 .It Bq Er EFAULT
 151 .Fa buf
 152 was the
 153 .Dv NULL
 154 pointer.
 155 .El
 156 .Pp
 157 The
 158 .Fn opendisk
 159 function
 160 may also set
 161 .Va errno
 162 to any value specified by the
 163 .Xr open 2
 164 function.
 165 .Sh SEE ALSO
 166 .Xr open 2 ,
 167 .Xr getrawpartition 3
 168 .Sh HISTORY
 169 The
 170 .Fn opendisk
 171 function first appeared in
 172 .Nx 1.3 .