File: gpgrt.texi

package info (click to toggle)
libgpg-error 1.17-3
  • links: PTS, VCS
  • area: main
  • in suites: jessie, jessie-kfreebsd
  • size: 5,104 kB
  • ctags: 1,473
  • sloc: sh: 12,666; ansic: 12,199; makefile: 335; awk: 333; lisp: 138; sed: 16
file content (435 lines) | stat: -rw-r--r-- 13,533 bytes parent folder | download
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
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
\input texinfo                  @c -*- Texinfo -*-
@c %**start of header
@setfilename gpgrt.info
@include version.texi
@settitle The Libgpg-error Reference Manual
@c Unify some of the indices.
@syncodeindex tp fn
@syncodeindex pg fn
@c %**end of header
@copying
This manual is for Libgpg-error (version @value{VERSION},
@value{UPDATED}), which is a library for code used by all GnuPG
related packages.

@noindent
Copyright @copyright{} 2014 g10 Code GmbH

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 2 of the License, or (at your
option) any later version. The text of the license can be found in the
section entitled ``GNU General Public License''.
@end quotation
@end copying

@dircategory Libraries
@direntry
* libgpg-error: (gnupg).   Error codes and common code for GnuPG.
@end direntry

@c A couple of macros with no effect on texinfo
@c but used by the yat2m processor.
@macro manpage {a}
@end macro
@macro mansect {a}
@end macro
@macro manpause
@end macro
@macro mancont
@end macro

@c
@c Printing stuff taken from gcc.
@c
@macro gnupgtabopt{body}
@code{\body\}
@end macro


@c
@c Titlepage
@c
@setchapternewpage odd
@titlepage
@title The Libgpg-error Reference Manual
@subtitle Version @value{VERSION}
@subtitle @value{UPDATED}
@author Werner Koch (@email{wk@@gnupg.org})

@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@ifnothtml
@summarycontents
@contents
@page
@end ifnothtml


@ifnottex
@node Top
@top The Libgpg-error Library
@insertcopying
@end ifnottex


@menu
* Introduction::                 What is Libgpg-error.
* Preparation::                  What you should do before using the library.
* Generalities::                 General library functions and data types.
* Tools::                        Utility tools

Appendices

* Library Copying::             The GNU Lesser General Public License
                                says how you can copy and share Libgpg-error.
* Copying::                     The GNU General Public License says how you
                                can copy and share some parts of Libgpg-error.

Indices

@c * Figures and Tables::          Index of figures and tables.
* Concept Index::               Index of concepts and programs.
* Function and Data Index::     Index of functions, variables and data types.

@end menu

@ifhtml
@page
@summarycontents
@contents
@end ifhtml


@c **********************************************************
@c *******************  Introduction  ***********************
@c **********************************************************
@node Introduction
@chapter Introduction

Libgpg-error is a library to provide error codes for GnuPG and relates
software as well as some other general purpose functions.  It is
planned to eventually rename this library to ``gpgrt'' (for GnuPG
RunTime).

@menu
* Getting Started::             How to use this manual.
* Features::                    A glance at Libgpg-error’s features.
* Overview::                    Overview about the library.
@end menu

@node Getting Started
@section Getting Started

This manual documents the Libgpg-error library application programming
interface (API).  The goal is to that all functions and data types
provided by the library are explained.  However, for now this is only
a stub and not very usefull.


@node Features
@section Features

TBD

@node Overview
@section Overview

@noindent
The Libgpg-error library is fully thread-safe, where it makes
sense to be thread-safe.

TBD

@c **********************************************************
@c *******************  Preparation  ************************
@c **********************************************************
@node Preparation
@chapter Preparation

To use Libgpg-error, you have to perform some changes to your
sources and the build system.  The necessary changes are small and
explained in the following sections.  At the end of this chapter, it
is described how the library is initialized, and how the requirements
of the library are verified.

