share/man/man9f/ldi_open_by_dev.9f

   1 '\" te
   2 .\" Copyright (c) 2004, 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.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" 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 the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH LDI_OPEN_BY_DEV 9F "Aug 9, 2004"
   7 .SH NAME
   8 ldi_open_by_dev, ldi_open_by_name, ldi_open_by_devid, ldi_close \- open and
   9 close devices
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <sys/sunldi.h>
  14
  15 \fBint\fR \fBldi_open_by_dev\fR(\fBdev_t *\fR\fIdevp\fR, \fBint\fR \fIotyp\fR, \fBint\fR \fIflag\fR, \fBcred_t  *\fR\fIcr\fR,
  16      \fBldi_handle_t *\fR\fIlhp\fR, \fBldi_ident_t\fR \fIli\fR);
  17 .fi
  18
  19 .LP
  20 .nf
  21 \fBint\fR \fBldi_open_by_name\fR(\fBchar  *\fR\fIpathname\fR, \fBint\fR \fIflag\fR, \fBcred_t *\fR\fIcr\fR,
  22      \fBldi_handle_t *\fR\fIlhp\fR, \fBldi_ident_t\fR \fIli\fR);
  23 .fi
  24
  25 .LP
  26 .nf
  27 \fBint\fR \fBldi_open_by_devid\fR(\fBddi_devid_t\fR \fIdevid\fR, \fBchar  *\fR\fIminor_name\fR, \fBint\fR \fIflag\fR,
  28      \fBcred_t *\fR\fIcr\fR, \fBldi_handle_t *\fR\fIlhp\fR, \fBldi_ident_t\fR \fIli\fR);
  29 .fi
  30
  31 .LP
  32 .nf
  33 \fBint\fR \fBldi_close\fR(\fBldi_handle_t\fR \fIlh\fR, \fBint\fR \fIflag\fR, \fBcred_ t *\fR\fIcr\fR);
  34 .fi
  35
  36 .SH PARAMETERS
  37 .sp
  38 .ne 2
  39 .na
  40 \fB\fIlh\fR\fR
  41 .ad
  42 .RS 14n
  43 Layered handle
  44 .RE
  45
  46 .sp
  47 .ne 2
  48 .na
  49 \fB\fIlhp\fR\fR
  50 .ad
  51 .RS 14n
  52 Pointer to a layered handle that is returned upon a successful open.
  53 .RE
  54
  55 .sp
  56 .ne 2
  57 .na
  58 \fB\fIli\fR\fR
  59 .ad
  60 .RS 14n
  61 LDI identifier.
  62 .RE
  63
  64 .sp
  65 .ne 2
  66 .na
  67 \fB\fIcr\fR\fR
  68 .ad
  69 .RS 14n
  70 Pointer to the credential structure used to open a device.
  71 .RE
  72
  73 .sp
  74 .ne 2
  75 .na
  76 \fB\fIdevp\fR\fR
  77 .ad
  78 .RS 14n
  79 Pointer to a device number.
  80 .RE
  81
  82 .sp
  83 .ne 2
  84 .na
  85 \fB\fIpathname\fR\fR
  86 .ad
  87 .RS 14n
  88 Pathname to a device.
  89 .RE
  90
  91 .sp
  92 .ne 2
  93 .na
  94 \fB\fIdevid\fR\fR
  95 .ad
  96 .RS 14n
  97 Device ID.
  98 .RE
  99
 100 .sp
 101 .ne 2
 102 .na
 103 \fB\fIminor_name\fR\fR
 104 .ad
 105 .RS 14n
 106 Minor device node name.
 107 .RE
 108
 109 .sp
 110 .ne 2
 111 .na
 112 \fB\fIotyp\fR\fR
 113 .ad
 114 .RS 14n
 115 Flag passed to the driver indicating which interface is open. Valid settings
 116 are:
 117 .sp
 118 .ne 2
 119 .na
 120 \fBOTYP_BLK\fR
 121 .ad
 122 .RS 12n
 123 Open the device block interface.
 124 .RE
 125
 126 .sp
 127 .ne 2
 128 .na
 129 \fBOTYP_CHR\fR
 130 .ad
 131 .RS 12n
 132 Open the device character interface.
 133 .RE
 134
 135 Only one OTYP flag can be specified. To open streams devices, specify
 136 \fBOTYP_CHR\fR.
 137 .RE
 138
 139 .sp
 140 .ne 2
 141 .na
 142 \fB\fIflag\fR\fR
 143 .ad
 144 .RS 14n
 145 Bit field that instructs the driver on how to open the device. Valid settings
 146 are:
 147 .sp
 148 .ne 2
 149 .na
 150 \fBFEXCL\fR
 151 .ad
 152 .RS 11n
 153 Open the device with exclusive access; fail all other attempts to open the
 154 device.
 155 .RE
 156
 157 .sp
 158 .ne 2
 159 .na
 160 \fBFNDELAY\fR
 161 .ad
 162 .RS 11n
 163 Open the device and return immediately.  Do not block the open even if
 164 something is wrong.
 165 .RE
 166
 167 .sp
 168 .ne 2
 169 .na
 170 \fBFREAD\fR
 171 .ad
 172 .RS 11n
 173 Open the device with read-only permission. (If ORed with \fBFWRITE\fR, allow
 174 both read and write access).
 175 .RE
 176
 177 .sp
 178 .ne 2
 179 .na
 180 \fBFWRITE\fR
 181 .ad
 182 .RS 11n
 183 Open a device with write-only permission (if ORed with \fBFREAD\fR, then allow
 184 both read and write access).
 185 .RE
 186
 187 .sp
 188 .ne 2
 189 .na
 190 \fBFNOCTTY\fR
 191 .ad
 192 .RS 11n
 193 Open the device. If the device is a tty, do not attempt to open it as a
 194 session-controlling tty.
 195 .RE
 196
 197 .RE
 198
 199 .SH DESCRIPTION
 200 .sp
 201 .LP
 202 The \fBldi_open_by_dev()\fR, \fBldi_open_by_name()\fR and
 203 \fBldi_open_by_devid()\fR functions allow a caller to open a block, character,
 204 or streams device. Upon a successful open, a layered handle to the device is
 205 returned via the layered handle pointed to by \fIlhp\fR. The ldi identifier
 206 passed to these functions is previously allocated with
 207 \fBldi_ident_from_stream\fR(9F), \fBldi_ident_from_dev\fR(9F), and
 208 \fBldi_ident_from_dip\fR(9F).
 209 .sp
 210 .LP
 211 The \fBldi_open_by_dev()\fR function opens a device specified by the dev_t
 212 pointed to by devp.  Upon successful open, the caller should check the value of
 213 the dev_t to see if it has changed. (Cloning devices will change this value
 214 during opens.)   When opening a streams device, otyp must be OTYP_CHR.
 215 .sp
 216 .LP
 217 The \fBldi_open_by_devid()\fR function opens a device by devid. The caller must
 218 specify the minor node name to open.
 219 .sp
 220 .LP
 221 The \fBldi_open_by_name()\fR function opens a device by pathname. Pathname is a
 222 null terminated string in the kernel address space. Pathname must be an
 223 absolute path, meaning that it must begin with '/'. The format of the pathname
 224 supplied to this function is either a \fB/devices\fR path or any other
 225 filesystem path to a device node. Opens utilizing \fB/devices\fR paths are
 226 supported before root is mounted. Opens utilizing other filesystem paths to
 227 device nodes are supported only if root is already mounted.
 228 .sp
 229 .LP
 230 The \fBldi_close()\fR function closes a layered handle that was obtained with
 231 either \fBldi_open_by_dev()\fR, \fBldi_open_by_name()\fR, or
 232 \fBldi_open_by_devid()\fR. After \fBldi_close()\fR returns the layered handle,
 233 the \fIlh\fR that was previously passed in is no longer valid.
 234 .SH RETURN VALUES
 235 .sp
 236 .LP
 237 The \fBldi_close()\fR function returns \fB0\fR for success. \fBEINVAL\fR is
 238 returned for invalid input parameters. Otherwise, any other error number may be
 239 returned by the device.
 240 .sp
 241 .LP
 242 The \fBldi_open_by_dev()\fR and \fBldi_open_by_devid()\fR functions return
 243 \fB0\fR upon success. If a failure occurs before the device is open, possible
 244 return values are shown below. Otherwise any other error number may be returned
 245 by the device.
 246 .sp
 247 .ne 2
 248 .na
 249 \fBEINVAL\fR
 250 .ad
 251 .RS 10n
 252 Invalid input parameters.
 253 .RE
 254
 255 .sp
 256 .ne 2
 257 .na
 258 \fBENODEV\fR
 259 .ad
 260 .RS 10n
 261 Requested device does not exist.
 262 .RE
 263
 264 .sp
 265 .ne 2
 266 .na
 267 \fBENXIO\fR
 268 .ad
 269 .RS 10n
 270 Unsupported device operation or access mode.
 271 .RE
 272
 273 .sp
 274 .LP
 275 The \fBldi_open_by_name()\fR function returns \fB0\fR upon success. If a
 276 failure occurs before the device is open, possible return values are shown
 277 below. Otherwise any other error number may be returned by the device.
 278 .sp
 279 .ne 2
 280 .na
 281 \fBEINVAL\fR
 282 .ad
 283 .RS 10n
 284 Invalid input parameters.
 285 .RE
 286
 287 .sp
 288 .ne 2
 289 .na
 290 \fBENODEV\fR
 291 .ad
 292 .RS 10n
 293 Requested device path does not exist.
 294 .RE
 295
 296 .sp
 297 .ne 2
 298 .na
 299 \fBEACCES\fR
 300 .ad
 301 .RS 10n
 302 Search permission is denied on a component of the path prefix, or the file
 303 exists and the permissions specified by \fIcr\fR are denied.
 304 .RE
 305
 306 .sp
 307 .ne 2
 308 .na
 309 \fBENXIO\fR
 310 .ad
 311 .RS 10n
 312 Unsupported device operation or access mode.
 313 .RE
 314
 315 .SH CONTEXT
 316 .sp
 317 .LP
 318 These functions may be called from user or kernel context.
 319 .sp
 320 .LP
 321 These functions should not be called from a device's attach, detach, or power
 322 entry point. This could result in a system crash or deadlock.
 323 .SH SEE ALSO
 324 .sp
 325 .LP
 326 \fBscsi_vhci\fR(7D), \fBldi_ident_from_dev\fR(9F),
 327 \fBldi_ident_from_dip\fR(9F), \fBldi_ident_from_stream\fR(9F)
 328 .SH NOTES
 329 .sp
 330 .LP
 331 Use only OTYP_CHR or OTYP_BLK options when you use the \fBldi_open_by_dev()\fR
 332 and \fBldi_open_by_devid()\fR functions to open a device. Other flags,
 333 including OTYP_LYR, have been deprecated and should not be used with these
 334 interfaces.
 335 .sp
 336 .LP
 337 The caller should be aware of cases when multiple paths to a single device may
 338 exist.  (This can occur for scsi disk devices if \fBscsi_vhci\fR(7D)) is
 339 disabled or a disk is connected to multiple controllers not supported by
 340 scsi_vhci(7D).
 341 .sp
 342 .LP
 343 In these cases, \fBldi_open_by_devid()\fR returns a device handle that
 344 corresponds to a  particular path to a target device. This path may not be the
 345 same across multiple calls to \fBldi_open_by_devid()\fR.  Device handles
 346 associated  with the same device but different access paths should have
 347 different filesystem device paths and dev_t values.
 348 .sp
 349 .LP
 350 In the cases where multiple paths to a device exist and access to the device
 351 has not been virtualized via MPXIO (as with scsi disk devices not accessed via
 352 \fBscsi_vhci\fR(7D)), the LDI does not provide any path fail-over capabilities.
 353 If the caller wishes to do their own path management and failover they should
 354 open all available paths to a device via \fBldi_open_by_name()\fR.