man/waffle_attrib_list.3.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   Copyright Intel 2012
   7
   8   This manual page is licensed under the Creative Commons Attribution-ShareAlike 3.0 United States License (CC BY-SA 3.0
   9   US). To view a copy of this license, visit http://creativecommons.org.license/by-sa/3.0/us.
  10 -->
  11
  12 <refentry
  13     id="waffle_attrib_list"
  14     xmlns:xi="http://www.w3.org/2001/XInclude">
  15
  16   <!-- See http://www.docbook.org/tdg/en/html/refentry.html. -->
  17
  18   <refmeta>
  19     <refentrytitle>waffle_attrib_list</refentrytitle>
  20     <manvolnum>3</manvolnum>
  21   </refmeta>
  22
  23   <refnamediv>
  24     <refname>waffle_attrib_list</refname>
  25     <refname>waffle_attrib_list_length</refname>
  26     <refname>waffle_attrib_list_get</refname>
  27     <refname>waffle_attrib_list_get_with_default</refname>
  28     <refname>waffle_attrib_list_update</refname>
  29     <refpurpose>Utilities for attribute lists</refpurpose>
  30   </refnamediv>
  31
  32   <refentryinfo>
  33     <title>Waffle Manual</title>
  34     <productname>waffle</productname>
  35     <xi:include href="common/author-chad.versace.xml"/>
  36     <xi:include href="common/copyright.xml"/>
  37     <xi:include href="common/legalnotice.xml"/>
  38   </refentryinfo>
  39
  40   <refsynopsisdiv>
  41
  42     <funcsynopsis language="C">
  43
  44       <funcsynopsisinfo>#include &lt;waffle.h&gt;</funcsynopsisinfo>
  45
  46       <funcprototype>
  47         <funcdef>DEPRECATED bool <function>waffle_attrib_list_length</function></funcdef>
  48         <paramdef>const int32_t <parameter>attrib_list</parameter>[]</paramdef>
  49       </funcprototype>
  50
  51       <funcprototype>
  52         <funcdef>DEPRECATED bool <function>waffle_attrib_list_get</function></funcdef>
  53         <paramdef>const int32_t <parameter>attrib_list</parameter>[]</paramdef>
  54         <paramdef>int32_t <parameter>key</parameter></paramdef>
  55         <paramdef>int32_t *<parameter>value</parameter></paramdef>
  56       </funcprototype>
  57
  58       <funcprototype>
  59         <funcdef>DEPRECATED bool <function>waffle_attrib_list_get_with_default</function></funcdef>
  60         <paramdef>const int32_t <parameter>attrib_list</parameter>[]</paramdef>
  61         <paramdef>int32_t <parameter>key</parameter></paramdef>
  62         <paramdef>int32_t *<parameter>value</parameter></paramdef>
  63         <paramdef>int32_t <parameter>default_value</parameter></paramdef>
  64       </funcprototype>
  65
  66       <funcprototype>
  67         <funcdef>DEPRECATED bool <function>waffle_attrib_list_update</function></funcdef>
  68         <paramdef>int32_t <parameter>attrib_list</parameter>[]</paramdef>
  69         <paramdef>int32_t <parameter>key</parameter></paramdef>
  70         <paramdef>int32_t *<parameter>value</parameter></paramdef>
  71       </funcprototype>
  72
  73     </funcsynopsis>
  74
  75     <refsect2>
  76       <title>Deprecation</title>
  77       <para>All functions above are deprecated in Waffle 1.6 and later.</para>
  78     </refsect2>
  79
  80   </refsynopsisdiv>
  81
  82   <refsect1>
  83     <title>Description</title>
  84
  85     <para>
  86       An attribute list is a zero-terminated list of <type>int32_t</type> key/value pairs or a null pointer. A null
  87       pointer is interpreted as an empty list, whose only member is the terminal zero. For concrete examples of
  88       attribute lists, see the "Examples" section in
  89       <citerefentry><refentrytitle><function>waffle_config</function></refentrytitle><manvolnum>3</manvolnum></citerefentry>.
  90     </para>
  91
  92     <para>
  93       All attribute list functions can be called before waffle has been successfully initialized with
  94       <citerefentry><refentrytitle><function>waffle_init</function></refentrytitle><manvolnum>3</manvolnum></citerefentry>.
  95     </para>
  96
  97     <variablelist>
  98
  99       <varlistentry>
 100         <term><function>waffle_attrib_list_length()</function></term>
 101         <listitem>
 102           <para>
 103             Return the number of key/value pairs in the list.
 104           </para>
 105         </listitem>
 106       </varlistentry>
 107
 108       <varlistentry>
 109         <term><function>waffle_attrib_list_get()</function></term>
 110         <listitem>
 111           <para>
 112             Get the <parameter>value</parameter> associated with <parameter>key</parameter>.  If the list does not
 113             contain the <parameter>key</parameter>, then <parameter>value</parameter> is not dereferenced.
 114             Return true if and only if the list contains the <parameter>key</parameter>.
 115           </para>
 116         </listitem>
 117       </varlistentry>
 118
 119       <varlistentry>
 120         <term><function>waffle_attrib_list_get_with_default()</function></term>
 121         <listitem>
 122           <para>
 123             Equivalent to <function>waffle_attrib_list_get()</function> except that if the list does not contain the
 124             <parameter>key</parameter> then <parameter>value</parameter> is set to a <parameter>default_value</parameter>.
 125           </para>
 126         </listitem>
 127       </varlistentry>
 128
 129       <varlistentry>
 130         <term><function>waffle_attrib_list_update()</function></term>
 131         <listitem>
 132           <para>
 133             Update the <parameter>value</parameter> associated with <parameter>key</parameter>.
 134             If the list does not contain the <parameter>key</parameter> then the list is not modified.
 135             Return true if and only if the list contains the <parameter>key</parameter>.
 136           </para>
 137         </listitem>
 138       </varlistentry>
 139
 140     </variablelist>
 141   </refsect1>
 142
 143   <refsect1>
 144     <title>Errors</title>
 145
 146     <para>
 147       All attribute list functions set the error code to <constant>WAFFLE_NO_ERROR</constant> and can be called before
 148       waffle has been successfully initialized with
 149       <citerefentry><refentrytitle><function>waffle_init</function></refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 150     </para>
 151
 152     <xi:include href="common/error-codes.xml"/>
 153
 154   </refsect1>
 155
 156   <xi:include href="common/issues.xml"/>
 157
 158   <refsect1>
 159     <title>See Also</title>
 160     <para>
 161       <citerefentry><refentrytitle>waffle</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 162     </para>
 163   </refsect1>
 164
 165 </refentry>
 166
 167 <!--
 168 vim:tw=120 et ts=2 sw=2:
 169 -->