~ubuntu-branches/ubuntu/utopic/libuser/utopic-proposed

<refname>error</refname><refpurpose>Functions for allocating and manipulating <link linkend="lu-error"><type>lu_error</type></link> structures.</refpurpose>

</refnamediv>

<refsynopsisdiv><title>Synopsis</title>

#define <link linkend="LU-ERROR-CHECK:CAPS">LU_ERROR_CHECK</link> (err_p_p)

const <link linkend="char">char</link> *fmt,

...);

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>

<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 <literal>LC_CTYPE</literal> locale category.

</para>

</refsect1>

<title>Details</title>

<title><anchor id="LU-ERROR-CHECK:CAPS"/>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">

<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>

<title><anchor id="lu-error-new"/>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,

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>

<listitem><simpara>An error code

</simpara></listitem></varlistentry>

<listitem><simpara>Format string describing the error. If <link linkend="NULL:CAPS"><type>NULL</type></link>, a default string is used.

</simpara></listitem></varlistentry>

<listitem><simpara>Arguments for <parameter>fmt</parameter>, if necessary

</simpara></listitem></varlistentry>

</variablelist></refsect2>

<title><anchor id="lu-error-free"/>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.

100

</para><variablelist role="params">

101

<varlistentry><term><parameter>error</parameter> :</term>

102

<listitem><simpara>A pointer to a pointer to the structure to be freed. The pointer is set

103

to NULL after the error is freed.

104

105

106

</simpara></listitem></varlistentry>

107

</variablelist></refsect2>

108

109

<title><anchor id="lu-error-is-success"/>lu_error_is_success ()</title>

110

<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>

111

<para>

112

Check if the error code held by an error structure is a success code.

113

</para><variablelist role="params">

114

<varlistentry><term><parameter>status</parameter> :</term>

115

116

</simpara></listitem></varlistentry>

117

<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.

118

119

120

</simpara></listitem></varlistentry>

121

</variablelist></refsect2>

122

123

<title><anchor id="lu-error-is-warning"/>lu_error_is_warning ()</title>

124

<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>

125

<para>

126

Check if the error code held by an error structure is a warning code.

127

</para><variablelist role="params">

128

<varlistentry><term><parameter>status</parameter> :</term>

129

130

</simpara></listitem></varlistentry>

131

<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.

132

133

134

</simpara></listitem></varlistentry>

135

</variablelist></refsect2>

136

137

<title><anchor id="lu-error-is-error"/>lu_error_is_error ()</title>

138

<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>

139

<para>

140

Check if the error code held by an error structure is an error code.

141

</para><variablelist role="params">

142

<varlistentry><term><parameter>status</parameter> :</term>

143

144

</simpara></listitem></varlistentry>

145

<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.

146

147

148

</simpara></listitem></varlistentry>

149

</variablelist></refsect2>

150

151

<title><anchor id="lu-strerror"/>lu_strerror ()</title>

152

<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>

153

<para>

154

Converts an <link linkend="lu-error"><type>lu_error</type></link> structure to a string describing the error.

155

If the <parameter>error->string</parameter> is <literal>NULL</literal>, returns a text representation of

156

<parameter>error->code</parameter>.

157

</para><variablelist role="params">

158

<varlistentry><term><parameter>error</parameter> :</term>

159

<listitem><simpara>An error

160

</simpara></listitem></varlistentry>

161

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>error string valid at least until <parameter>error</parameter> is freed.

162

163

164

</simpara></listitem></varlistentry>

165

</variablelist></refsect2>

166

167

</refsect1>

168

169

170

171

172

</refentry>

Older »