share/man/man9/resource_query_string.9

   1 .\" -*- nroff -*-
   2 .\"
   3 .\" Copyright (c) 2001 M. Warner Losh
   4 .\"
   5 .\" All rights reserved.
   6 .\"
   7 .\" This program is free software.
   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 DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
  19 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  20 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  21 .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
  22 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  23 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  24 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  25 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  26 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  27 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  28 .\"
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd March 1, 2001
  32 .Dt RESOURCE_QUERY_STRING 9
  33 .Os
  34 .Sh NAME
  35 .Nm resource_query_string , resource_query_name , resource_query_unit
  36 .Nd query the
  37 .Dq hints
  38 database for matches
  39 .Sh SYNOPSIS
  40 .In sys/bus.h
  41 .Ft int
  42 .Fn resource_query_string "int num" "const char *field" "const char *what"
  43 .Ft char *
  44 .Fn resource_query_name "int num"
  45 .Ft int
  46 .Fn resource_query_unit "int num"
  47 .Sh DESCRIPTION
  48 .Fn resource_query_string
  49 enumerates all devices in the
  50 .Dq hints
  51 database whose
  52 .Fa field
  53 value matches the
  54 .Fa what
  55 parameter.
  56 A cookie is returned for use as the
  57 .Fa num
  58 parameter in calls to
  59 .Fn resource_query_name
  60 and
  61 .Fn resource_query_unit .
  62 This cookie should be passed as the
  63 .Fa num
  64 parameter on subsequent calls.
  65 A return value of \-1 means no further matches exist.
  66 .Pp
  67 .Fn resource_query_name
  68 returns the name of the device matched by
  69 .Fn resource_query_string .
  70 .Pp
  71 .Fn resource_query_unit
  72 returns the unit of the device matched by
  73 .Fn resource_query_string .
  74 .Pp
  75 The functions take the following arguments:
  76 .Bl -tag -width "field"
  77 .It Fa num
  78 is the
  79 .Dq index
  80 of the item to lookup.
  81 Set to \-1 for the first call, and the return value of the previous
  82 .Fn resource_query_string
  83 on subsequent calls.
  84 The
  85 .Dq index
  86 is an opaque cookie.
  87 .It Fa field
  88 is the name of the field in the
  89 .Dq hints
  90 database to query.
  91 .It Fa what
  92 is the value of
  93 .Fa field
  94 in the
  95 .Dq hints
  96 database for which to search.
  97 .El
  98 .Sh RETURN VALUES
  99 .Fn resource_query_string
 100 returns \-1 on failure, otherwise a cookie to pass to
 101 .Fn resource_query_name
 102 or
 103 .Fn resource_query_unit .
 104 .Pp
 105 .Fn resource_query_name
 106 returns the device name matching the cookie.
 107 .Pp
 108 .Fn resource_query_unit
 109 returns the device unit number matching the cookie.
 110 .Sh EXAMPLES
 111 The following example will return all the
 112 .Dq hints
 113 that say they are
 114 .Dq Li "at gerbil0" .
 115 .Pp
 116 An example hint would be:
 117 .Bd -literal -offset indent
 118 hint.habitat.0.at="gerbil0"
 119 hint.ewheel.0.at="gerbil0"
 120 hint.fred.0.at="nexus"
 121 .Ed
 122 .Pp
 123 The following code
 124 .Bd -literal -offset indent
 125 int i = -1;
 126 while ((i = resource_query_string(i, "at", "gerbil0")) != -1) {
 127         printf("Found %s%d at gerbil0\en", resource_query_name(i),
 128             resource_query_unit(i));
 129 }
 130 .Ed
 131 .Pp
 132 would produce two lines:
 133 .Bd -literal -offset indent
 134 Found habitat0 at gerbil0
 135 Found ewheel0 at gerbil0
 136 .Ed
 137 .Sh SEE ALSO
 138 .Xr device 9 ,
 139 .Xr driver 9 ,
 140 .Xr resource_int_value 9
 141 .Sh AUTHORS
 142 This manual page was written by
 143 .An Warner Losh Aq imp@FreeBSD.org .