share/man/man3devinfo/di_prom_prop_lookup_bytes.3devinfo

   1 '\" te
   2 .\" Copyright (c) 1998, 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 DI_PROM_PROP_LOOKUP_BYTES 3DEVINFO "Dec 1, 1998"
   7 .SH NAME
   8 di_prom_prop_lookup_bytes, di_prom_prop_lookup_ints,
   9 di_prom_prop_lookup_strings \- search for a PROM property
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 \fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-ldevinfo\fR [ \fIlibrary\fR... ]
  14 #include <libdevinfo.h>
  15
  16 \fBint\fR \fBdi_prom_prop_lookup_bytes\fR(\fBdi_prom_handle_t\fR \fIph\fR, \fBdi_node_t\fR \fInode\fR,
  17      \fBconst char *\fR\fIprop_name\fR, \fBuchar_t **\fR\fIprop_data\fR);
  18 .fi
  19
  20 .LP
  21 .nf
  22 \fBint\fR \fBdi_prom_prop_lookup_ints\fR(\fBdi_prom_handle_t\fR \fIph\fR, \fBdi_node_t\fR \fInode\fR,
  23      \fBconst char *\fR\fIprop_name\fR, \fBint **\fR\fIprop_data\fR);
  24 .fi
  25
  26 .LP
  27 .nf
  28 \fBint\fR \fBdi_prom_prop_lookup_strings\fR(\fBdi_prom_handle_t\fR \fIph\fR, \fBdi_node_t\fR \fInode\fR,
  29      \fBconst char *\fR\fIprop_name\fR, \fBchar **\fR\fIprop_data\fR);
  30 .fi
  31
  32 .SH PARAMETERS
  33 .sp
  34 .ne 2
  35 .na
  36 \fB\fInode\fR\fR
  37 .ad
  38 .RS 13n
  39 Handle to device node in snapshot created by \fBdi_init\fR(3DEVINFO).
  40 .RE
  41
  42 .sp
  43 .ne 2
  44 .na
  45 \fB\fIph\fR\fR
  46 .ad
  47 .RS 13n
  48 Handle returned by \fBdi_prom_init\fR(3DEVINFO).
  49 .RE
  50
  51 .sp
  52 .ne 2
  53 .na
  54 \fB\fIprop_data\fR\fR
  55 .ad
  56 .RS 13n
  57 For \fBdi_prom_prop_lookup_bytes()\fR, the address of a pointer to an array of
  58 unsigned characters.
  59 .sp
  60 For \fBdi_prom_prop_lookup_ints()\fR, the address of a pointer to an integer.
  61 .sp
  62 For \fBdi_prom_prop_lookup_strings()\fR, the address of pointer to a buffer.
  63 .RE
  64
  65 .sp
  66 .ne 2
  67 .na
  68 \fB\fIprop_name\fR\fR
  69 .ad
  70 .RS 13n
  71 The name of the property being searched.
  72 .RE
  73
  74 .SH DESCRIPTION
  75 .sp
  76 .LP
  77 These functions return the value of a known \fBPROM\fR property name and value
  78 type and update the \fIprop_data\fR pointer to reference memory that contains
  79 the property value. All memory allocated by these functions is managed by the
  80 library and must not be freed by the caller.
  81 .SH RETURN VALUES
  82 .sp
  83 .LP
  84 If the property is found, the number of entries in \fIprop_data\fR is returned.
  85 If the property is a boolean type, 0 is returned and the existence of this
  86 property indicates the value is true. Otherwise, -1 is returned and \fIerrno\fR
  87 is set to indicate the error.
  88 .sp
  89 .LP
  90 For \fBdi_prom_prop_lookup_bytes()\fR, the number of entries is the number of
  91 unsigned characters contained in the buffer pointed to by \fIprop_data\fR.
  92 .sp
  93 .LP
  94 For \fBdi_prom_prop_lookup_ints()\fR, the number of entries is the number of
  95 integers contained in the buffer pointed to by \fIprop_data\fR.
  96 .sp
  97 .LP
  98 For \fBdi_prom_prop_lookup_strings()\fR, the number of entries is the number of
  99 null-terminated strings contained in the buffer. The strings are stored in a
 100 concatenated format in the buffer.
 101 .SH ERRORS
 102 .sp
 103 .LP
 104 These functions will fail if::
 105 .sp
 106 .ne 2
 107 .na
 108 \fB\fBEINVAL\fR\fR
 109 .ad
 110 .RS 10n
 111 Invalid argument.
 112 .RE
 113
 114 .sp
 115 .ne 2
 116 .na
 117 \fB\fBENXIO\fR\fR
 118 .ad
 119 .RS 10n
 120 The property does not exist.
 121 .RE
 122
 123 .SH ATTRIBUTES
 124 .sp
 125 .LP
 126 See \fBattributes\fR(5)  for descriptions of the following attributes:
 127 .sp
 128
 129 .sp
 130 .TS
 131 box;
 132 c | c
 133 l | l .
 134 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 135 _
 136 Interface Stability     Evolving
 137 _
 138 MT-Level        Safe
 139 .TE
 140
 141 .SH SEE ALSO
 142 .sp
 143 .LP
 144 \fBdi_init\fR(3DEVINFO), \fBdi_prom_prop_next\fR(3DEVINFO),
 145 \fBlibdevinfo\fR(3LIB), \fBattributes\fR(5), \fBopenprom\fR(7D)
 146 .sp
 147 .LP
 148 \fIWriting Device Drivers\fR