1/* gpg-error.h or gpgrt.h - Common code for GnuPG and others.    -*- c -*-
2 * Copyright (C) 2001-2020 g10 Code GmbH
3 *
4 * This file is part of libgpg-error (aka libgpgrt).
5 *
6 * libgpg-error is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Lesser General Public License
8 * as published by the Free Software Foundation; either version 2.1 of
9 * the License, or (at your option) any later version.
10 *
11 * libgpg-error is distributed in the hope that it will be useful, but
12 * WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
14 * Lesser General Public License for more details.
15 *
16 * You should have received a copy of the GNU Lesser General Public
17 * License along with this program; if not, see <https://www.gnu.org/licenses/>.
18 * SPDX-License-Identifier: LGPL-2.1+
19 *
20 * @configure_input@
21 */
22
23/* The GnuPG project consists of many components.  Error codes are
24 * exchanged between all components.  The common error codes and their
25 * user-presentable descriptions are kept into a shared library to
26 * allow adding new error codes and components without recompiling any
27 * of the other components.  In addition to error codes this library
28 * also features several other groups of functions which are common to
29 * all GnuPG components.  They may be used by independet project as
30 * well.  The interfaces will not change in a backward incompatible way.
31 *
32 * An error code together with an error source build up an error
33 * value.  As the error value is been passed from one component to
34 * another, it preserves the information about the source and nature
35 * of the error.
36 *
37 * A component of the GnuPG project can define the following macros to
38 * tune the behaviour of the library:
39 *
40 * GPG_ERR_SOURCE_DEFAULT: Define to an error source of type
41 * gpg_err_source_t to make that source the default for gpg_error().
42 * Otherwise GPG_ERR_SOURCE_UNKNOWN is used as default.
43 *
44 * GPG_ERR_ENABLE_GETTEXT_MACROS: Define to provide macros to map the
45 * internal gettext API to standard names.  This has only an effect on
46 * Windows platforms.
47 *
48 * GPGRT_ENABLE_ES_MACROS: Define to provide "es_" macros for the
49 * estream functions.
50 *
51 * GPGRT_ENABLE_LOG_MACROS: Define to provide short versions of the
52 * log functions.
53 *
54 * GPGRT_ENABLE_ARGPARSE_MACROS: Needs to be defined to provide the
55 * mandatory macros of the argparse interface.
56 */
57
58#ifndef GPG_ERROR_H
59#define GPG_ERROR_H 1
60#ifndef GPGRT_H
61#define GPGRT_H 1
62
63#include <stddef.h>
64#include <stdio.h>
65#include <stdarg.h>
66
67/* The version string of this header. */
68#define GPG_ERROR_VERSION @version@
69#define GPGRT_VERSION     @version@
70
71/* The version number of this header. */
72#define GPG_ERROR_VERSION_NUMBER @version-number@
73#define GPGRT_VERSION_NUMBER     @version-number@
74
75
76#ifdef __GNUC__
77# define GPG_ERR_INLINE __inline__
78#elif defined(_MSC_VER) && _MSC_VER >= 1300
79# define GPG_ERR_INLINE __inline
80#elif defined (__STDC_VERSION__) && __STDC_VERSION__ >= 199901L
81# define GPG_ERR_INLINE inline
82#else
83# ifndef GPG_ERR_INLINE
84#  define GPG_ERR_INLINE
85# endif
86#endif
87
88#ifdef __cplusplus
89extern "C" {
90#if 0 /* just to make Emacs auto-indent happy */
91}
92#endif
93#endif /* __cplusplus */
94
95
96
97/* The error source type gpg_err_source_t.
98 *
99 * Where as the Poo out of a welle small
100 * Taketh his firste springing and his sours.
101 *					--Chaucer.
102 */
103
104/* Only use free slots, never change or reorder the existing
105 * entries.  */
106typedef enum
107  {
108@include:err-sources@
109    /* This is one more than the largest allowed entry.  */
110    GPG_ERR_SOURCE_DIM = 128
111  } gpg_err_source_t;
112
113
114/* The error code type gpg_err_code_t.  */
115
116/* Only use free slots, never change or reorder the existing
117 * entries.  */
118typedef enum
119  {
120@include:err-codes@
121    /* The following error codes are used to map system errors.  */
122#define GPG_ERR_SYSTEM_ERROR	(1 << 15)
123@include:errnos@
124    /* This is one more than the largest allowed entry.  */
125    GPG_ERR_CODE_DIM = 65536
126  } gpg_err_code_t;
127
128
129/* The error value type gpg_error_t.  */
130
131/* We would really like to use bit-fields in a struct, but using
132 * structs as return values can cause binary compatibility issues, in
133 * particular if you want to do it efficiently (also see
134 * -freg-struct-return option to GCC).  */
135typedef unsigned int gpg_error_t;
136
137/* We use the lowest 16 bits of gpg_error_t for error codes.  The 16th
138 * bit indicates system errors.  */
139#define GPG_ERR_CODE_MASK	(GPG_ERR_CODE_DIM - 1)
140
141/* Bits 17 to 24 are reserved.  */
142
143/* We use the upper 7 bits of gpg_error_t for error sources.  */
144#define GPG_ERR_SOURCE_MASK	(GPG_ERR_SOURCE_DIM - 1)
145#define GPG_ERR_SOURCE_SHIFT	24
146
147/* The highest bit is reserved.  It shouldn't be used to prevent
148 * potential negative numbers when transmitting error values as
149 * text.  */
150
151
152/*
153 * GCC feature test.
154 */
155#if __GNUC__
156# define _GPG_ERR_GCC_VERSION (__GNUC__ * 10000 \
157                               + __GNUC_MINOR__ * 100 \
158                               + __GNUC_PATCHLEVEL__)
159#else
160# define _GPG_ERR_GCC_VERSION 0
161#endif
162
163#undef _GPG_ERR_HAVE_CONSTRUCTOR
164#if _GPG_ERR_GCC_VERSION > 30100
165# define _GPG_ERR_CONSTRUCTOR	__attribute__ ((__constructor__))
166# define _GPG_ERR_HAVE_CONSTRUCTOR
167#else
168# define _GPG_ERR_CONSTRUCTOR
169#endif
170
171#define GPGRT_GCC_VERSION  _GPG_ERR_GCC_VERSION
172
173#if _GPG_ERR_GCC_VERSION >= 29200
174# define _GPGRT__RESTRICT __restrict__
175#else
176# define _GPGRT__RESTRICT
177#endif
178
179/* The noreturn attribute.  */
180#if _GPG_ERR_GCC_VERSION >= 20500
181# define GPGRT_ATTR_NORETURN   __attribute__ ((__noreturn__))
182#else
183# define GPGRT_ATTR_NORETURN
184#endif
185
186/* The printf attributes.  */
187#if _GPG_ERR_GCC_VERSION >= 40400
188# define GPGRT_ATTR_PRINTF(f, a) \
189                    __attribute__ ((format(__gnu_printf__,f,a)))
190# define GPGRT_ATTR_NR_PRINTF(f, a) \
191                    __attribute__ ((__noreturn__, format(__gnu_printf__,f,a)))
192#elif _GPG_ERR_GCC_VERSION >= 20500
193# define GPGRT_ATTR_PRINTF(f, a) \
194                    __attribute__ ((format(printf,f,a)))
195# define GPGRT_ATTR_NR_PRINTF(f, a) \
196                    __attribute__ ((__noreturn__, format(printf,f,a)))
197#else
198# define GPGRT_ATTR_PRINTF(f, a)
199# define GPGRT_ATTR_NR_PRINTF(f, a)
200#endif
201#if _GPG_ERR_GCC_VERSION >= 20800
202# define GPGRT_ATTR_FORMAT_ARG(a)  __attribute__ ((__format_arg__ (a)))
203#else
204# define GPGRT_ATTR_FORMAT_ARG(a)
205#endif
206
207/* The sentinel attribute.  */
208#if _GPG_ERR_GCC_VERSION >= 40000
209# define GPGRT_ATTR_SENTINEL(a)  __attribute__ ((sentinel(a)))
210#else
211# define GPGRT_ATTR_SENTINEL(a)
212#endif
213
214/* The used and unused attributes.
215 * I am not sure since when the unused attribute is really supported.
216 * In any case it it only needed for gcc versions which print a
217 * warning.  Thus let us require gcc >= 3.5.  */
218#if _GPG_ERR_GCC_VERSION >= 40000
219# define GPGRT_ATTR_USED  __attribute__ ((used))
220#else
221# define GPGRT_ATTR_USED
222#endif
223#if _GPG_ERR_GCC_VERSION >= 30500
224# define GPGRT_ATTR_UNUSED  __attribute__ ((unused))
225#else
226# define GPGRT_ATTR_UNUSED
227#endif
228
229/* The deprecated attribute.  */
230#if _GPG_ERR_GCC_VERSION >= 30100
231# define GPGRT_ATTR_DEPRECATED  __attribute__ ((__deprecated__))
232#else
233# define GPGRT_ATTR_DEPRECATED
234#endif
235
236/* The pure attribute.  */
237#if _GPG_ERR_GCC_VERSION >= 29600
238# define GPGRT_ATTR_PURE  __attribute__ ((__pure__))
239#else
240# define GPGRT_ATTR_PURE
241#endif
242
243/* The malloc attribute.  */
244#if _GPG_ERR_GCC_VERSION >= 30200
245# define GPGRT_ATTR_MALLOC  __attribute__ ((__malloc__))
246#else
247# define GPGRT_ATTR_MALLOC
248#endif
249
250/* A macro defined if a GCC style __FUNCTION__ macro is available.  */
251#undef GPGRT_HAVE_MACRO_FUNCTION
252#if _GPG_ERR_GCC_VERSION >= 20500
253# define GPGRT_HAVE_MACRO_FUNCTION 1
254#endif
255
256/* A macro defined if the pragma GCC push_options is available.  */
257#undef GPGRT_HAVE_PRAGMA_GCC_PUSH
258#if _GPG_ERR_GCC_VERSION >= 40400
259# define GPGRT_HAVE_PRAGMA_GCC_PUSH 1
260#endif
261
262/* Detect LeakSanitizer (LSan) support for GCC and Clang based on
263 * whether AddressSanitizer (ASAN) is enabled via -fsanitize=address).
264 * Note that -fsanitize=leak just affect the linker options which
265 * cannot be detected here.  In that case you have to define the
266 * GPGRT_HAVE_LEAK_SANITIZER macro manually.  */
267#ifdef __GNUC__
268# ifdef __SANITIZE_ADDRESS__
269#  define GPGRT_HAVE_LEAK_SANITIZER
270# elif defined(__has_feature)
271#  if __has_feature(address_sanitizer)
272#   define GPGRT_HAVE_LEAK_SANITIZER
273#  endif
274# endif
275#endif
276
277
278/* The new name for the inline macro.  */
279#define GPGRT_INLINE GPG_ERR_INLINE
280
281#ifdef GPGRT_HAVE_LEAK_SANITIZER
282# include <sanitizer/lsan_interface.h>
283#endif
284
285/* Mark heap objects as non-leaked memory. */
286static GPGRT_INLINE void
287gpgrt_annotate_leaked_object (const void *p)
288{
289#ifdef GPGRT_HAVE_LEAK_SANITIZER
290  __lsan_ignore_object(p);
291#else
292  (void)p;
293#endif
294}
295
296
297/*
298 * Initialization function.
299 */
300
301/* Initialize the library.  This function should be run early.  */
302gpg_error_t gpg_err_init (void) _GPG_ERR_CONSTRUCTOR;
303
304/* If this is defined, the library is already initialized by the
305   constructor and does not need to be initialized explicitely.  */
306#undef GPG_ERR_INITIALIZED
307#ifdef _GPG_ERR_HAVE_CONSTRUCTOR
308# define GPG_ERR_INITIALIZED	1
309# define gpgrt_init() do { gpg_err_init (); } while (0)
310#else
311# define gpgrt_init() do { ; } while (0)
312#endif
313
314/* See the source on how to use the deinit function; it is usually not
315   required.  */
316void gpg_err_deinit (int mode);
317
318/* Register blocking system I/O clamping functions.  */
319void gpgrt_set_syscall_clamp (void (*pre)(void), void (*post)(void));
320
321/* Get current I/O clamping functions.  */
322void gpgrt_get_syscall_clamp (void (**r_pre)(void), void (**r_post)(void));
323
324/* Register a custom malloc/realloc/free function.  */
325void gpgrt_set_alloc_func  (void *(*f)(void *a, size_t n));
326
327/* Register an emergency cleanup handler.  */
328void gpgrt_add_emergency_cleanup (void (*f)(void));
329
330/* Wrapper around abort to make sure emergency cleanups are run.  */
331void gpgrt_abort (void) GPGRT_ATTR_NORETURN;
332
333
334
335/*
336 * Constructor and accessor functions.
337 */
338
339/* Construct an error value from an error code and source.  Within a
340 * subsystem, use gpg_error.  */
341static GPG_ERR_INLINE gpg_error_t
342gpg_err_make (gpg_err_source_t source, gpg_err_code_t code)
343{
344  return code == GPG_ERR_NO_ERROR ? GPG_ERR_NO_ERROR
345    : (((source & GPG_ERR_SOURCE_MASK) << GPG_ERR_SOURCE_SHIFT)
346       | (code & GPG_ERR_CODE_MASK));
347}
348
349
350/* The user should define GPG_ERR_SOURCE_DEFAULT before including this
351 * file to specify a default source for gpg_error.  */
352#ifndef GPG_ERR_SOURCE_DEFAULT
353#define GPG_ERR_SOURCE_DEFAULT	GPG_ERR_SOURCE_UNKNOWN
354#endif
355
356static GPG_ERR_INLINE gpg_error_t
357gpg_error (gpg_err_code_t code)
358{
359  return gpg_err_make (GPG_ERR_SOURCE_DEFAULT, code);
360}
361
362
363/* Retrieve the error code from an error value.  */
364static GPG_ERR_INLINE gpg_err_code_t
365gpg_err_code (gpg_error_t err)
366{
367  return (gpg_err_code_t) (err & GPG_ERR_CODE_MASK);
368}
369
370
371/* Retrieve the error source from an error value.  */
372static GPG_ERR_INLINE gpg_err_source_t
373gpg_err_source (gpg_error_t err)
374{
375  return (gpg_err_source_t) ((err >> GPG_ERR_SOURCE_SHIFT)
376			     & GPG_ERR_SOURCE_MASK);
377}
378
379
380/* String functions.  */
381
382/* Return a pointer to a string containing a description of the error
383 * code in the error value ERR.  This function is not thread-safe.  */
384const char *gpg_strerror (gpg_error_t err);
385
386/* Return the error string for ERR in the user-supplied buffer BUF of
387 * size BUFLEN.  This function is, in contrast to gpg_strerror,
388 * thread-safe if a thread-safe strerror_r() function is provided by
389 * the system.  If the function succeeds, 0 is returned and BUF
390 * contains the string describing the error.  If the buffer was not
391 * large enough, ERANGE is returned and BUF contains as much of the
392 * beginning of the error string as fits into the buffer.  */
393int gpg_strerror_r (gpg_error_t err, char *buf, size_t buflen);
394
395/* Return a pointer to a string containing a description of the error
396 * source in the error value ERR.  */
397const char *gpg_strsource (gpg_error_t err);
398
399
400/*
401 * Mapping of system errors (errno).
402 */
403
404/* Retrieve the error code for the system error ERR.  This returns
405 * GPG_ERR_UNKNOWN_ERRNO if the system error is not mapped (report
406 * this). */
407gpg_err_code_t gpg_err_code_from_errno (int err);
408
409/* Retrieve the system error for the error code CODE.  This returns 0
410 * if CODE is not a system error code.  */
411int gpg_err_code_to_errno (gpg_err_code_t code);
412
413/* Retrieve the error code directly from the ERRNO variable.  This
414 * returns GPG_ERR_UNKNOWN_ERRNO if the system error is not mapped
415 * (report this) and GPG_ERR_MISSING_ERRNO if ERRNO has the value 0. */
416gpg_err_code_t gpg_err_code_from_syserror (void);
417
418/* Mapper for SQLite primary error codes.  */
419static GPG_ERR_INLINE gpg_error_t
420gpg_err_code_from_sqlite (int sqlres)
421{
422  return sqlres? GPG_ERR_SQL_OK + (sqlres & 0xff) : 0;
423}
424
425
426/* Set the ERRNO variable.  This function is the preferred way to set
427 * ERRNO due to peculiarities on WindowsCE.  */
428void gpg_err_set_errno (int err);
429
430/* Return or check the version.  Both functions are identical.  */
431const char *gpgrt_check_version (const char *req_version);
432const char *gpg_error_check_version (const char *req_version);
433
434/* System specific type definitions.  */
435@define:pid_t@
436@define:gpgrt_ssize_t@
437@define:gpgrt_off_t@
438
439@include:os-add@
440
441/* Self-documenting convenience functions.  */
442
443static GPG_ERR_INLINE gpg_error_t
444gpg_err_make_from_errno (gpg_err_source_t source, int err)
445{
446  return gpg_err_make (source, gpg_err_code_from_errno (err));
447}
448
449
450static GPG_ERR_INLINE gpg_error_t
451gpg_error_from_errno (int err)
452{
453  return gpg_error (gpg_err_code_from_errno (err));
454}
455
456static GPG_ERR_INLINE gpg_error_t
457gpg_error_from_syserror (void)
458{
459  return gpg_error (gpg_err_code_from_syserror ());
460}
461
462
463
464/*
465 * Malloc and friends
466 */
467
468void *gpgrt_realloc (void *a, size_t n);
469void *gpgrt_reallocarray (void *a, size_t oldnmemb, size_t nmemb, size_t size);
470void *gpgrt_malloc (size_t n);
471void *gpgrt_calloc (size_t n, size_t m);
472char *gpgrt_strdup (const char *string);
473char *gpgrt_strconcat (const char *s1, ...) GPGRT_ATTR_SENTINEL(0);
474void gpgrt_free (void *a);
475
476
477/*
478 * System specific function wrappers.
479 */
480
481/* A getenv replacement which mallocs the returned string.  */
482char *gpgrt_getenv (const char *name);
483
484/* A setenv and a unsetenv replacement.*/
485gpg_err_code_t gpgrt_setenv (const char *name,
486                             const char *value, int overwrite);
487#define gpgrt_unsetenv(n) gpgrt_setenv ((n), NULL, 1)
488
489/* A wrapper around mkdir using a string for the mode.  */
490gpg_err_code_t gpgrt_mkdir (const char *name, const char *modestr);
491
492/* A simple wrapper around chdir.  */
493gpg_err_code_t gpgrt_chdir (const char *name);
494
495/* Return the current WD as a malloced string.  */
496char *gpgrt_getcwd (void);
497
498/* A wrapper around access to handle UTF-8 on Windows.  */
499gpg_err_code_t gpgrt_access (const char *fname, int mode);
500
501
502
503
504/*
505 * Lock functions.
506 */
507
508@include:lock-obj@
509
510#define GPGRT_LOCK_DEFINE(name) \
511  static gpgrt_lock_t name  = GPGRT_LOCK_INITIALIZER
512
513/* NB: If GPGRT_LOCK_DEFINE is not used, zero out the lock variable
514   before passing it to gpgrt_lock_init.  */
515gpg_err_code_t gpgrt_lock_init (gpgrt_lock_t *lockhd);
516gpg_err_code_t gpgrt_lock_lock (gpgrt_lock_t *lockhd);
517gpg_err_code_t gpgrt_lock_trylock (gpgrt_lock_t *lockhd);
518gpg_err_code_t gpgrt_lock_unlock (gpgrt_lock_t *lockhd);
519gpg_err_code_t gpgrt_lock_destroy (gpgrt_lock_t *lockhd);
520
521
522
523/*
524 * Thread functions.
525 */
526
527gpg_err_code_t gpgrt_yield (void);
528
529
530
531
532/*
533 * Estream
534 */
535
536/* The definition of this struct is entirely private.  You must not
537   use it for anything.  It is only here so some functions can be
538   implemented as macros.  */
539struct _gpgrt_stream_internal;
540struct _gpgrt__stream
541{
542  /* The layout of this struct must never change.  It may be grown,
543     but only if all functions which access the new members are
544     versioned.  */
545
546  /* Various flags.  */
547  struct {
548    unsigned int magic: 16;
549    unsigned int writing: 1;
550    unsigned int reserved: 15;
551  } flags;
552
553  /* A pointer to the stream buffer.  */
554  unsigned char *buffer;
555
556  /* The size of the buffer in bytes.  */
557  size_t buffer_size;
558
559  /* The length of the usable data in the buffer, only valid when in
560     read mode (see flags).  */
561  size_t data_len;
562
563  /* The current position of the offset pointer, valid in read and
564     write mode.  */
565  size_t data_offset;
566
567  size_t data_flushed;
568  unsigned char *unread_buffer;
569  size_t unread_buffer_size;
570
571  /* The number of unread bytes.  */
572  size_t unread_data_len;
573
574  /* A pointer to our internal data for this stream.  */
575  struct _gpgrt_stream_internal *intern;
576};
577
578/* The opaque type for an estream.  */
579typedef struct _gpgrt__stream *gpgrt_stream_t;
580#ifdef GPGRT_ENABLE_ES_MACROS
581typedef struct _gpgrt__stream *estream_t;
582#endif
583
584typedef @api_ssize_t@ (*gpgrt_cookie_read_function_t) (void *cookie,
585                                                 void *buffer, size_t size);
586typedef @api_ssize_t@ (*gpgrt_cookie_write_function_t) (void *cookie,
587                                                  const void *buffer,
588                                                  size_t size);
589typedef int (*gpgrt_cookie_seek_function_t) (void *cookie,
590                                             gpgrt_off_t *pos, int whence);
591typedef int (*gpgrt_cookie_close_function_t) (void *cookie);
592
593struct _gpgrt_cookie_io_functions
594{
595  gpgrt_cookie_read_function_t func_read;
596  gpgrt_cookie_write_function_t func_write;
597  gpgrt_cookie_seek_function_t func_seek;
598  gpgrt_cookie_close_function_t func_close;
599};
600typedef struct _gpgrt_cookie_io_functions gpgrt_cookie_io_functions_t;
601#ifdef GPGRT_ENABLE_ES_MACROS
602typedef struct _gpgrt_cookie_io_functions  es_cookie_io_functions_t;
603#define es_cookie_read_function_t  gpgrt_cookie_read_function_t
604#define es_cookie_write_function_t gpgrt_cookie_read_function_t
605#define es_cookie_seek_function_t  gpgrt_cookie_read_function_t
606#define es_cookie_close_function_t gpgrt_cookie_read_function_t
607#endif
608
609enum gpgrt_syshd_types
610  {
611    GPGRT_SYSHD_NONE = 0,  /* No system handle available.                   */
612    GPGRT_SYSHD_FD = 1,    /* A file descriptor as returned by open().      */
613    GPGRT_SYSHD_SOCK = 2,  /* A socket as returned by socket().             */
614    GPGRT_SYSHD_RVID = 3,  /* A rendezvous id (see libassuan's gpgcedev.c).  */
615    GPGRT_SYSHD_HANDLE = 4 /* A HANDLE object (Windows).                    */
616  };
617
618struct _gpgrt_syshd
619{
620  enum gpgrt_syshd_types type;
621  union {
622    int fd;
623    int sock;
624    int rvid;
625    void *handle;
626  } u;
627};
628typedef struct _gpgrt_syshd gpgrt_syshd_t;
629#ifdef GPGRT_ENABLE_ES_MACROS
630typedef struct _gpgrt_syshd es_syshd_t;
631#define ES_SYSHD_NONE   GPGRT_SYSHD_NONE
632#define ES_SYSHD_FD     GPGRT_SYSHD_FD
633#define ES_SYSHD_SOCK   GPGRT_SYSHD_SOCK
634#define ES_SYSHD_RVID   GPGRT_SYSHD_RVID
635#define ES_SYSHD_HANDLE GPGRT_SYSHD_HANDLE
636#endif
637
638/* The object used with gpgrt_poll.  */
639struct _gpgrt_poll_s
640{
641  gpgrt_stream_t stream;
642  unsigned int want_read:1;
643  unsigned int want_write:1;
644  unsigned int want_oob:1;
645  unsigned int want_rdhup:1;
646  unsigned int _reserv1:4;
647  unsigned int got_read:1;
648  unsigned int got_write:1;
649  unsigned int got_oob:1;
650  unsigned int got_rdhup:1;
651  unsigned int _reserv2:4;
652  unsigned int got_err:1;
653  unsigned int got_hup:1;
654  unsigned int got_nval:1;
655  unsigned int _reserv3:4;
656  unsigned int ignore:1;
657  unsigned int user:8;       /* For application use.  */
658};
659typedef struct _gpgrt_poll_s gpgrt_poll_t;
660#ifdef GPGRT_ENABLE_ES_MACROS
661typedef struct _gpgrt_poll_s es_poll_t;
662#endif
663
664/* The type of the string filter function as used by fprintf_sf et al.  */
665typedef char *(*gpgrt_string_filter_t) (const char *s, int n, void *opaque);
666
667
668
669gpgrt_stream_t gpgrt_fopen (const char *_GPGRT__RESTRICT path,
670                            const char *_GPGRT__RESTRICT mode);
671gpgrt_stream_t gpgrt_mopen (void *_GPGRT__RESTRICT data,
672                            size_t data_n, size_t data_len,
673                            unsigned int grow,
674                            void *(*func_realloc) (void *mem, size_t size),
675                            void (*func_free) (void *mem),
676                            const char *_GPGRT__RESTRICT mode);
677gpgrt_stream_t gpgrt_fopenmem (size_t memlimit,
678                               const char *_GPGRT__RESTRICT mode);
679gpgrt_stream_t gpgrt_fopenmem_init (size_t memlimit,
680                                    const char *_GPGRT__RESTRICT mode,
681                                    const void *data, size_t datalen);
682gpgrt_stream_t gpgrt_fdopen    (int filedes, const char *mode);
683gpgrt_stream_t gpgrt_fdopen_nc (int filedes, const char *mode);
684gpgrt_stream_t gpgrt_sysopen    (gpgrt_syshd_t *syshd, const char *mode);
685gpgrt_stream_t gpgrt_sysopen_nc (gpgrt_syshd_t *syshd, const char *mode);
686gpgrt_stream_t gpgrt_fpopen    (FILE *fp, const char *mode);
687gpgrt_stream_t gpgrt_fpopen_nc (FILE *fp, const char *mode);
688gpgrt_stream_t gpgrt_freopen (const char *_GPGRT__RESTRICT path,
689                              const char *_GPGRT__RESTRICT mode,
690                              gpgrt_stream_t _GPGRT__RESTRICT stream);
691gpgrt_stream_t gpgrt_fopencookie (void *_GPGRT__RESTRICT cookie,
692                                  const char *_GPGRT__RESTRICT mode,
693                                  gpgrt_cookie_io_functions_t functions);
694int gpgrt_fclose (gpgrt_stream_t stream);
695int gpgrt_fcancel (gpgrt_stream_t stream);
696int gpgrt_fclose_snatch (gpgrt_stream_t stream,
697                         void **r_buffer, size_t *r_buflen);
698int gpgrt_onclose (gpgrt_stream_t stream, int mode,
699                   void (*fnc) (gpgrt_stream_t, void*), void *fnc_value);
700int gpgrt_fileno (gpgrt_stream_t stream);
701int gpgrt_fileno_unlocked (gpgrt_stream_t stream);
702int gpgrt_syshd (gpgrt_stream_t stream, gpgrt_syshd_t *syshd);
703int gpgrt_syshd_unlocked (gpgrt_stream_t stream, gpgrt_syshd_t *syshd);
704
705void _gpgrt_set_std_fd (int no, int fd);
706gpgrt_stream_t _gpgrt_get_std_stream (int fd);
707
708#define gpgrt_stdin  _gpgrt_get_std_stream (0)
709#define gpgrt_stdout _gpgrt_get_std_stream (1)
710#define gpgrt_stderr _gpgrt_get_std_stream (2)
711
712
713void gpgrt_flockfile (gpgrt_stream_t stream);
714int  gpgrt_ftrylockfile (gpgrt_stream_t stream);
715void gpgrt_funlockfile (gpgrt_stream_t stream);
716
717int gpgrt_feof (gpgrt_stream_t stream);
718int gpgrt_feof_unlocked (gpgrt_stream_t stream);
719int gpgrt_ferror (gpgrt_stream_t stream);
720int gpgrt_ferror_unlocked (gpgrt_stream_t stream);
721void gpgrt_clearerr (gpgrt_stream_t stream);
722void gpgrt_clearerr_unlocked (gpgrt_stream_t stream);
723
724int _gpgrt_pending (gpgrt_stream_t stream);          /* (private) */
725int _gpgrt_pending_unlocked (gpgrt_stream_t stream); /* (private) */
726
727#define gpgrt_pending(stream) _gpgrt_pending (stream)
728
729#define gpgrt_pending_unlocked(stream)				\
730  (((!(stream)->flags.writing)					\
731    && (((stream)->data_offset < (stream)->data_len)		\
732        || ((stream)->unread_data_len)))                        \
733   ? 1 : _gpgrt_pending_unlocked ((stream)))
734
735int gpgrt_fflush (gpgrt_stream_t stream);
736int gpgrt_fseek (gpgrt_stream_t stream, long int offset, int whence);
737int gpgrt_fseeko (gpgrt_stream_t stream, gpgrt_off_t offset, int whence);
738int gpgrt_ftruncate (gpgrt_stream_t stream, gpgrt_off_t length);
739long int gpgrt_ftell (gpgrt_stream_t stream);
740gpgrt_off_t gpgrt_ftello (gpgrt_stream_t stream);
741void gpgrt_rewind (gpgrt_stream_t stream);
742
743int gpgrt_fgetc (gpgrt_stream_t stream);
744int gpgrt_fputc (int c, gpgrt_stream_t stream);
745
746int _gpgrt_getc_underflow (gpgrt_stream_t stream);       /* (private) */
747int _gpgrt_putc_overflow (int c, gpgrt_stream_t stream); /* (private) */
748
749#define gpgrt_getc_unlocked(stream)				\
750  (((!(stream)->flags.writing)					\
751    && ((stream)->data_offset < (stream)->data_len)		\
752    && (! (stream)->unread_data_len))				\
753  ? ((int) (stream)->buffer[((stream)->data_offset)++])		\
754  : _gpgrt_getc_underflow ((stream)))
755
756#define gpgrt_putc_unlocked(c, stream)				\
757  (((stream)->flags.writing					\
758    && ((stream)->data_offset < (stream)->buffer_size)		\
759    && (c != '\n'))						\
760  ? ((int) ((stream)->buffer[((stream)->data_offset)++] = (c)))	\
761  : _gpgrt_putc_overflow ((c), (stream)))
762
763#define gpgrt_getc(stream)    gpgrt_fgetc (stream)
764#define gpgrt_putc(c, stream) gpgrt_fputc (c, stream)
765
766int gpgrt_ungetc (int c, gpgrt_stream_t stream);
767
768int gpgrt_read (gpgrt_stream_t _GPGRT__RESTRICT stream,
769                void *_GPGRT__RESTRICT buffer, size_t bytes_to_read,
770                size_t *_GPGRT__RESTRICT bytes_read);
771int gpgrt_write (gpgrt_stream_t _GPGRT__RESTRICT stream,
772                 const void *_GPGRT__RESTRICT buffer, size_t bytes_to_write,
773                 size_t *_GPGRT__RESTRICT bytes_written);
774int gpgrt_write_sanitized (gpgrt_stream_t _GPGRT__RESTRICT stream,
775                           const void *_GPGRT__RESTRICT buffer, size_t length,
776                           const char *delimiters,
777                           size_t *_GPGRT__RESTRICT bytes_written);
778int gpgrt_write_hexstring (gpgrt_stream_t _GPGRT__RESTRICT stream,
779                           const void *_GPGRT__RESTRICT buffer, size_t length,
780                           int reserved,
781                           size_t *_GPGRT__RESTRICT bytes_written);
782
783size_t gpgrt_fread (void *_GPGRT__RESTRICT ptr, size_t size, size_t nitems,
784                    gpgrt_stream_t _GPGRT__RESTRICT stream);
785size_t gpgrt_fwrite (const void *_GPGRT__RESTRICT ptr, size_t size,
786                     size_t nitems, gpgrt_stream_t _GPGRT__RESTRICT stream);
787
788char *gpgrt_fgets (char *_GPGRT__RESTRICT s, int n,
789                   gpgrt_stream_t _GPGRT__RESTRICT stream);
790int gpgrt_fputs (const char *_GPGRT__RESTRICT s,
791                 gpgrt_stream_t _GPGRT__RESTRICT stream);
792int gpgrt_fputs_unlocked (const char *_GPGRT__RESTRICT s,
793                          gpgrt_stream_t _GPGRT__RESTRICT stream);
794
795@api_ssize_t@ gpgrt_getline (char *_GPGRT__RESTRICT *_GPGRT__RESTRICT lineptr,
796                       size_t *_GPGRT__RESTRICT n,
797                       gpgrt_stream_t stream);
798@api_ssize_t@ gpgrt_read_line (gpgrt_stream_t stream,
799                         char **addr_of_buffer, size_t *length_of_buffer,
800                         size_t *max_length);
801
802int gpgrt_fprintf (gpgrt_stream_t _GPGRT__RESTRICT stream,
803                   const char *_GPGRT__RESTRICT format, ...)
804                   GPGRT_ATTR_PRINTF(2,3);
805int gpgrt_fprintf_unlocked (gpgrt_stream_t _GPGRT__RESTRICT stream,
806                            const char *_GPGRT__RESTRICT format, ...)
807                            GPGRT_ATTR_PRINTF(2,3);
808
809int gpgrt_fprintf_sf (gpgrt_stream_t _GPGRT__RESTRICT stream,
810                      gpgrt_string_filter_t sf, void *sfvalue,
811                      const char *_GPGRT__RESTRICT format,
812                      ...) GPGRT_ATTR_PRINTF(4,5);
813int gpgrt_fprintf_sf_unlocked (gpgrt_stream_t _GPGRT__RESTRICT stream,
814                               gpgrt_string_filter_t sf, void *sfvalue,
815                               const char *_GPGRT__RESTRICT format,
816                               ...) GPGRT_ATTR_PRINTF(4,5);
817
818int gpgrt_printf (const char *_GPGRT__RESTRICT format, ...)
819                  GPGRT_ATTR_PRINTF(1,2);
820int gpgrt_printf_unlocked (const char *_GPGRT__RESTRICT format, ...)
821                           GPGRT_ATTR_PRINTF(1,2);
822
823int gpgrt_vfprintf (gpgrt_stream_t _GPGRT__RESTRICT stream,
824                    const char *_GPGRT__RESTRICT format, va_list ap)
825                    GPGRT_ATTR_PRINTF(2,0);
826int gpgrt_vfprintf_unlocked (gpgrt_stream_t _GPGRT__RESTRICT stream,
827                             const char *_GPGRT__RESTRICT format, va_list ap)
828                             GPGRT_ATTR_PRINTF(2,0);
829
830int gpgrt_setvbuf (gpgrt_stream_t _GPGRT__RESTRICT stream,
831                   char *_GPGRT__RESTRICT buf, int mode, size_t size);
832void gpgrt_setbuf (gpgrt_stream_t _GPGRT__RESTRICT stream,
833                   char *_GPGRT__RESTRICT buf);
834
835void gpgrt_set_binary (gpgrt_stream_t stream);
836int  gpgrt_set_nonblock (gpgrt_stream_t stream, int onoff);
837int  gpgrt_get_nonblock (gpgrt_stream_t stream);
838
839int gpgrt_poll (gpgrt_poll_t *fdlist, unsigned int nfds, int timeout);
840
841gpgrt_stream_t gpgrt_tmpfile (void);
842
843void gpgrt_opaque_set (gpgrt_stream_t _GPGRT__RESTRICT stream,
844                       void *_GPGRT__RESTRICT opaque);
845void *gpgrt_opaque_get (gpgrt_stream_t stream);
846
847void gpgrt_fname_set (gpgrt_stream_t stream, const char *fname);
848const char *gpgrt_fname_get (gpgrt_stream_t stream);
849
850int gpgrt_asprintf (char **r_buf, const char * _GPGRT__RESTRICT format, ...)
851                    GPGRT_ATTR_PRINTF(2,3);
852int gpgrt_vasprintf (char **r_buf, const char * _GPGRT__RESTRICT format,
853                     va_list ap)
854                     GPGRT_ATTR_PRINTF(2,0);
855char *gpgrt_bsprintf (const char * _GPGRT__RESTRICT format, ...)
856                      GPGRT_ATTR_PRINTF(1,2);
857char *gpgrt_vbsprintf (const char * _GPGRT__RESTRICT format, va_list ap)
858                       GPGRT_ATTR_PRINTF(1,0);
859int gpgrt_snprintf (char *buf, size_t bufsize,
860                    const char * _GPGRT__RESTRICT format, ...)
861                    GPGRT_ATTR_PRINTF(3,4);
862int gpgrt_vsnprintf (char *buf,size_t bufsize,
863                     const char * _GPGRT__RESTRICT format, va_list arg_ptr)
864                     GPGRT_ATTR_PRINTF(3,0);
865
866
867#ifdef GPGRT_ENABLE_ES_MACROS
868# define es_fopen             gpgrt_fopen
869# define es_mopen             gpgrt_mopen
870# define es_fopenmem          gpgrt_fopenmem
871# define es_fopenmem_init     gpgrt_fopenmem_init
872# define es_fdopen            gpgrt_fdopen
873# define es_fdopen_nc         gpgrt_fdopen_nc
874# define es_sysopen           gpgrt_sysopen
875# define es_sysopen_nc        gpgrt_sysopen_nc
876# define es_fpopen            gpgrt_fpopen
877# define es_fpopen_nc         gpgrt_fpopen_nc
878# define es_freopen           gpgrt_freopen
879# define es_fopencookie       gpgrt_fopencookie
880# define es_fclose            gpgrt_fclose
881# define es_fclose_snatch     gpgrt_fclose_snatch
882# define es_onclose           gpgrt_onclose
883# define es_fileno            gpgrt_fileno
884# define es_fileno_unlocked   gpgrt_fileno_unlocked
885# define es_syshd             gpgrt_syshd
886# define es_syshd_unlocked    gpgrt_syshd_unlocked
887# define es_stdin             _gpgrt_get_std_stream (0)
888# define es_stdout            _gpgrt_get_std_stream (1)
889# define es_stderr            _gpgrt_get_std_stream (2)
890# define es_flockfile         gpgrt_flockfile
891# define es_ftrylockfile      gpgrt_ftrylockfile
892# define es_funlockfile       gpgrt_funlockfile
893# define es_feof              gpgrt_feof
894# define es_feof_unlocked     gpgrt_feof_unlocked
895# define es_ferror            gpgrt_ferror
896# define es_ferror_unlocked   gpgrt_ferror_unlocked
897# define es_clearerr          gpgrt_clearerr
898# define es_clearerr_unlocked gpgrt_clearerr_unlocked
899# define es_pending           gpgrt_pending
900# define es_pending_unlocked  gpgrt_pending_unlocked
901# define es_fflush            gpgrt_fflush
902# define es_fseek             gpgrt_fseek
903# define es_fseeko            gpgrt_fseeko
904# define es_ftruncate         gpgrt_ftruncate
905# define es_ftell             gpgrt_ftell
906# define es_ftello            gpgrt_ftello
907# define es_rewind            gpgrt_rewind
908# define es_fgetc             gpgrt_fgetc
909# define es_fputc             gpgrt_fputc
910# define es_getc_unlocked     gpgrt_getc_unlocked
911# define es_putc_unlocked     gpgrt_putc_unlocked
912# define es_getc              gpgrt_getc
913# define es_putc              gpgrt_putc
914# define es_ungetc            gpgrt_ungetc
915# define es_read              gpgrt_read
916# define es_write             gpgrt_write
917# define es_write_sanitized   gpgrt_write_sanitized
918# define es_write_hexstring   gpgrt_write_hexstring
919# define es_fread             gpgrt_fread
920# define es_fwrite            gpgrt_fwrite
921# define es_fgets             gpgrt_fgets
922# define es_fputs             gpgrt_fputs
923# define es_fputs_unlocked    gpgrt_fputs_unlocked
924# define es_getline           gpgrt_getline
925# define es_read_line         gpgrt_read_line
926# define es_free              gpgrt_free
927# define es_fprintf           gpgrt_fprintf
928# define es_fprintf_unlocked  gpgrt_fprintf_unlocked
929# define es_printf            gpgrt_printf
930# define es_printf_unlocked   gpgrt_printf_unlocked
931# define es_vfprintf          gpgrt_vfprintf
932# define es_vfprintf_unlocked gpgrt_vfprintf_unlocked
933# define es_setvbuf           gpgrt_setvbuf
934# define es_setbuf            gpgrt_setbuf
935# define es_set_binary        gpgrt_set_binary
936# define es_set_nonblock      gpgrt_set_nonblock
937# define es_get_nonblock      gpgrt_get_nonblock
938# define es_poll              gpgrt_poll
939# define es_tmpfile           gpgrt_tmpfile
940# define es_opaque_set        gpgrt_opaque_set
941# define es_opaque_get        gpgrt_opaque_get
942# define es_fname_set         gpgrt_fname_set
943# define es_fname_get         gpgrt_fname_get
944# define es_asprintf          gpgrt_asprintf
945# define es_vasprintf         gpgrt_vasprintf
946# define es_bsprintf          gpgrt_bsprintf
947# define es_vbsprintf         gpgrt_vbsprintf
948#endif /*GPGRT_ENABLE_ES_MACROS*/
949
950
951
952/*
953 * Base64 encode and decode functions.
954 */
955
956struct _gpgrt_b64state;
957typedef struct _gpgrt_b64state *gpgrt_b64state_t;
958
959gpgrt_b64state_t gpgrt_b64enc_start (gpgrt_stream_t stream, const char *title);
960gpg_err_code_t   gpgrt_b64enc_write (gpgrt_b64state_t state,
961                                     const void *buffer, size_t nbytes);
962gpg_err_code_t   gpgrt_b64enc_finish (gpgrt_b64state_t state);
963
964gpgrt_b64state_t gpgrt_b64dec_start (const char *title);
965gpg_error_t      gpgrt_b64dec_proc (gpgrt_b64state_t state,
966                                    void *buffer, size_t length,
967                                    size_t *r_nbytes);
968gpg_error_t      gpgrt_b64dec_finish (gpgrt_b64state_t state);
969
970
971
972/*
973 * Logging functions
974 */
975
976/* Flag values for gpgrt_log_set_prefix. */
977#define GPGRT_LOG_WITH_PREFIX  1
978#define GPGRT_LOG_WITH_TIME    2
979#define GPGRT_LOG_WITH_PID     4
980#define GPGRT_LOG_RUN_DETACHED 256
981#define GPGRT_LOG_NO_REGISTRY  512
982
983/* Log levels as used by gpgrt_log.  */
984enum gpgrt_log_levels
985  {
986    GPGRT_LOGLVL_BEGIN,
987    GPGRT_LOGLVL_CONT,
988    GPGRT_LOGLVL_INFO,
989    GPGRT_LOGLVL_WARN,
990    GPGRT_LOGLVL_ERROR,
991    GPGRT_LOGLVL_FATAL,
992    GPGRT_LOGLVL_BUG,
993    GPGRT_LOGLVL_DEBUG
994  };
995
996
997/* The next 4 functions are not thread-safe - call them early.  */
998void gpgrt_log_set_sink (const char *name, gpgrt_stream_t stream, int fd);
999void gpgrt_log_set_socket_dir_cb (const char *(*fnc)(void));
1000void gpgrt_log_set_pid_suffix_cb (int (*cb)(unsigned long *r_value));
1001void gpgrt_log_set_prefix (const char *text, unsigned int flags);
1002
1003int  gpgrt_get_errorcount (int clear);
1004void gpgrt_inc_errorcount (void);
1005const char *gpgrt_log_get_prefix (unsigned int *flags);
1006int  gpgrt_log_test_fd (int fd);
1007int  gpgrt_log_get_fd (void);
1008gpgrt_stream_t gpgrt_log_get_stream (void);
1009
1010void gpgrt_log (int level, const char *fmt, ...) GPGRT_ATTR_PRINTF(2,3);
1011void gpgrt_logv (int level, const char *fmt, va_list arg_ptr);
1012void gpgrt_logv_prefix (int level, const char *prefix,
1013                              const char *fmt, va_list arg_ptr);
1014void gpgrt_log_string (int level, const char *string);
1015void gpgrt_log_bug (const char *fmt, ...)    GPGRT_ATTR_NR_PRINTF(1,2);
1016void gpgrt_log_fatal (const char *fmt, ...)  GPGRT_ATTR_NR_PRINTF(1,2);
1017void gpgrt_log_error (const char *fmt, ...)  GPGRT_ATTR_PRINTF(1,2);
1018void gpgrt_log_info (const char *fmt, ...)   GPGRT_ATTR_PRINTF(1,2);
1019void gpgrt_log_debug (const char *fmt, ...)  GPGRT_ATTR_PRINTF(1,2);
1020void gpgrt_log_debug_string (const char *string,
1021                             const char *fmt, ...) GPGRT_ATTR_PRINTF(2,3);
1022void gpgrt_log_printf (const char *fmt, ...) GPGRT_ATTR_PRINTF(1,2);
1023void gpgrt_log_printhex (const void *buffer, size_t length,
1024                         const char *fmt, ...) GPGRT_ATTR_PRINTF(3,4);
1025void gpgrt_log_clock (const char *fmt, ...) GPGRT_ATTR_PRINTF(1,2);
1026void gpgrt_log_flush (void);
1027void _gpgrt_log_assert (const char *expr, const char *file, int line,
1028                        const char *func) GPGRT_ATTR_NORETURN;
1029
1030#ifdef GPGRT_HAVE_MACRO_FUNCTION
1031# define gpgrt_assert(expr)                                     \
1032  ((expr)                                                       \
1033   ? (void) 0                                                   \
1034   : _gpgrt_log_assert (#expr, __FILE__, __LINE__, __FUNCTION__))
1035#else /*!GPGRT_HAVE_MACRO_FUNCTION*/
1036# define gpgrt_assert(expr)                                     \
1037  ((expr)                                                       \
1038   ? (void) 0                                                   \
1039   : _gpgrt_log_assert (#expr, __FILE__, __LINE__, NULL))
1040#endif /*!GPGRT_HAVE_MACRO_FUNCTION*/
1041
1042#ifdef GPGRT_ENABLE_LOG_MACROS
1043# define log_get_errorcount      gpgrt_get_errorcount
1044# define log_inc_errorcount      gpgrt_inc_errorcount
1045# define log_set_file(a)         gpgrt_log_set_sink ((a), NULL, -1)
1046# define log_set_fd(a)           gpgrt_log_set_sink (NULL, NULL, (a))
1047# define log_set_stream(a)       gpgrt_log_set_sink (NULL, (a), -1)
1048# define log_set_socket_dir_cb   gpgrt_log_set_socket_dir_cb
1049# define log_set_pid_suffix_cb   gpgrt_log_set_pid_suffix_cb
1050# define log_set_prefix          gpgrt_log_set_prefix
1051# define log_get_prefix          gpgrt_log_get_prefix
1052# define log_test_fd             gpgrt_log_test_fd
1053# define log_get_fd              gpgrt_log_get_fd
1054# define log_get_stream          gpgrt_log_get_stream
1055# define log_log                 gpgrt_log
1056# define log_logv                gpgrt_logv
1057# define log_logv_prefix         gpgrt_logv_prefix
1058# define log_string              gpgrt_log_string
1059# define log_bug                 gpgrt_log_bug
1060# define log_fatal               gpgrt_log_fatal
1061# define log_error               gpgrt_log_error
1062# define log_info                gpgrt_log_info
1063# define log_debug               gpgrt_log_debug
1064# define log_debug_string        gpgrt_log_debug_string
1065# define log_printf              gpgrt_log_printf
1066# define log_printhex            gpgrt_log_printhex
1067# define log_clock               gpgrt_log_clock
1068# define log_flush               gpgrt_log_flush
1069# ifdef GPGRT_HAVE_MACRO_FUNCTION
1070#  define log_assert(expr)                                      \
1071  ((expr)                                                       \
1072   ? (void) 0                                                   \
1073   : _gpgrt_log_assert (#expr, __FILE__, __LINE__, __FUNCTION__))
1074# else /*!GPGRT_HAVE_MACRO_FUNCTION*/
1075#  define log_assert(expr)                                      \
1076  ((expr)                                                       \
1077   ? (void) 0                                                   \
1078   : _gpgrt_log_assert (#expr, __FILE__, __LINE__, NULL))
1079# endif /*!GPGRT_HAVE_MACRO_FUNCTION*/
1080
1081#endif /*GPGRT_ENABLE_LOG_MACROS*/
1082
1083
1084/*
1085 * Spawn functions  (Not yet available)
1086 */
1087#define GPGRT_SPAWN_NONBLOCK   16 /* Set the streams to non-blocking.      */
1088#define GPGRT_SPAWN_RUN_ASFW   64 /* Use AllowSetForegroundWindow on W32.  */
1089#define GPGRT_SPAWN_DETACHED  128 /* Start the process in the background.  */
1090
1091#if 0
1092
1093/* Function and convenience macros to create pipes.  */
1094gpg_err_code_t gpgrt_make_pipe (int filedes[2], gpgrt_stream_t *r_fp,
1095                                int direction, int nonblock);
1096#define gpgrt_create_pipe(a)              gpgrt_make_pipe ((a),NULL,  0,  0);
1097#define gpgrt_create_inbound_pipe(a,b,c)  gpgrt_make_pipe ((a), (b), -1,(c));
1098#define gpgrt_create_outbound_pipe(a,b,c) gpgrt_make_pipe ((a), (b),  1,(c));
1099
1100
1101/* Fork and exec PGMNAME.  */
1102gpg_err_code_t gpgrt_spawn_process (const char *pgmname, const char *argv[],
1103                                    int *execpt, void (*preexec)(void),
1104                                    unsigned int flags,
1105                                    gpgrt_stream_t *r_infp,
1106                                    gpgrt_stream_t *r_outfp,
1107                                    gpgrt_stream_t *r_errfp,
1108                                    pid_t *pid);
1109
1110/* Fork and exec PGNNAME and connect the process to the given FDs.  */
1111gpg_err_code_t gpgrt_spawn_process_fd (const char *pgmname, const char *argv[],
1112                                       int infd, int outfd, int errfd,
1113                                       pid_t *pid);
1114
1115/* Fork and exec PGMNAME as a detached process.  */
1116gpg_err_code_t gpgrt_spawn_process_detached (const char *pgmname,
1117                                             const char *argv[],
1118                                             const char *envp[] );
1119
1120/* Wait for a single process.  */
1121gpg_err_code_t gpgrt_wait_process (const char *pgmname, pid_t pid, int hang,
1122                                int *r_exitcode);
1123
1124/* Wait for a multiple processes.  */
1125gpg_err_code_t gpgrt_wait_processes (const char **pgmnames, pid_t *pids,
1126                                     size_t count, int hang, int *r_exitcodes);
1127
1128/* Kill the process identified by PID.  */
1129void gpgrt_kill_process (pid_t pid);
1130
1131/* Release process resources identified by PID.  */
1132void gpgrt_release_process (pid_t pid);
1133
1134#endif /*0*/
1135
1136
1137
1138/*
1139 * Option parsing.
1140 */
1141
1142struct _gpgrt_argparse_internal_s;
1143typedef struct
1144{
1145  int  *argc;	      /* Pointer to ARGC (value subject to change). */
1146  char ***argv;	      /* Pointer to ARGV (value subject to change). */
1147  unsigned int flags; /* Global flags.  May be set prior to calling the
1148                         parser.  The parser may change the value.  */
1149  int err;            /* Print error description for last option.
1150                         Either 0,  ARGPARSE_PRINT_WARNING or
1151                         ARGPARSE_PRINT_ERROR.  */
1152  unsigned int lineno;/* The current line number.  */
1153  int r_opt; 	      /* Returns option code. */
1154  int r_type;	      /* Returns type of option value.  */
1155  union {
1156    int   ret_int;
1157    long  ret_long;
1158    unsigned long ret_ulong;
1159    char *ret_str;
1160  } r;		      /* Return values */
1161
1162  struct _gpgrt_argparse_internal_s *internal;
1163} gpgrt_argparse_t;
1164
1165
1166typedef struct
1167{
1168  int          short_opt;
1169  const char  *long_opt;
1170  unsigned int flags;
1171  const char  *description; /* Optional description. */
1172} gpgrt_opt_t;
1173
1174
1175#ifdef GPGRT_ENABLE_ARGPARSE_MACROS
1176
1177/* Global flags for (gpgrt_argparse_t).flags.  */
1178#define ARGPARSE_FLAG_KEEP        1  /* Do not remove options form argv.     */
1179#define ARGPARSE_FLAG_ALL         2  /* Do not stop at last option but return
1180                                        remaining args with R_OPT set to -1. */
1181#define ARGPARSE_FLAG_MIXED       4  /* Assume options and args are mixed.   */
1182#define ARGPARSE_FLAG_NOSTOP      8  /* Do not stop processing at "--".      */
1183#define ARGPARSE_FLAG_ARG0       16  /* Do not skip the first arg.           */
1184#define ARGPARSE_FLAG_ONEDASH    32  /* Allow long options with one dash.    */
1185#define ARGPARSE_FLAG_NOVERSION  64  /* No output for "--version".           */
1186#define ARGPARSE_FLAG_RESET     128  /* Request to reset the internal state. */
1187#define ARGPARSE_FLAG_STOP_SEEN 256  /* Set to true if a "--" has been seen. */
1188#define ARGPARSE_FLAG_NOLINENO  512  /* Do not zero the lineno field.        */
1189#define ARGPARSE_FLAG_SYS      1024  /* Use system config file.              */
1190#define ARGPARSE_FLAG_USER     2048  /* Use user config file.                */
1191#define ARGPARSE_FLAG_VERBOSE  4096  /* Print additional argparser info.     */
1192#define ARGPARSE_FLAG_USERVERS 8192  /* Try version-ed user config files.    */
1193#define ARGPARSE_FLAG_WITHATTR 16384 /* Return attribute bits.               */
1194
1195/* Constants for (gpgrt_argparse_t).err.  */
1196#define ARGPARSE_PRINT_WARNING  1    /* Print a diagnostic.                  */
1197#define ARGPARSE_PRINT_ERROR    2    /* Print a diagnostic and call exit.    */
1198
1199/* Special return values of gpgrt_argparse.  */
1200#define ARGPARSE_IS_ARG            (-1)
1201#define ARGPARSE_INVALID_OPTION    (-2)
1202#define ARGPARSE_MISSING_ARG       (-3)
1203#define ARGPARSE_KEYWORD_TOO_LONG  (-4)
1204#define ARGPARSE_READ_ERROR        (-5)
1205#define ARGPARSE_UNEXPECTED_ARG    (-6)
1206#define ARGPARSE_INVALID_COMMAND   (-7)
1207#define ARGPARSE_AMBIGUOUS_OPTION  (-8)
1208#define ARGPARSE_AMBIGUOUS_COMMAND (-9)
1209#define ARGPARSE_INVALID_ALIAS     (-10)
1210#define ARGPARSE_OUT_OF_CORE       (-11)
1211#define ARGPARSE_INVALID_ARG       (-12)
1212#define ARGPARSE_PERMISSION_ERROR  (-13)
1213#define ARGPARSE_NO_CONFFILE       (-14)
1214#define ARGPARSE_CONFFILE          (-15)
1215#define ARGPARSE_INVALID_META      (-16)
1216#define ARGPARSE_UNKNOWN_META      (-17)
1217#define ARGPARSE_UNEXPECTED_META   (-18)
1218
1219/* Flags for the option descriptor (gpgrt_opt_t)->flags.  Note that a
1220 * TYPE constant may be or-ed with the OPT constants but when used as
1221 * return value in r_type these OPT constants are normally not
1222 * included.  However with ARGPARSE_FLAG_WITHATTR used and an option
1223 * would normally not be returned, it is returned but
1224 * ARGPARSE_OPT_IGNORE is then set; further ARPARSE_ATTR_* are set.
1225 */
1226#define ARGPARSE_TYPE_MASK   0x0007  /* Mask for the type bits.           */
1227#define ARGPARSE_TYPE_NONE        0  /* Does not take an argument.        */
1228#define ARGPARSE_TYPE_INT         1  /* Takes an int argument.            */
1229#define ARGPARSE_TYPE_STRING      2  /* Takes a string argument.          */
1230#define ARGPARSE_TYPE_LONG        3  /* Takes a long argument.            */
1231#define ARGPARSE_TYPE_ULONG       4  /* Takes an unsigned long argument.  */
1232#define ARGPARSE_OPT_OPTIONAL (1<<3) /* Argument is optional.             */
1233#define ARGPARSE_OPT_PREFIX   (1<<4) /* Allow 0x etc. prefixed values.    */
1234#define ARGPARSE_OPT_IGNORE   (1<<6) /* Ignore command or option.         */
1235#define ARGPARSE_OPT_COMMAND  (1<<7) /* The argument is a command.        */
1236#define ARGPARSE_OPT_CONFFILE (1<<8) /* The value is a conffile.          */
1237#define ARGPARSE_OPT_HEADER   (1<<9) /* The value is printed as a header. */
1238#define ARGPARSE_OPT_VERBATIM (1<<10)/* The value is printed verbatim.    */
1239#define ARGPARSE_ATTR_FORCE   (1<<14)/* Attribute force is set.           */
1240#define ARGPARSE_ATTR_IGNORE  (1<<15)/* Attribute ignore is set.          */
1241
1242/* A set of macros to make option definitions easier to read.  */
1243#define ARGPARSE_x(s,l,t,f,d) \
1244     { (s), (l), ARGPARSE_TYPE_ ## t | (f), (d) }
1245
1246#define ARGPARSE_s(s,l,t,d) \
1247     { (s), (l), ARGPARSE_TYPE_ ## t, (d) }
1248#define ARGPARSE_s_n(s,l,d) \
1249     { (s), (l), ARGPARSE_TYPE_NONE, (d) }
1250#define ARGPARSE_s_i(s,l,d) \
1251     { (s), (l), ARGPARSE_TYPE_INT, (d) }
1252#define ARGPARSE_s_s(s,l,d) \
1253     { (s), (l), ARGPARSE_TYPE_STRING, (d) }
1254#define ARGPARSE_s_l(s,l,d) \
1255     { (s), (l), ARGPARSE_TYPE_LONG, (d) }
1256#define ARGPARSE_s_u(s,l,d) \
1257     { (s), (l), ARGPARSE_TYPE_ULONG, (d) }
1258
1259#define ARGPARSE_o(s,l,t,d) \
1260     { (s), (l), (ARGPARSE_TYPE_ ## t  | ARGPARSE_OPT_OPTIONAL), (d) }
1261#define ARGPARSE_o_n(s,l,d) \
1262     { (s), (l), (ARGPARSE_TYPE_NONE   | ARGPARSE_OPT_OPTIONAL), (d) }
1263#define ARGPARSE_o_i(s,l,d) \
1264     { (s), (l), (ARGPARSE_TYPE_INT    | ARGPARSE_OPT_OPTIONAL), (d) }
1265#define ARGPARSE_o_s(s,l,d) \
1266     { (s), (l), (ARGPARSE_TYPE_STRING | ARGPARSE_OPT_OPTIONAL), (d) }
1267#define ARGPARSE_o_l(s,l,d) \
1268     { (s), (l), (ARGPARSE_TYPE_LONG   | ARGPARSE_OPT_OPTIONAL), (d) }
1269#define ARGPARSE_o_u(s,l,d) \
1270     { (s), (l), (ARGPARSE_TYPE_ULONG  | ARGPARSE_OPT_OPTIONAL), (d) }
1271
1272#define ARGPARSE_p(s,l,t,d) \
1273     { (s), (l), (ARGPARSE_TYPE_ ## t  | ARGPARSE_OPT_PREFIX), (d) }
1274#define ARGPARSE_p_n(s,l,d) \
1275     { (s), (l), (ARGPARSE_TYPE_NONE   | ARGPARSE_OPT_PREFIX), (d) }
1276#define ARGPARSE_p_i(s,l,d) \
1277     { (s), (l), (ARGPARSE_TYPE_INT    | ARGPARSE_OPT_PREFIX), (d) }
1278#define ARGPARSE_p_s(s,l,d) \
1279     { (s), (l), (ARGPARSE_TYPE_STRING | ARGPARSE_OPT_PREFIX), (d) }
1280#define ARGPARSE_p_l(s,l,d) \
1281     { (s), (l), (ARGPARSE_TYPE_LONG   | ARGPARSE_OPT_PREFIX), (d) }
1282#define ARGPARSE_p_u(s,l,d) \
1283     { (s), (l), (ARGPARSE_TYPE_ULONG  | ARGPARSE_OPT_PREFIX), (d) }
1284
1285#define ARGPARSE_op(s,l,t,d) \
1286     { (s), (l), (ARGPARSE_TYPE_ ## t \
1287                  | ARGPARSE_OPT_OPTIONAL | ARGPARSE_OPT_PREFIX), (d) }
1288#define ARGPARSE_op_n(s,l,d) \
1289     { (s), (l), (ARGPARSE_TYPE_NONE \
1290                  | ARGPARSE_OPT_OPTIONAL | ARGPARSE_OPT_PREFIX), (d) }
1291#define ARGPARSE_op_i(s,l,d) \
1292     { (s), (l), (ARGPARSE_TYPE_INT \
1293                  | ARGPARSE_OPT_OPTIONAL | ARGPARSE_OPT_PREFIX), (d) }
1294#define ARGPARSE_op_s(s,l,d) \
1295     { (s), (l), (ARGPARSE_TYPE_STRING \
1296                  | ARGPARSE_OPT_OPTIONAL | ARGPARSE_OPT_PREFIX), (d) }
1297#define ARGPARSE_op_l(s,l,d) \
1298     { (s), (l), (ARGPARSE_TYPE_LONG \
1299                  | ARGPARSE_OPT_OPTIONAL | ARGPARSE_OPT_PREFIX), (d) }
1300#define ARGPARSE_op_u(s,l,d) \
1301     { (s), (l), (ARGPARSE_TYPE_ULONG \
1302                  | ARGPARSE_OPT_OPTIONAL | ARGPARSE_OPT_PREFIX), (d) }
1303
1304#define ARGPARSE_c(s,l,d) \
1305     { (s), (l), (ARGPARSE_TYPE_NONE | ARGPARSE_OPT_COMMAND), (d) }
1306
1307#define ARGPARSE_conffile(s,l,d) \
1308  { (s), (l), (ARGPARSE_TYPE_STRING|ARGPARSE_OPT_CONFFILE), (d) }
1309
1310#define ARGPARSE_noconffile(s,l,d) \
1311  { (s), (l), (ARGPARSE_TYPE_NONE|ARGPARSE_OPT_CONFFILE), (d) }
1312
1313/* This macro is for stub or obsolete options.  */
1314#define ARGPARSE_ignore(s,l)                    \
1315  { (s), (l), (ARGPARSE_OPT_IGNORE), "@" }
1316
1317/* This is a legacy version of ARGPARSE_verbatim which really does
1318 * verbatim printing.  */
1319#define ARGPARSE_group(s,d) \
1320  { (s), NULL, 0, (d) }
1321
1322/* Verbatim print the string D in the help output.  It does not make
1323 * use of the "@" hack as ARGPARSE_group does.  */
1324#define ARGPARSE_verbatim(d) \
1325  { 1, NULL, (ARGPARSE_OPT_VERBATIM), (d) }
1326
1327/* Same as ARGPARSE_verbatim but also print a colon and a LF.  N can
1328 * be used give a symbolic name to the header.  Nothing is printed if
1329 * D is the empty string.  */
1330#define ARGPARSE_header(n,d) \
1331  { 1, (n), (ARGPARSE_OPT_HEADER), (d) }
1332
1333/* Mark the end of the list (mandatory).  */
1334#define ARGPARSE_end() \
1335  { 0, NULL, 0, NULL }
1336
1337#endif /* GPGRT_ENABLE_ARGPARSE_MACROS */
1338
1339/* Values used for gpgrt_set_confdir.  */
1340#define GPGRT_CONFDIR_USER 1   /* The user's configuration dir.    */
1341#define GPGRT_CONFDIR_SYS  2   /* The systems's configuration dir. */
1342
1343/* Take care: gpgrt_argparse keeps state in ARG and requires that
1344 * either ARGPARSE_FLAG_RESET is used after OPTS has been changed or
1345 * gpgrt_argparse (NULL, ARG, NULL) is called first.  */
1346int gpgrt_argparse (gpgrt_stream_t fp,
1347                    gpgrt_argparse_t *arg, gpgrt_opt_t *opts);
1348int gpgrt_argparser (gpgrt_argparse_t *arg, gpgrt_opt_t *opts,
1349                     const char *confname);
1350void gpgrt_usage (int level);
1351const char *gpgrt_strusage (int level);
1352void gpgrt_set_strusage (const char *(*f)(int));
1353void gpgrt_set_usage_outfnc (int (*f)(int, const char *));
1354void gpgrt_set_fixed_string_mapper (const char *(*f)(const char*));
1355void gpgrt_set_confdir (int what, const char *name);
1356
1357
1358/*
1359 * Various helper functions
1360 */
1361
1362/* Compare arbitrary version strings.  For the standard m.n.o version
1363 * numbering scheme a LEVEL of 3 is suitable; see the manual.  */
1364int gpgrt_cmp_version (const char *a, const char *b, int level);
1365
1366/* Construct a filename from the NULL terminated list of parts.  Tilde
1367 * expansion is done for the first argument.  The caller must release
1368 * the result using gpgrt_free; on error ERRNO is set and NULL
1369 * returned.  The second function returns an absolute filename.  */
1370char *gpgrt_fnameconcat (const char *first, ...) GPGRT_ATTR_SENTINEL(0);
1371char *gpgrt_absfnameconcat (const char *first, ...) GPGRT_ATTR_SENTINEL(0);
1372
1373
1374#ifdef __cplusplus
1375}
1376#endif
1377#endif	/* GPGRT_H */
1378#endif	/* GPG_ERROR_H */
1379