@menu
* Header::                      What header file you need to include.
* Building sources::            How to build sources using the library.
* Building sources using Automake::  How to build sources with the help of Automake.
* Initializing the library::    How to initialize the library.
* Multi-Threading::             How Libgpg-error can be used in a MT environment.
@end menu


@node Header
@section Header

All interfaces (data types and functions) of the library are defined
in the header file @file{libgpg-error.h}.  You must include this in all source
files using the library, either directly or through some other header
file, like this:

@example
#include <libgpg-error.h>
@end example

Note well that the header file is platform specific and may only be
used on the platform for which it has been build.

The name space of Libgpg-error is @code{gpg_*} and @code{gpgrt*}
for function and type names and @code{GPG_*} and @code{GPGRT_*}
for other symbols.  In addition the same name prefixes with one
prepended underscore are reserved for internal use and should never be
used by an application.

@noindent
Certain parts of gpg-error.h may be included by defining these macros:

@table @code
@item GPG_ERR_ENABLE_GETTEXT_MACROS
Define to provide macros to map the internal gettext API to standard
names.  This has only an effect on Windows platforms.

@item GPGRT_ENABLE_ES_MACROS
Define to provide "es_" macros for the estream functions.
@end table

@node Building sources
@section Building sources

If you want to compile a source file including the `gpg-error.h' header
file, you must make sure that the compiler can find it in the
directory hierarchy.  This is accomplished by adding the path to the
directory in which the header file is located to the compilers include
file search path (via the @option{-I} option).

However, the path to the include file is determined at the time the
source is configured.  To solve this problem, Libgpg-error ships with a small
helper program @command{gpg-error-config} that knows the path to the
include file and other configuration options.  The options that need
to be added to the compiler invocation at compile time are output by
the @option{--cflags} option to @command{gpg-error-config}.  The following
example shows how it can be used at the command line:

@example
gcc -c foo.c $(gpg-error-config --cflags)
@end example

Adding the output of @samp{gpg-error-config --cflags} to the
compiler’s command line will ensure that the compiler can find the
Libgpg-error header file.

A similar problem occurs when linking the program with the library.
Again, the compiler has to find the library files.  For this to work,
the path to the library files has to be added to the library search
path (via the @option{-L} option).  For this, the option
@option{--libs} to @command{gpg-error-config} can be used.  The
example shows how to link @file{foo.o} with the Libgpg-error library
to a program @command{foo}.

@example
gcc -o foo foo.o $(gpg-error-config --libs)
@end example

Of course you can also combine both examples to a single command by
specifying both options to @command{gpg-error-config}:

@example
gcc -o foo foo.c $(gpg-error-config --cflags --libs)
@end example

@node Building sources using Automake
@section Building sources using Automake

It is much easier if you use GNU Automake instead of writing your own
Makefiles.  If you do that, you do not have to worry about finding and
invoking the @command{gpg-error-config} script at all.  Libgpg-error
provides an extension to Automake that does all the work for you.

@c A simple macro for optional variables.
@macro ovar{varname}
@r{[}@var{\varname\}@r{]}
@end macro
@defmac AM_PATH_GPG_ERROR (@ovar{minimum-version}, @ovar{action-if-found}, @ovar{action-if-not-found})
Check whether Libgpg-error (at least version @var{minimum-version}, if
given) exists on the host system.  If it is found, execute
@var{action-if-found}, otherwise do @var{action-if-not-found}, if
given.

Additionally, the function defines @code{GPG_ERROR_CFLAGS} to the
flags needed for compilation of the program to find the
@file{gpg-error.h} header file, and @code{GPG_ERROR_LIBS} to the
linker flags needed to link the program to the Libgpg-error library.  If
the used helper script does not match the target type you are building
for a warning is printed and the string @code{libgpg-error} is
appended to the variable @code{gpg_config_script_warn}.

This macro searches for @command{gpg-error-config} along the PATH.  If
you are cross-compiling, it is useful to set the environment variable
@code{SYSROOT} to the top directory of your target.  The macro will
then first look for the helper program in the @file{bin} directory
below that top directory.  An absolute directory name must be used for
@code{SYSROOT}.  Finally, if the configure command line option
@code{--with-gpg-error-prefix} is used, only its value is used for the top
directory below which the helper script is expected.

@end defmac

You can use the defined Autoconf variables like this in your
@file{Makefile.am}:

@example
AM_CPPFLAGS = $(GPG_ERROR_CFLAGS)
LDADD = $(GPG_ERROR_LIBS)
@end example

@node Initializing the library
@section Initializing the library

Before the library can be used, it should initialize itself.  This is
achieved by invoking the function @code{gpgrt_check_version} described
below.

Also, it is often desirable to check that the version of
Libgpg-error used is indeed one which fits all requirements.
Even with binary compatibility, new features may have been introduced,
but due to problem with the dynamic linker an old version may actually
be used.  So you may want to check that the version is okay right
after program startup.

@deftypefun {const char *} gpgrt_check_version (const char *@var{req_version})

The function @code{gpgrt_check_version} initializes some subsystems used
by Libgpg-error and must be invoked before any other function in the
library.
@xref{Multi-Threading}.

Furthermore, this function returns the version number of the library.
It can also verify that the version number is higher than a certain
required version number @var{req_version}, if this value is not a null
pointer.
@end deftypefun


@node Multi-Threading
@section Multi-Threading

TBD.

@c **********************************************************
@c *******************  General  ****************************
@c **********************************************************
@node Generalities
@chapter Generalities

TBD.  (Description of the error fucntion may be taken from Libgcrypt.)



@c **********************************************************
@c *********************  Tools  ****************************
@c **********************************************************
@node Tools
@chapter Tools

@menu
* gpg-error-config::    Print required compiler flags
@end menu

@c The original version of this man page has been written for Debian and was
@c contributed to libgpg-error by Daniel Kahn Gillmor <dkg@fifthhorseman.net>.
@manpage gpg-error-config.1
@node gpg-error-config
@section Print required compiler flags
@ifset manverb
.B gpg-error-config
\- Script to get information about the installed version of libgpg-error
@end ifset

@mansect synopsis
@ifset manverb
.B  gpg-error-config
.RI [ options ]
@end ifset

@mansect description
@command{gpg-error-config} is a tool that is used to configure to
determine the compiler and linker flags that should be used to compile
and link programs that use Libgpg-error. It is also used
internally to the @code{.m4} macros for GNU autoconf that are included
with Libgpg-error.

@mansect options
@noindent
@command{gpg-error-config} accepts the following options:

@table @gnupgtabopt

@item  --mt
Provide output appropriate for multithreaded programs.  @option{--mt}
is only useful when combined with other options, and must be the first
option if present.

@item --version
Print the currently installed version of Libgpg-error on the
standard output.

@item --libs
Print the linker flags that are necessary to link a program using
Libgpg-error.

@item --cflags
Print the compiler flags that are necessary to compile a program using
Libgpg-error.

@item --prefix=@var{prefix}
If specified, use @var{prefix} instead of the installation prefix that
Libgpg-error was built with when computing the output for the
@option{--cflags} and @option{--libs} options.  This option is also
used for the exec prefix if @option{--exec-prefix} was not specified.
This option must be specified before any @option{--libs} or
@code{--cflags} options.

@item --exec-prefix=@var{prefix}
If specified, use @var{prefix} instead of the installation exec prefix
that Libgpg-error was built with when computing the output for the
@option{--cflags} and @option{--libs} options.  This option must be
specified before any @option{--libs} or @option{--cflags} options.

@end table

@manpause



@c **********************************************************
@c *************  Appendices (license etc.)  ****************
@c **********************************************************
@include lgpl.texi

@include gpl.texi

@c @node Figures and Tables
@c #@unnumbered List of Figures and Tables
@c
@c @listoffloats Figure
@c
@c @listoffloats Table

@node Concept Index
@unnumbered Concept Index

@printindex cp

@node Function and Data Index
@unnumbered Function and Data Index

@printindex fn


@bye