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>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>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>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>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   </refsynopsisdiv>
  75
  76   <refsect1>
  77     <title>Description</title>
  78
  79     <para>
  80       An attribute list is a zero-terminated list of <type>int32_t</type> key/value pairs or a null pointer. A null
  81       pointer is interpreted as an empty list, whose only member is the terminal zero. For concrete examples of
  82       attribute lists, see the "Examples" section in
  83       <citerefentry><refentrytitle><function>waffle_config</function></refentrytitle><manvolnum>3</manvolnum></citerefentry>.
  84     </para>
  85
  86     <para>
  87       All attribute list functions can be called before waffle has been successfully initialized with
  88       <citerefentry><refentrytitle><function>waffle_init</function></refentrytitle><manvolnum>3</manvolnum></citerefentry>.
  89     </para>
  90
  91     <variablelist>
  92
  93       <varlistentry>
  94         <term><function>waffle_attrib_list_length()</function></term>
  95         <listitem>
  96           <para>
  97             Return the number of key/value pairs in the list.
  98           </para>
  99         </listitem>
 100       </varlistentry>
 101
 102       <varlistentry>
 103         <term><function>waffle_attrib_list_get()</function></term>
 104         <listitem>
 105           <para>
 106             Get the <parameter>value</parameter> associated with <parameter>key</parameter>.  If the list does not
 107             contain the <parameter>key</parameter>, then <parameter>value</parameter> is not dereferenced.
 108             Return true if and only if the list contains the <parameter>key</parameter>.
 109           </para>
 110         </listitem>
 111       </varlistentry>
 112
 113       <varlistentry>
 114         <term><function>waffle_attrib_list_get_with_default()</function></term>
 115         <listitem>
 116           <para>
 117             Equivalent to <function>waffle_attrib_list_get()</function> except that if the list does not contain the
 118             <parameter>key</parameter> then <parameter>value</parameter> is set to a <parameter>default_value</parameter>.
 119           </para>
 120         </listitem>
 121       </varlistentry>
 122
 123       <varlistentry>
 124         <term><function>waffle_attrib_list_update()</function></term>
 125         <listitem>
 126           <para>
 127             Update the <parameter>value</parameter> associated with <parameter>key</parameter>.
 128             If the list does not contain the <parameter>key</parameter> then the list is not modified.
 129             Return true if and only if the list contains the <parameter>key</parameter>.
 130           </para>
 131         </listitem>
 132       </varlistentry>
 133
 134     </variablelist>
 135   </refsect1>
 136
 137   <refsect1>
 138     <title>Errors</title>
 139
 140     <para>
 141       All attribute list functions set the error code to <constant>WAFFLE_NO_ERROR</constant> and can be called before
 142       waffle has been successfully initialized with
 143       <citerefentry><refentrytitle><function>waffle_init</function></refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 144     </para>
 145
 146     <xi:include href="common/error-codes.xml"/>
 147
 148   </refsect1>
 149
 150   <xi:include href="common/issues.xml"/>
 151
 152   <refsect1>
 153     <title>See Also</title>
 154     <para>
 155       <citerefentry><refentrytitle>waffle</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 156     </para>
 157   </refsect1>
 158
 159 </refentry>
 160
 161 <!--
 162 vim:tw=120 et ts=2 sw=2:
 163 -->