1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
|
<refentry id="libuser-value">
<refmeta>
<refentrytitle role="top_of_page">value</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>LIBUSER Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>value</refname>
<refpurpose>Simplified interface to GValue types used in libuser entities.</refpurpose>
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
</refnamediv>
<refsynopsisdiv role="synopsis">
<title role="synopsis.title">Synopsis</title>
<synopsis>
#define <link linkend="LU-VALUE-INVALID-ID:CAPS">LU_VALUE_INVALID_ID</link>
<link linkend="char">char</link>* <link linkend="lu-value-strdup">lu_value_strdup</link> (const <link linkend="GValue">GValue</link> *value);
<link linkend="gboolean">gboolean</link> <link linkend="lu-value-init-set-attr-from-string">lu_value_init_set_attr_from_string</link> (<link linkend="GValue">GValue</link> *value,
const <link linkend="char">char</link> *attr,
const <link linkend="char">char</link> *string,
<link linkend="lu-error-t">lu_error_t</link> **error);
<link linkend="void">void</link> <link linkend="lu-value-init-set-id">lu_value_init_set_id</link> (<link linkend="GValue">GValue</link> *value,
<link linkend="id-t">id_t</link> id);
<link linkend="id-t">id_t</link> <link linkend="lu-value-get-id">lu_value_get_id</link> (const <link linkend="GValue">GValue</link> *value);
<link linkend="int">int</link> <link linkend="lu-values-equal">lu_values_equal</link> (const <link linkend="GValue">GValue</link> *a,
const <link linkend="GValue">GValue</link> *b);
</synopsis>
</refsynopsisdiv>
<refsect1 role="desc">
<title role="desc.title">Description</title>
<para>
Libuser entities store attribute values as <link linkend="GValue"><type>GValue</type></link>, which allows representing
any possible data type. Only a few types are needed in practice; the only
types applications should hard-code are <link linkend="G-TYPE-LONG:CAPS"><literal>G_TYPE_LONG</literal></link> and <link linkend="G-TYPE-STRING:CAPS"><literal>G_TYPE_STRING</literal></link>
(<link linkend="G-TYPE-STRING:CAPS"><literal>G_TYPE_STRING</literal></link> can usually be used as a fallback for other number types).
</para>
<para>
The only currently used data types that are not conveniently supported using
the above types are <link linkend="uid-t"><type>uid_t</type></link> and <link linkend="gid-t"><type>gid_t</type></link> (which can be together represented in
<link linkend="id-t"><type>id_t</type></link>), because they can support values outside of the range of <link linkend="glong"><type>glong</type></link>. Helper
functions are provided to convert values between <link linkend="id-t"><type>id_t</type></link> and <link linkend="GValue"><type>GValue</type></link>, even if the
value is stored using <link linkend="G-TYPE-STRING:CAPS"><literal>G_TYPE_STRING</literal></link>. The <link linkend="GValue"><type>GValue</type></link> types used for storing <link linkend="id-t"><type>id_t</type></link>
values are an internal implementation detail of libuser and applications should
not rely on them.
</para>
<para>
Values of each attribute are expected to have a specific type, documented in
the documentation of the specific attribute name. Using other types (e.g.
using <link linkend="G-TYPE-STRING:CAPS"><literal>G_TYPE_STRING</literal></link> for <link linkend="LU-UIDNUMBER:CAPS"><literal>LU_UIDNUMBER</literal></link>) is not allowed and results in undefined
behavior.. You can use <link linkend="lu-value-strdup"><function>lu_value_strdup()</function></link> and
<link linkend="lu-value-init-set-attr-from-string"><function>lu_value_init_set_attr_from_string()</function></link> for conversion between strings and values
appropriate for a specific attribute.
</para>
</refsect1>
<refsect1 role="details">
<title role="details.title">Details</title>
<refsect2>
<title><anchor id="LU-VALUE-INVALID-ID:CAPS" role="macro"/>LU_VALUE_INVALID_ID</title>
<indexterm><primary>LU_VALUE_INVALID_ID</primary></indexterm><programlisting>#define LU_VALUE_INVALID_ID ((id_t)-1)
</programlisting>
<para>
An <link linkend="id-t"><type>id_t</type></link> value that matches no valid user or group ID.
</para></refsect2>
<refsect2>
<title><anchor id="lu-value-strdup" role="function"/>lu_value_strdup ()</title>
<indexterm><primary>lu_value_strdup</primary></indexterm><programlisting><link linkend="char">char</link>* lu_value_strdup (const <link linkend="GValue">GValue</link> *value);</programlisting>
<para>
Converts <parameter>value</parameter>, of any type used by libuser, to a string. Preferable
to hard-coding checks for expected value types.
</para><variablelist role="params">
<varlistentry><term><parameter>value</parameter> :</term>
<listitem><simpara>value
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>string, should be freed by <link linkend="g-free"><function>g_free()</function></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="lu-value-init-set-attr-from-string" role="function"/>lu_value_init_set_attr_from_string ()</title>
<indexterm><primary>lu_value_init_set_attr_from_string</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> lu_value_init_set_attr_from_string (<link linkend="GValue">GValue</link> *value,
const <link linkend="char">char</link> *attr,
const <link linkend="char">char</link> *string,
<link linkend="lu-error-t">lu_error_t</link> **error);</programlisting>
<para>
Initializes a zero-filled (uninitialized) <parameter>value</parameter> for storing a value of
attribute <parameter>attr</parameter> and sets it to the contents of <parameter>string</parameter>. To see whether a
specific type is used for an attribute, see the documentation of that
attribute.
</para><variablelist role="params">
<varlistentry><term><parameter>value</parameter> :</term>
<listitem><simpara><link linkend="GValue"><type>GValue</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>attr</parameter> :</term>
<listitem><simpara>attribute name
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>string</parameter> :</term>
<listitem><simpara>the string to convert
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>error</parameter> :</term>
<listitem><simpara>filled with a <link linkend="lu-error"><type>lu_error</type></link> if an error occurs, or <link linkend="NULL:CAPS"><literal>NULL</literal></link> if <parameter>attr</parameter> is
unknown
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara><link linkend="TRUE:CAPS"><literal>TRUE</literal></link> on success, <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> on error or if <parameter>attr</parameter> is unknown
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="lu-value-init-set-id" role="function"/>lu_value_init_set_id ()</title>
<indexterm><primary>lu_value_init_set_id</primary></indexterm><programlisting><link linkend="void">void</link> lu_value_init_set_id (<link linkend="GValue">GValue</link> *value,
<link linkend="id-t">id_t</link> id);</programlisting>
<para>
Initializes a zero-filled (uninitialized) <parameter>value</parameter> with an unspecified type and
sets it to <parameter>id</parameter>.
</para><variablelist role="params">
<varlistentry><term><parameter>value</parameter> :</term>
<listitem><simpara><link linkend="GValue"><type>GValue</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>id</parameter> :</term>
<listitem><simpara>user or group ID.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="lu-value-get-id" role="function"/>lu_value_get_id ()</title>
<indexterm><primary>lu_value_get_id</primary></indexterm><programlisting><link linkend="id-t">id_t</link> lu_value_get_id (const <link linkend="GValue">GValue</link> *value);</programlisting>
<para>
Get the contents of <parameter>value</parameter>. <parameter>value</parameter> should be initialized by
<link linkend="lu-value-init-set-id"><function>lu_value_init_set_id()</function></link> or use <link linkend="G-TYPE-LONG:CAPS"><literal>G_TYPE_LONG</literal></link> or <link linkend="G-TYPE-STRING:CAPS"><literal>G_TYPE_STRING</literal></link>.
</para>
<para>
If <parameter>value</parameter> does not contain a valid <link linkend="id-t"><type>id_t</type></link> value, <link linkend="LU-VALUE-INVALID-ID:CAPS"><literal>LU_VALUE_INVALID_ID</literal></link>
is returned.
</para><variablelist role="params">
<varlistentry><term><parameter>value</parameter> :</term>
<listitem><simpara><link linkend="GValue"><type>GValue</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>ID value or <link linkend="LU-VALUE-INVALID-ID:CAPS"><literal>LU_VALUE_INVALID_ID</literal></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="lu-values-equal" role="function"/>lu_values_equal ()</title>
<indexterm><primary>lu_values_equal</primary></indexterm><programlisting><link linkend="int">int</link> lu_values_equal (const <link linkend="GValue">GValue</link> *a,
const <link linkend="GValue">GValue</link> *b);</programlisting>
<para>
Check whether <parameter>a</parameter> and <parameter>b</parameter> have the same type and value.
</para><variablelist role="params">
<varlistentry><term><parameter>a</parameter> :</term>
<listitem><simpara><link linkend="GValue"><type>GValue</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>b</parameter> :</term>
<listitem><simpara><link linkend="GValue"><type>GValue</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara><link linkend="TRUE:CAPS"><type>TRUE</type></link> if <parameter>a</parameter> and <parameter>b</parameter> have the same type and value
</simpara></listitem></varlistentry>
</variablelist></refsect2>
</refsect1>
<refsect1><refsect2 /><refsect2 /></refsect1>
</refentry>
|
