util/opendev.3

   1 .\"     $OpenBSD: opendev.3,v 1.15 2002/05/01 08:03:30 mpech Exp $
   2 .\"
   3 .\" Copyright (c) 2000, Todd C. Miller.  All rights reserved.
   4 .\" Copyright (c) 1996, Jason Downs.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR(S) ``AS IS'' AND ANY EXPRESS
  16 .\" OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  17 .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  18 .\" DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY DIRECT,
  19 .\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  20 .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
  21 .\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
  22 .\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  25 .\" SUCH DAMAGE.
  26 .\"
  27 .Dd December 12, 2002
  28 .Dt OPENDEV 3
  29 .Os
  30 .Sh NAME
  31 .Nm opendev
  32 .Nd short form device open routine
  33 .Sh SYNOPSIS
  34 .Fd #include <util.h>
  35 .Ft int
  36 .Fn opendev "char *path" "int oflags" "int dflags" "char **realpath"
  37 .Sh DESCRIPTION
  38 The
  39 .Fn opendev
  40 function opens a device using the
  41 .Dq short form
  42 name.
  43 This is typically
  44 .Dq disk0s3 ,
  45 for instance, which will be expanded to
  46 .Pa /dev/rdisk0s3
  47 on most architectures.
  48 .Pp
  49 Device name lookup is done by first checking
  50 .Fa path
  51 for a
  52 .Dq /
  53 and if one is found attempting to open that file.
  54 Otherwise
  55 .Fa /dev
  56 is searched for a matching device.
  57 .Pp
  58 The
  59 .Fa oflags
  60 are the same as the
  61 .Fa flags
  62 passed to
  63 .Xr open 2 .
  64 .Pp
  65 The
  66 .Fa dflags
  67 are specified by
  68 .Tn OR Ns 'ing
  69 the following values:
  70 .Pp
  71 .Bd -literal -offset indent -compact
  72 OPENDEV_PART    attempt to open the raw partition during expansion
  73 OPENDEV_BLCK    open the block device (default is character device)
  74 .Ed
  75 .Pp
  76 The
  77 .Dq raw
  78 partition is defined as the partition which provides access to the entire
  79 disk, regardless of the disk's partition map.
  80 .Pp
  81 If
  82 .Fa realpath
  83 is not
  84 .Dv NULL ,
  85 it is modified to point at the fully expanded device name.
  86 .Sh RETURN VALUES
  87 The
  88 .Fn opendev
  89 return value and errors are the same as the return value and errors of
  90 .Xr open 2 .
  91 .Sh WARNINGS
  92 If
  93 .Fa realpath
  94 is not
  95 .Dv NULL ,
  96 on return it will point to internal
  97 static storage space that will be overwritten by subsequent calls.
  98 .Sh SEE ALSO
  99 .Xr open 2
 100 .Sh HISTORY
 101 The
 102 .Fn opendev
 103 function first appeared in
 104 .Ox 1.2 .