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
|
<refentry id="libuser-error">
<refmeta>
<refentrytitle role="top_of_page">error</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>LIBUSER Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>error</refname>
<refpurpose>Functions for allocating and manipulating <link linkend="lu-error"><type>lu_error</type></link> structures.</refpurpose>
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
</refnamediv>
<refsynopsisdiv role="synopsis">
<title role="synopsis.title">Synopsis</title>
<synopsis>
#define <link linkend="LU-ERROR-CHECK:CAPS">LU_ERROR_CHECK</link> (err_p_p)
<link linkend="void">void</link> <link linkend="lu-error-new">lu_error_new</link> (<link linkend="lu-error-t">lu_error_t</link> **error,
<link linkend="lu-status-t">lu_status_t</link> code,
const <link linkend="char">char</link> *fmt,
...);
<link linkend="void">void</link> <link linkend="lu-error-free">lu_error_free</link> (<link linkend="lu-error-t">lu_error_t</link> **error);
<link linkend="gboolean">gboolean</link> <link linkend="lu-error-is-success">lu_error_is_success</link> (<link linkend="lu-status-t">lu_status_t</link> status);
<link linkend="gboolean">gboolean</link> <link linkend="lu-error-is-warning">lu_error_is_warning</link> (<link linkend="lu-status-t">lu_status_t</link> status);
<link linkend="gboolean">gboolean</link> <link linkend="lu-error-is-error">lu_error_is_error</link> (<link linkend="lu-status-t">lu_status_t</link> status);
const <link linkend="char">char</link>* <link linkend="lu-strerror">lu_strerror</link> (<link linkend="lu-error-t">lu_error_t</link> *error);
</synopsis>
</refsynopsisdiv>
<refsect1 role="desc">
<title role="desc.title">Description</title>
<para>
<filename>error.h</filename> includes declarations for allocating and
manipulating <link linkend="lu-error"><type>lu_error</type></link> structures. These structures hold error and status
information passed between libuser, its modules, and applications.
</para>
<para>
A struct <link linkend="lu-error"><type>lu_error</type></link> contains an error code and a human-readable, possibly
translated error string. The error string is using the encoding specified
by <link linkend="LC-CTYPE:CAPS"><literal>LC_CTYPE</literal></link> locale category.
</para>
</refsect1>
<refsect1 role="details">
<title role="details.title">Details</title>
<refsect2>
<title><anchor id="LU-ERROR-CHECK:CAPS" role="macro"/>LU_ERROR_CHECK()</title>
<indexterm><primary>LU_ERROR_CHECK</primary></indexterm><programlisting>#define LU_ERROR_CHECK(err_p_p)</programlisting>
<para>
Checks that the given pointer to a pointer to a struct does not already point
to a valid <link linkend="lu-error"><type>lu_error</type></link> structure. This macro is used by many internal functions
to check that an error has not already occurred when they are invoked.
</para><variablelist role="params">
<varlistentry><term><parameter>err_p_p</parameter> :</term>
<listitem><simpara>A pointer to a struct <link linkend="lu-error"><type>lu_error</type></link> * which will be checked. If there
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="lu-error-new" role="function"/>lu_error_new ()</title>
<indexterm><primary>lu_error_new</primary></indexterm><programlisting><link linkend="void">void</link> lu_error_new (<link linkend="lu-error-t">lu_error_t</link> **error,
<link linkend="lu-status-t">lu_status_t</link> code,
const <link linkend="char">char</link> *fmt,
...);</programlisting>
<para>
Creates a new <link linkend="lu-error"><type>lu_error</type></link> structure.
</para><variablelist role="params">
<varlistentry><term><parameter>error</parameter> :</term>
<listitem><simpara>A pointer to a struct <link linkend="lu-error"><type>lu_error</type></link> * which will hold the newly-created
error structure. It must point to <link linkend="NULL:CAPS"><type>NULL</type></link> before calling this function.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>code</parameter> :</term>
<listitem><simpara>An error code
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>fmt</parameter> :</term>
<listitem><simpara>Format string describing the error. If <link linkend="NULL:CAPS"><type>NULL</type></link>, a default string is used.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter> :</term>
<listitem><simpara>Arguments for <parameter>fmt</parameter>, if necessary
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="lu-error-free" role="function"/>lu_error_free ()</title>
<indexterm><primary>lu_error_free</primary></indexterm><programlisting><link linkend="void">void</link> lu_error_free (<link linkend="lu-error-t">lu_error_t</link> **error);</programlisting>
<para>
Frees an <link linkend="lu-error"><type>lu_error</type></link> structure.
</para><variablelist role="params">
<varlistentry><term><parameter>error</parameter> :</term>
<listitem><simpara>A pointer to a pointer to the structure to be freed. The pointer is set
to NULL after the error is freed.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="lu-error-is-success" role="function"/>lu_error_is_success ()</title>
<indexterm><primary>lu_error_is_success</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> lu_error_is_success (<link linkend="lu-status-t">lu_status_t</link> status);</programlisting>
<para>
Check if the error code held by an error structure is a success code.
</para><variablelist role="params">
<varlistentry><term><parameter>status</parameter> :</term>
<listitem><simpara>An error code
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>a <link linkend="gboolean"><type>gboolean</type></link> indicating whether or not the error is a success code.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="lu-error-is-warning" role="function"/>lu_error_is_warning ()</title>
<indexterm><primary>lu_error_is_warning</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> lu_error_is_warning (<link linkend="lu-status-t">lu_status_t</link> status);</programlisting>
<para>
Check if the error code held by an error structure is a warning code.
</para><variablelist role="params">
<varlistentry><term><parameter>status</parameter> :</term>
<listitem><simpara>An error code
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>a <link linkend="gboolean"><type>gboolean</type></link> indicating whether or not the error is a warning code.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="lu-error-is-error" role="function"/>lu_error_is_error ()</title>
<indexterm><primary>lu_error_is_error</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> lu_error_is_error (<link linkend="lu-status-t">lu_status_t</link> status);</programlisting>
<para>
Check if the error code held by an error structure is an error code.
</para><variablelist role="params">
<varlistentry><term><parameter>status</parameter> :</term>
<listitem><simpara>An error code
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>a <link linkend="gboolean"><type>gboolean</type></link> indicating whether or not the error is an error code.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="lu-strerror" role="function"/>lu_strerror ()</title>
<indexterm><primary>lu_strerror</primary></indexterm><programlisting>const <link linkend="char">char</link>* lu_strerror (<link linkend="lu-error-t">lu_error_t</link> *error);</programlisting>
<para>
Converts an <link linkend="lu-error"><type>lu_error</type></link> structure to a string describing the error.
If the <parameter>error->string</parameter> is <link linkend="NULL:CAPS"><literal>NULL</literal></link>, returns a text representation of
<parameter>error->code</parameter>.
</para><variablelist role="params">
<varlistentry><term><parameter>error</parameter> :</term>
<listitem><simpara>An error
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>error string valid at least until <parameter>error</parameter> is freed.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
</refsect1>
<refsect1><refsect2 /><refsect2 /></refsect1>
</refentry>
|
