summary refs log tree commit diff stats
path: root/libotr/libgpg-error-1.42/src/gpg-error.h.in
blob: d2c3b8d3a16b520c86fca508a3f4e878f341be22 (plain) (blame)
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
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
/* gpg-error.h or gpgrt.h - Common code for GnuPG and others.    -*- c -*-
 * Copyright (C) 2001-2020 g10 Code GmbH
 *
 * This file is part of libgpg-error (aka libgpgrt).
 *
 * libgpg-error is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public License
 * as published by the Free Software Foundation; either version 2.1 of
 * the License, or (at your option) any later version.
 *
 * libgpg-error is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this program; if not, see <https://www.gnu.org/licenses/>.
 * SPDX-License-Identifier: LGPL-2.1+
 *
 * @configure_input@
 */

/* The GnuPG project consists of many components.  Error codes are
 * exchanged between all components.  The common error codes and their
 * user-presentable descriptions are kept into a shared library to
 * allow adding new error codes and components without recompiling any
 * of the other components.  In addition to error codes this library
 * also features several other groups of functions which are common to
 * all GnuPG components.  They may be used by independet project as
 * well.  The interfaces will not change in a backward incompatible way.
 *
 * An error code together with an error source build up an error
 * value.  As the error value is been passed from one component to
 * another, it preserves the information about the source and nature
 * of the error.
 *
 * A component of the GnuPG project can define the following macros to
 * tune the behaviour of the library:
 *
 * GPG_ERR_SOURCE_DEFAULT: Define to an error source of type
 * gpg_err_source_t to make that source the default for gpg_error().
 * Otherwise GPG_ERR_SOURCE_UNKNOWN is used as default.
 *
 * 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.
 *
 * GPGRT_ENABLE_ES_MACROS: Define to provide "es_" macros for the
 * estream functions.
 *
 * GPGRT_ENABLE_LOG_MACROS: Define to provide short versions of the
 * log functions.
 *
 * GPGRT_ENABLE_ARGPARSE_MACROS: Needs to be defined to provide the
 * mandatory macros of the argparse interface.
 */

#ifndef GPG_ERROR_H
#define GPG_ERROR_H 1
#ifndef GPGRT_H
#define GPGRT_H 1

#include <stddef.h>
#include <stdio.h>
#include <stdarg.h>

/* The version string of this header. */
#define GPG_ERROR_VERSION @version@
#define GPGRT_VERSION     @version@

/* The version number of this header. */
#define GPG_ERROR_VERSION_NUMBER @version-number@
#define GPGRT_VERSION_NUMBER     @version-number@


#ifdef __GNUC__
# define GPG_ERR_INLINE __inline__
#elif defined(_MSC_VER) && _MSC_VER >= 1300
# define GPG_ERR_INLINE __inline
#elif defined (__STDC_VERSION__) && __STDC_VERSION__ >= 199901L
# define GPG_ERR_INLINE inline
#else
# ifndef GPG_ERR_INLINE
#  define GPG_ERR_INLINE
# endif
#endif

#ifdef __cplusplus
extern "C" {
#if 0 /* just to make Emacs auto-indent happy */
}
#endif
#endif /* __cplusplus */



/* The error source type gpg_err_source_t.
 *
 * Where as the Poo out of a welle small
 * Taketh his firste springing and his sours.
 *					--Chaucer.
 */

/* Only use free slots, never change or reorder the existing
 * entries.  */
typedef enum
  {
@include:err-sources@
    /* This is one more than the largest allowed entry.  */
    GPG_ERR_SOURCE_DIM = 128
  } gpg_err_source_t;


/* The error code type gpg_err_code_t.  */

/* Only use free slots, never change or reorder the existing
 * entries.  */
typedef enum
  {
@include:err-codes@
    /* The following error codes are used to map system errors.  */
#define GPG_ERR_SYSTEM_ERROR	(1 << 15)
@include:errnos@
    /* This is one more than the largest allowed entry.  */
    GPG_ERR_CODE_DIM = 65536
  } gpg_err_code_t;


/* The error value type gpg_error_t.  */

/* We would really like to use bit-fields in a struct, but using
 * structs as return values can cause binary compatibility issues, in
 * particular if you want to do it efficiently (also see
 * -freg-struct-return option to GCC).  */
typedef unsigned int gpg_error_t;

/* We use the lowest 16 bits of gpg_error_t for error codes.  The 16th
 * bit indicates system errors.  */
#define GPG_ERR_CODE_MASK	(GPG_ERR_CODE_DIM - 1)

/* Bits 17 to 24 are reserved.  */

/* We use the upper 7 bits of gpg_error_t for error sources.  */
#define GPG_ERR_SOURCE_MASK	(GPG_ERR_SOURCE_DIM - 1)
#define GPG_ERR_SOURCE_SHIFT	24

/* The highest bit is reserved.  It shouldn't be used to prevent
 * potential negative numbers when transmitting error values as
 * text.  */


/*
 * GCC feature test.
 */
#if __GNUC__
# define _GPG_ERR_GCC_VERSION (__GNUC__ * 10000 \
                               + __GNUC_MINOR__ * 100 \
                               + __GNUC_PATCHLEVEL__)
#else
# define _GPG_ERR_GCC_VERSION 0
#endif

#undef _GPG_ERR_HAVE_CONSTRUCTOR
#if _GPG_ERR_GCC_VERSION > 30100
# define _GPG_ERR_CONSTRUCTOR	__attribute__ ((__constructor__))
# define _GPG_ERR_HAVE_CONSTRUCTOR
#else
# define _GPG_ERR_CONSTRUCTOR
#endif

#define GPGRT_GCC_VERSION  _GPG_ERR_GCC_VERSION

#if _GPG_ERR_GCC_VERSION >= 29200
# define _GPGRT__RESTRICT __restrict__
#else
# define _GPGRT__RESTRICT
#endif

/* The noreturn attribute.  */
#if _GPG_ERR_GCC_VERSION >= 20500
# define GPGRT_ATTR_NORETURN   __attribute__ ((__noreturn__))
#else
# define GPGRT_ATTR_NORETURN
#endif

/* The printf attributes.  */
#if _GPG_ERR_GCC_VERSION >= 40400
# define GPGRT_ATTR_PRINTF(f, a) \
                    __attribute__ ((format(__gnu_printf__,f,a)))
# define GPGRT_ATTR_NR_PRINTF(f, a) \
                    __attribute__ ((__noreturn__, format(__gnu_printf__,f,a)))
#elif _GPG_ERR_GCC_VERSION >= 20500
# define GPGRT_ATTR_PRINTF(f, a) \
                    __attribute__ ((format(printf,f,a)))
# define GPGRT_ATTR_NR_PRINTF(f, a) \
                    __attribute__ ((__noreturn__, format(printf,f,a)))
#else
# define GPGRT_ATTR_PRINTF(f, a)
# define GPGRT_ATTR_NR_PRINTF(f, a)
#endif
#if _GPG_ERR_GCC_VERSION >= 20800
# define GPGRT_ATTR_FORMAT_ARG(a)  __attribute__ ((__format_arg__ (a)))
#else
# define GPGRT_ATTR_FORMAT_ARG(a)
#endif

/* The sentinel attribute.  */
#if _GPG_ERR_GCC_VERSION >= 40000
# define GPGRT_ATTR_SENTINEL(a)  __attribute__ ((sentinel(a)))
#else
# define GPGRT_ATTR_SENTINEL(a)
#endif

/* The used and unused attributes.
 * I am not sure since when the unused attribute is really supported.
 * In any case it it only needed for gcc versions which print a
 * warning.  Thus let us require gcc >= 3.5.  */
#if _GPG_ERR_GCC_VERSION >= 40000
# define GPGRT_ATTR_USED  __attribute__ ((used))
#else
# define GPGRT_ATTR_USED
#endif
#if _GPG_ERR_GCC_VERSION >= 30500
# define GPGRT_ATTR_UNUSED  __attribute__ ((unused))
#else
# define GPGRT_ATTR_UNUSED
#endif

/* The deprecated attribute.  */
#if _GPG_ERR_GCC_VERSION >= 30100
# define GPGRT_ATTR_DEPRECATED  __attribute__ ((__deprecated__))
#else
# define GPGRT_ATTR_DEPRECATED
#endif

/* The pure attribute.  */
#if _GPG_ERR_GCC_VERSION >= 29600
# define GPGRT_ATTR_PURE  __attribute__ ((__pure__))
#else
# define GPGRT_ATTR_PURE
#endif

/* The malloc attribute.  */
#if _GPG_ERR_GCC_VERSION >= 30200
# define GPGRT_ATTR_MALLOC  __attribute__ ((__malloc__))
#else
# define GPGRT_ATTR_MALLOC
#endif

/* A macro defined if a GCC style __FUNCTION__ macro is available.  */
#undef GPGRT_HAVE_MACRO_FUNCTION
#if _GPG_ERR_GCC_VERSION >= 20500
# define GPGRT_HAVE_MACRO_FUNCTION 1
#endif

/* A macro defined if the pragma GCC push_options is available.  */
#undef GPGRT_HAVE_PRAGMA_GCC_PUSH
#if _GPG_ERR_GCC_VERSION >= 40400
# define GPGRT_HAVE_PRAGMA_GCC_PUSH 1
#endif

/* Detect LeakSanitizer (LSan) support for GCC and Clang based on
 * whether AddressSanitizer (ASAN) is enabled via -fsanitize=address).
 * Note that -fsanitize=leak just affect the linker options which
 * cannot be detected here.  In that case you have to define the
 * GPGRT_HAVE_LEAK_SANITIZER macro manually.  */
#ifdef __GNUC__
# ifdef __SANITIZE_ADDRESS__
#  define GPGRT_HAVE_LEAK_SANITIZER
# elif defined(__has_feature)
#  if __has_feature(address_sanitizer)
#   define GPGRT_HAVE_LEAK_SANITIZER
#  endif
# endif
#endif


/* The new name for the inline macro.  */
#define GPGRT_INLINE GPG_ERR_INLINE

#ifdef GPGRT_HAVE_LEAK_SANITIZER
# include <sanitizer/lsan_interface.h>
#endif

/* Mark heap objects as non-leaked memory. */
static GPGRT_INLINE void
gpgrt_annotate_leaked_object (const void *p)
{
#ifdef GPGRT_HAVE_LEAK_SANITIZER
  __lsan_ignore_object(p);
#else
  (void)p;
#endif
}


/*
 * Initialization function.
 */

/* Initialize the library.  This function should be run early.  */
gpg_error_t gpg_err_init (void) _GPG_ERR_CONSTRUCTOR;

/* If this is defined, the library is already initialized by the
   constructor and does not need to be initialized explicitely.  */
#undef GPG_ERR_INITIALIZED
#ifdef _GPG_ERR_HAVE_CONSTRUCTOR
# define GPG_ERR_INITIALIZED	1
# define gpgrt_init() do { gpg_err_init (); } while (0)
#else
# define gpgrt_init() do { ; } while (0)
#endif

/* See the source on how to use the deinit function; it is usually not
   required.  */
void gpg_err_deinit (int mode);

/* Register blocking system I/O clamping functions.  */
void gpgrt_set_syscall_clamp (void (*pre)(void), void (*post)(void));

/* Get current I/O clamping functions.  */
void gpgrt_get_syscall_clamp (void (**r_pre)(void), void (**r_post)(void));

/* Register a custom malloc/realloc/free function.  */
void gpgrt_set_alloc_func  (void *(*f)(void *a, size_t n));

/* Register an emergency cleanup handler.  */
void gpgrt_add_emergency_cleanup (void (*f)(void));

/* Wrapper around abort to make sure emergency cleanups are run.  */
void gpgrt_abort (void) GPGRT_ATTR_NORETURN;



/*
 * Constructor and accessor functions.
 */

/* Construct an error value from an error code and source.  Within a
 * subsystem, use gpg_error.  */
static GPG_ERR_INLINE gpg_error_t
gpg_err_make (gpg_err_source_t source, gpg_err_code_t code)
{
  return code == GPG_ERR_NO_ERROR ? GPG_ERR_NO_ERROR
    : (((source & GPG_ERR_SOURCE_MASK) << GPG_ERR_SOURCE_SHIFT)
       | (code & GPG_ERR_CODE_MASK));
}


/* The user should define GPG_ERR_SOURCE_DEFAULT before including this
 * file to specify a default source for gpg_error.  */
#ifndef GPG_ERR_SOURCE_DEFAULT
#define GPG_ERR_SOURCE_DEFAULT	GPG_ERR_SOURCE_UNKNOWN
#endif

static GPG_ERR_INLINE gpg_error_t
gpg_error (gpg_err_code_t code)
{
  return gpg_err_make (GPG_ERR_SOURCE_DEFAULT, code);
}


/* Retrieve the error code from an error value.  */
static GPG_ERR_INLINE gpg_err_code_t
gpg_err_code (gpg_error_t err)
{
  return (gpg_err_code_t) (err & GPG_ERR_CODE_MASK);
}


/* Retrieve the error source from an error value.  */
static GPG_ERR_INLINE gpg_err_source_t
gpg_err_source (gpg_error_t err)
{
  return (gpg_err_source_t) ((err >> GPG_ERR_SOURCE_SHIFT)
			     & GPG_ERR_SOURCE_MASK);
}


/* String functions.  */

/* Return a pointer to a string containing a description of the error
 * code in the error value ERR.  This function is not thread-safe.  */
const char *gpg_strerror (gpg_error_t err);

/* Return the error string for ERR in the user-supplied buffer BUF of
 * size BUFLEN.  This function is, in contrast to gpg_strerror,
 * thread-safe if a thread-safe strerror_r() function is provided by
 * the system.  If the function succeeds, 0 is returned and BUF
 * contains the string describing the error.  If the buffer was not
 * large enough, ERANGE is returned and BUF contains as much of the
 * beginning of the error string as fits into the buffer.  */
int gpg_strerror_r (gpg_error_t err, char *buf, size_t buflen);

/* Return a pointer to a string containing a description of the error
 * source in the error value ERR.  */
const char *gpg_strsource (gpg_error_t err);


/*
 * Mapping of system errors (errno).
 */

/* Retrieve the error code for the system error ERR.  This returns
 * GPG_ERR_UNKNOWN_ERRNO if the system error is not mapped (report
 * this). */
gpg_err_code_t gpg_err_code_from_errno (int err);

/* Retrieve the system error for the error code CODE.  This returns 0
 * if CODE is not a system error code.  */
int gpg_err_code_to_errno (gpg_err_code_t code);

/* Retrieve the error code directly from the ERRNO variable.  This
 * returns GPG_ERR_UNKNOWN_ERRNO if the system error is not mapped
 * (report this) and GPG_ERR_MISSING_ERRNO if ERRNO has the value 0. */
gpg_err_code_t gpg_err_code_from_syserror (void);

/* Mapper for SQLite primary error codes.  */
static GPG_ERR_INLINE gpg_error_t
gpg_err_code_from_sqlite (int sqlres)
{
  return sqlres? GPG_ERR_SQL_OK + (sqlres & 0xff) : 0;
}


/* Set the ERRNO variable.  This function is the preferred way to set
 * ERRNO due to peculiarities on WindowsCE.  */
void gpg_err_set_errno (int err);

/* Return or check the version.  Both functions are identical.  */
const char *gpgrt_check_version (const char *req_version);
const char *gpg_error_check_version (const char *req_version);

/* System specific type definitions.  */
@define:pid_t@
@define:gpgrt_ssize_t@
@define:gpgrt_off_t@

@include:os-add@

/* Self-documenting convenience functions.  */

static GPG_ERR_INLINE gpg_error_t
gpg_err_make_from_errno (gpg_err_source_t source, int err)
{
  return gpg_err_make (source, gpg_err_code_from_errno (err));
}


static GPG_ERR_INLINE gpg_error_t
gpg_error_from_errno (int err)
{
  return gpg_error (gpg_err_code_from_errno (err));
}

static GPG_ERR_INLINE gpg_error_t
gpg_error_from_syserror (void)
{
  return gpg_error (gpg_err_code_from_syserror ());
}



/*
 * Malloc and friends
 */

void *gpgrt_realloc (void *a, size_t n);
void *gpgrt_reallocarray (void *a, size_t oldnmemb, size_t nmemb, size_t size);
void *gpgrt_malloc (size_t n);
void *gpgrt_calloc (size_t n, size_t m);
char *gpgrt_strdup (const char *string);
char *gpgrt_strconcat (const char *s1, ...) GPGRT_ATTR_SENTINEL(0);
void gpgrt_free (void *a);


/*
 * System specific function wrappers.
 */

/* A getenv replacement which mallocs the returned string.  */
char *gpgrt_getenv (const char *name);

/* A setenv and a unsetenv replacement.*/
gpg_err_code_t gpgrt_setenv (const char *name,
                             const char *value, int overwrite);
#define gpgrt_unsetenv(n) gpgrt_setenv ((n), NULL, 1)

/* A wrapper around mkdir using a string for the mode.  */
gpg_err_code_t gpgrt_mkdir (const char *name, const char *modestr);

/* A simple wrapper around chdir.  */
gpg_err_code_t gpgrt_chdir (const char *name);

/* Return the current WD as a malloced string.  */
char *gpgrt_getcwd (void);

/* A wrapper around access to handle UTF-8 on Windows.  */
gpg_err_code_t gpgrt_access (const char *fname, int mode);




/*
 * Lock functions.
 */

@include:lock-obj@

#define GPGRT_LOCK_DEFINE(name) \
  static gpgrt_lock_t name  = GPGRT_LOCK_INITIALIZER

/* NB: If GPGRT_LOCK_DEFINE is not used, zero out the lock variable
   before passing it to gpgrt_lock_init.  */
gpg_err_code_t gpgrt_lock_init (gpgrt_lock_t *lockhd);
gpg_err_code_t gpgrt_lock_lock (gpgrt_lock_t *lockhd);
gpg_err_code_t gpgrt_lock_trylock (gpgrt_lock_t *lockhd);
gpg_err_code_t gpgrt_lock_unlock (gpgrt_lock_t *lockhd);
gpg_err_code_t gpgrt_lock_destroy (gpgrt_lock_t *lockhd);



/*
 * Thread functions.
 */

gpg_err_code_t gpgrt_yield (void);




/*
 * Estream
 */

/* The definition of this struct is entirely private.  You must not
   use it for anything.  It is only here so some functions can be
   implemented as macros.  */
struct _gpgrt_stream_internal;
struct _gpgrt__stream
{
  /* The layout of this struct must never change.  It may be grown,
     but only if all functions which access the new members are
     versioned.  */

  /* Various flags.  */
  struct {
    unsigned int magic: 16;
    unsigned int writing: 1;
    unsigned int reserved: 15;
  } flags;

  /* A pointer to the stream buffer.  */
  unsigned char *buffer;

  /* The size of the buffer in bytes.  */
  size_t buffer_size;

  /* The length of the usable data in the buffer, only valid when in
     read mode (see flags).  */
  size_t data_len;

  /* The current position of the offset pointer, valid in read and
     write mode.  */
  size_t data_offset;

  size_t data_flushed;
  unsigned char *unread_buffer;
  size_t unread_buffer_size;

  /* The number of unread bytes.  */
  size_t unread_data_len;

  /* A pointer to our internal data for this stream.  */
  struct _gpgrt_stream_internal *intern;
};

/* The opaque type for an estream.  */
typedef struct _gpgrt__stream *gpgrt_stream_t;
#ifdef GPGRT_ENABLE_ES_MACROS
typedef struct _gpgrt__stream *estream_t;
#endif

typedef @api_ssize_t@ (*gpgrt_cookie_read_function_t) (void *cookie,
                                                 void *buffer, size_t size);
typedef @api_ssize_t@ (*gpgrt_cookie_write_function_t) (void *cookie,
                                                  const void *buffer,
                                                  size_t size);
typedef int (*gpgrt_cookie_seek_function_t) (void *cookie,
                                             gpgrt_off_t *pos, int whence);
typedef int (*gpgrt_cookie_close_function_t) (void *cookie);

struct _gpgrt_cookie_io_functions
{
  gpgrt_cookie_read_function_t func_read;
  gpgrt_cookie_write_function_t func_write;
  gpgrt_cookie_seek_function_t func_seek;
  gpgrt_cookie_close_function_t func_close;
};
typedef struct _gpgrt_cookie_io_functions gpgrt_cookie_io_functions_t;
#ifdef GPGRT_ENABLE_ES_MACROS
typedef struct _gpgrt_cookie_io_functions  es_cookie_io_functions_t;
#define es_cookie_read_function_t  gpgrt_cookie_read_function_t
#define es_cookie_write_function_t gpgrt_cookie_read_function_t
#define es_cookie_seek_function_t  gpgrt_cookie_read_function_t
#define es_cookie_close_function_t gpgrt_cookie_read_function_t
#endif

enum gpgrt_syshd_types
  {
    GPGRT_SYSHD_NONE = 0,  /* No system handle available.                   */
    GPGRT_SYSHD_FD = 1,    /* A file descriptor as returned by open().      */
    GPGRT_SYSHD_SOCK = 2,  /* A socket as returned by socket().             */
    GPGRT_SYSHD_RVID = 3,  /* A rendezvous id (see libassuan's gpgcedev.c).  */
    GPGRT_SYSHD_HANDLE = 4 /* A HANDLE object (Windows).                    */
  };

struct _gpgrt_syshd
{
  enum gpgrt_syshd_types type;
  union {
    int fd;
    int sock;
    int rvid;
    void *handle;
  } u;
};
typedef struct _gpgrt_syshd gpgrt_syshd_t;
#ifdef GPGRT_ENABLE_ES_MACROS
typedef struct _gpgrt_syshd es_syshd_t;
#define ES_SYSHD_NONE   GPGRT_SYSHD_NONE
#define ES_SYSHD_FD     GPGRT_SYSHD_FD
#define ES_SYSHD_SOCK   GPGRT_SYSHD_SOCK
#define ES_SYSHD_RVID   GPGRT_SYSHD_RVID
#define ES_SYSHD_HANDLE GPGRT_SYSHD_HANDLE
#endif

/* The object used with gpgrt_poll.  */
struct _gpgrt_poll_s
{
  gpgrt_stream_t stream;
  unsigned int want_read:1;
  unsigned int want_write:1;
  unsigned int want_oob:1;
  unsigned int want_rdhup:1;
  unsigned int _reserv1:4;
  unsigned int got_read:1;
  unsigned int got_write:1;
  unsigned int got_oob:1;
  unsigned int got_rdhup:1;
  unsigned int _reserv2:4;
  unsigned int got_err:1;
  unsigned int got_hup:1;
  unsigned int got_nval:1;
  unsigned int _reserv3:4;
  unsigned int ignore:1;
  unsigned int user:8;       /* For application use.  */
};
typedef struct _gpgrt_poll_s gpgrt_poll_t;
#ifdef GPGRT_ENABLE_ES_MACROS
typedef struct _gpgrt_poll_s es_poll_t;
#endif

/* The type of the string filter function as used by fprintf_sf et al.  */
typedef char *(*gpgrt_string_filter_t) (const char *s, int n, void *opaque);



gpgrt_stream_t gpgrt_fopen (const char *_GPGRT__RESTRICT path,
                            const char *_GPGRT__RESTRICT mode);
gpgrt_stream_t gpgrt_mopen (void *_GPGRT__RESTRICT data,
                            size_t data_n, size_t data_len,
                            unsigned int grow,
                            void *(*func_realloc) (void *mem, size_t size),
                            void (*func_free) (void *mem),
                            const char *_GPGRT__RESTRICT mode);
gpgrt_stream_t gpgrt_fopenmem (size_t memlimit,
                               const char *_GPGRT__RESTRICT mode);
gpgrt_stream_t gpgrt_fopenmem_init (size_t memlimit,
                                    const char *_GPGRT__RESTRICT mode,
                                    const void *data, size_t datalen);
gpgrt_stream_t gpgrt_fdopen    (int filedes, const char *mode);
gpgrt_stream_t gpgrt_fdopen_nc (int filedes, const char *mode);
gpgrt_stream_t gpgrt_sysopen    (gpgrt_syshd_t *syshd, const char *mode);
gpgrt_stream_t gpgrt_sysopen_nc (gpgrt_syshd_t *syshd, const char *mode);
gpgrt_stream_t gpgrt_fpopen    (FILE *fp, const char *mode);
gpgrt_stream_t gpgrt_fpopen_nc (FILE *fp, const char *mode);
gpgrt_stream_t gpgrt_freopen (const char *_GPGRT__RESTRICT path,
                              const char *_GPGRT__RESTRICT mode,
                              gpgrt_stream_t _GPGRT__RESTRICT stream);
gpgrt_stream_t gpgrt_fopencookie (void *_GPGRT__RESTRICT cookie,
                                  const char *_GPGRT__RESTRICT mode,
                                  gpgrt_cookie_io_functions_t functions);
int gpgrt_fclose (gpgrt_stream_t stream);
int gpgrt_fcancel (gpgrt_stream_t stream);
int gpgrt_fclose_snatch (gpgrt_stream_t stream,
                         void **r_buffer, size_t *r_buflen);
int gpgrt_onclose (gpgrt_stream_t stream, int mode,
                   void (*fnc) (gpgrt_stream_t, void*), void *fnc_value);
int gpgrt_fileno (gpgrt_stream_t stream);
int gpgrt_fileno_unlocked (gpgrt_stream_t stream);
int gpgrt_syshd (gpgrt_stream_t stream, gpgrt_syshd_t *syshd);
int gpgrt_syshd_unlocked (gpgrt_stream_t stream, gpgrt_syshd_t *syshd);

void _gpgrt_set_std_fd (int no, int fd);
gpgrt_stream_t _gpgrt_get_std_stream (int fd);

#define gpgrt_stdin  _gpgrt_get_std_stream (0)
#define gpgrt_stdout _gpgrt_get_std_stream (1)
#define gpgrt_stderr _gpgrt_get_std_stream (2)


void gpgrt_flockfile (gpgrt_stream_t stream);
int  gpgrt_ftrylockfile (gpgrt_stream_t stream);
void gpgrt_funlockfile (gpgrt_stream_t stream);

int gpgrt_feof (gpgrt_stream_t stream);
int gpgrt_feof_unlocked (gpgrt_stream_t stream);
int gpgrt_ferror (gpgrt_stream_t stream);
int gpgrt_ferror_unlocked (gpgrt_stream_t stream);
void gpgrt_clearerr (gpgrt_stream_t stream);
void gpgrt_clearerr_unlocked (gpgrt_stream_t stream);

int _gpgrt_pending (gpgrt_stream_t stream);          /* (private) */
int _gpgrt_pending_unlocked (gpgrt_stream_t stream); /* (private) */

#define gpgrt_pending(stream) _gpgrt_pending (stream)

#define gpgrt_pending_unlocked(stream)				\
  (((!(stream)->flags.writing)					\
    && (((stream)->data_offset < (stream)->data_len)		\
        || ((stream)->unread_data_len)))                        \
   ? 1 : _gpgrt_pending_unlocked ((stream)))

int gpgrt_fflush (gpgrt_stream_t stream);
int gpgrt_fseek (gpgrt_stream_t stream, long int offset, int whence);
int gpgrt_fseeko (gpgrt_stream_t stream, gpgrt_off_t offset, int whence);
int gpgrt_ftruncate (gpgrt_stream_t stream, gpgrt_off_t length);
long int gpgrt_ftell (gpgrt_stream_t stream);
gpgrt_off_t gpgrt_ftello (gpgrt_stream_t stream);
void gpgrt_rewind (gpgrt_stream_t stream);

int gpgrt_fgetc (gpgrt_stream_t stream);
int gpgrt_fputc (int c, gpgrt_stream_t stream);

int _gpgrt_getc_underflow (gpgrt_stream_t stream);       /* (private) */
int _gpgrt_putc_overflow (int c, gpgrt_stream_t stream); /* (private) */

#define gpgrt_getc_unlocked(stream)				\
  (((!(stream)->flags.writing)					\
    && ((stream)->data_offset < (stream)->data_len)		\
    && (! (stream)->unread_data_len))				\
  ? ((int) (stream)->buffer[((stream)->data_offset)++])		\
  : _gpgrt_getc_underflow ((stream)))

#define gpgrt_putc_unlocked(c, stream)				\
  (((stream)->flags.writing					\
    && ((stream)->data_offset < (stream)->buffer_size)		\
    && (c != '\n'))						\
  ? ((int) ((stream)->buffer[((stream)->data_offset)++] = (c)))	\
  : _gpgrt_putc_overflow ((c), (stream)))

#define gpgrt_getc(stream)    gpgrt_fgetc (stream)
#define gpgrt_putc(c, stream) gpgrt_fputc (c, stream)

int gpgrt_ungetc (int c, gpgrt_stream_t stream);

int gpgrt_read (gpgrt_stream_t _GPGRT__RESTRICT stream,
                void *_GPGRT__RESTRICT buffer, size_t bytes_to_read,
                size_t *_GPGRT__RESTRICT bytes_read);
int gpgrt_write (gpgrt_stream_t _GPGRT__RESTRICT stream,
                 const void *_GPGRT__RESTRICT buffer, size_t bytes_to_write,
                 size_t *_GPGRT__RESTRICT bytes_written);
int gpgrt_write_sanitized (gpgrt_stream_t _GPGRT__RESTRICT stream,
                           const void *_GPGRT__RESTRICT buffer, size_t length,
                           const char *delimiters,
                           size_t *_GPGRT__RESTRICT bytes_written);
int gpgrt_write_hexstring (gpgrt_stream_t _GPGRT__RESTRICT stream,
                           const void *_GPGRT__RESTRICT buffer, size_t length,
                           int reserved,
                           size_t *_GPGRT__RESTRICT bytes_written);

size_t gpgrt_fread (void *_GPGRT__RESTRICT ptr, size_t size, size_t nitems,
                    gpgrt_stream_t _GPGRT__RESTRICT stream);
size_t gpgrt_fwrite (const void *_GPGRT__RESTRICT ptr, size_t size,
                     size_t nitems, gpgrt_stream_t _GPGRT__RESTRICT stream);

char *gpgrt_fgets (char *_GPGRT__RESTRICT s, int n,
                   gpgrt_stream_t _GPGRT__RESTRICT stream);
int gpgrt_fputs (const char *_GPGRT__RESTRICT s,
                 gpgrt_stream_t _GPGRT__RESTRICT stream);
int gpgrt_fputs_unlocked (const char *_GPGRT__RESTRICT s,
                          gpgrt_stream_t _GPGRT__RESTRICT stream);

@api_ssize_t@ gpgrt_getline (char *_GPGRT__RESTRICT *_GPGRT__RESTRICT lineptr,
                       size_t *_GPGRT__RESTRICT n,
                       gpgrt_stream_t stream);
@api_ssize_t@ gpgrt_read_line (gpgrt_stream_t stream,
                         char **addr_of_buffer, size_t *length_of_buffer,
                         size_t *max_length);

int gpgrt_fprintf (gpgrt_stream_t _GPGRT__RESTRICT stream,
                   const char *_GPGRT__RESTRICT format, ...)
                   GPGRT_ATTR_PRINTF(2,3);
int gpgrt_fprintf_unlocked (gpgrt_stream_t _GPGRT__RESTRICT stream,
                            const char *_GPGRT__RESTRICT format, ...)
                            GPGRT_ATTR_PRINTF(2,3);

int gpgrt_fprintf_sf (gpgrt_stream_t _GPGRT__RESTRICT stream,
                      gpgrt_string_filter_t sf, void *sfvalue,
                      const char *_GPGRT__RESTRICT format,
                      ...) GPGRT_ATTR_PRINTF(4,5);
int gpgrt_fprintf_sf_unlocked (gpgrt_stream_t _GPGRT__RESTRICT stream,
                               gpgrt_string_filter_t sf, void *sfvalue,
                               const char *_GPGRT__RESTRICT format,
                               ...) GPGRT_ATTR_PRINTF(4,5);

int gpgrt_printf (const char *_GPGRT__RESTRICT format, ...)
                  GPGRT_ATTR_PRINTF(1,2);
int gpgrt_printf_unlocked (const char *_GPGRT__RESTRICT format, ...)
                           GPGRT_ATTR_PRINTF(1,2);

int gpgrt_vfprintf (gpgrt_stream_t _GPGRT__RESTRICT stream,
                    const char *_GPGRT__RESTRICT format, va_list ap)
                    GPGRT_ATTR_PRINTF(2,0);
int gpgrt_vfprintf_unlocked (gpgrt_stream_t _GPGRT__RESTRICT stream,
                             const char *_GPGRT__RESTRICT format, va_list ap)
                             GPGRT_ATTR_PRINTF(2,0);

int gpgrt_setvbuf (gpgrt_stream_t _GPGRT__RESTRICT stream,
                   char *_GPGRT__RESTRICT buf, int mode, size_t size);
void gpgrt_setbuf (gpgrt_stream_t _GPGRT__RESTRICT stream,
                   char *_GPGRT__RESTRICT buf);

void gpgrt_set_binary (gpgrt_stream_t stream);
int  gpgrt_set_nonblock (gpgrt_stream_t stream, int onoff);
int  gpgrt_get_nonblock (gpgrt_stream_t stream);

int gpgrt_poll (gpgrt_poll_t *fdlist, unsigned int nfds, int timeout);

gpgrt_stream_t gpgrt_tmpfile (void);

void gpgrt_opaque_set (gpgrt_stream_t _GPGRT__RESTRICT stream,
                       void *_GPGRT__RESTRICT opaque);
void *gpgrt_opaque_get (gpgrt_stream_t stream);

void gpgrt_fname_set (gpgrt_stream_t stream, const char *fname);
const char *gpgrt_fname_get (gpgrt_stream_t stream);

int gpgrt_asprintf (char **r_buf, const char * _GPGRT__RESTRICT format, ...)
                    GPGRT_ATTR_PRINTF(2,3);
int gpgrt_vasprintf (char **r_buf, const char * _GPGRT__RESTRICT format,
                     va_list ap)
                     GPGRT_ATTR_PRINTF(2,0);
char *gpgrt_bsprintf (const char * _GPGRT__RESTRICT format, ...)
                      GPGRT_ATTR_PRINTF(1,2);
char *gpgrt_vbsprintf (const char * _GPGRT__RESTRICT format, va_list ap)
                       GPGRT_ATTR_PRINTF(1,0);
int gpgrt_snprintf (char *buf, size_t bufsize,
                    const char * _GPGRT__RESTRICT format, ...)
                    GPGRT_ATTR_PRINTF(3,4);
int gpgrt_vsnprintf (char *buf,size_t bufsize,
                     const char * _GPGRT__RESTRICT format, va_list arg_ptr)
                     GPGRT_ATTR_PRINTF(3,0);


#ifdef GPGRT_ENABLE_ES_MACROS
# define es_fopen             gpgrt_fopen
# define es_mopen             gpgrt_mopen
# define es_fopenmem          gpgrt_fopenmem
# define es_fopenmem_init     gpgrt_fopenmem_init
# define es_fdopen            gpgrt_fdopen
# define es_fdopen_nc         gpgrt_fdopen_nc
# define es_sysopen           gpgrt_sysopen
# define es_sysopen_nc        gpgrt_sysopen_nc
# define es_fpopen            gpgrt_fpopen
# define es_fpopen_nc         gpgrt_fpopen_nc
# define es_freopen           gpgrt_freopen
# define es_fopencookie       gpgrt_fopencookie
# define es_fclose            gpgrt_fclose
# define es_fclose_snatch     gpgrt_fclose_snatch
# define es_onclose           gpgrt_onclose
# define es_fileno            gpgrt_fileno
# define es_fileno_unlocked   gpgrt_fileno_unlocked
# define es_syshd             gpgrt_syshd
# define es_syshd_unlocked    gpgrt_syshd_unlocked
# define es_stdin             _gpgrt_get_std_stream (0)
# define es_stdout            _gpgrt_get_std_stream (1)
# define es_stderr            _gpgrt_get_std_stream (2)
# define es_flockfile         gpgrt_flockfile
# define es_ftrylockfile      gpgrt_ftrylockfile
# define es_funlockfile       gpgrt_funlockfile
# define es_feof              gpgrt_feof
# define es_feof_unlocked     gpgrt_feof_unlocked
# define es_ferror            gpgrt_ferror
# define es_ferror_unlocked   gpgrt_ferror_unlocked
# define es_clearerr          gpgrt_clearerr
# define es_clearerr_unlocked gpgrt_clearerr_unlocked
# define es_pending           gpgrt_pending
# define es_pending_unlocked  gpgrt_pending_unlocked
# define es_fflush            gpgrt_fflush
# define es_fseek             gpgrt_fseek
# define es_fseeko            gpgrt_fseeko
# define es_ftruncate         gpgrt_ftruncate
# define es_ftell             gpgrt_ftell
# define es_ftello            gpgrt_ftello
# define es_rewind            gpgrt_rewind
# define es_fgetc             gpgrt_fgetc
# define es_fputc             gpgrt_fputc
# define es_getc_unlocked     gpgrt_getc_unlocked
# define es_putc_unlocked     gpgrt_putc_unlocked
# define es_getc              gpgrt_getc
# define es_putc              gpgrt_putc
# define es_ungetc            gpgrt_ungetc
# define es_read              gpgrt_read
# define es_write             gpgrt_write
# define es_write_sanitized   gpgrt_write_sanitized
# define es_write_hexstring   gpgrt_write_hexstring
# define es_fread             gpgrt_fread
# define es_fwrite            gpgrt_fwrite
# define es_fgets             gpgrt_fgets
# define es_fputs             gpgrt_fputs
# define es_fputs_unlocked    gpgrt_fputs_unlocked
# define es_getline           gpgrt_getline
# define es_read_line         gpgrt_read_line
# define es_free              gpgrt_free
# define es_fprintf           gpgrt_fprintf
# define es_fprintf_unlocked  gpgrt_fprintf_unlocked
# define es_printf            gpgrt_printf
# define es_printf_unlocked   gpgrt_printf_unlocked
# define es_vfprintf          gpgrt_vfprintf
# define es_vfprintf_unlocked gpgrt_vfprintf_unlocked
# define es_setvbuf           gpgrt_setvbuf
# define es_setbuf            gpgrt_setbuf
# define es_set_binary        gpgrt_set_binary
# define es_set_nonblock      gpgrt_set_nonblock
# define es_get_nonblock      gpgrt_get_nonblock
# define es_poll              gpgrt_poll
# define es_tmpfile           gpgrt_tmpfile
# define es_opaque_set        gpgrt_opaque_set
# define es_opaque_get        gpgrt_opaque_get
# define es_fname_set         gpgrt_fname_set
# define es_fname_get         gpgrt_fname_get
# define es_asprintf          gpgrt_asprintf
# define es_vasprintf         gpgrt_vasprintf
# define es_bsprintf          gpgrt_bsprintf
# define es_vbsprintf         gpgrt_vbsprintf
#endif /*GPGRT_ENABLE_ES_MACROS*/



/*
 * Base64 encode and decode functions.
 */

struct _gpgrt_b64state;
typedef struct _gpgrt_b64state *gpgrt_b64state_t;

gpgrt_b64state_t gpgrt_b64enc_start (gpgrt_stream_t stream, const char *title);
gpg_err_code_t   gpgrt_b64enc_write (gpgrt_b64state_t state,
                                     const void *buffer, size_t nbytes);
gpg_err_code_t   gpgrt_b64enc_finish (gpgrt_b64state_t state);

gpgrt_b64state_t gpgrt_b64dec_start (const char *title);
gpg_error_t      gpgrt_b64dec_proc (gpgrt_b64state_t state,
                                    void *buffer, size_t length,
                                    size_t *r_nbytes);
gpg_error_t      gpgrt_b64dec_finish (gpgrt_b64state_t state);



/*
 * Logging functions
 */

/* Flag values for gpgrt_log_set_prefix. */
#define GPGRT_LOG_WITH_PREFIX  1
#define GPGRT_LOG_WITH_TIME    2
#define GPGRT_LOG_WITH_PID     4
#define GPGRT_LOG_RUN_DETACHED 256
#define GPGRT_LOG_NO_REGISTRY  512

/* Log levels as used by gpgrt_log.  */
enum gpgrt_log_levels
  {
    GPGRT_LOGLVL_BEGIN,
    GPGRT_LOGLVL_CONT,
    GPGRT_LOGLVL_INFO,
    GPGRT_LOGLVL_WARN,
    GPGRT_LOGLVL_ERROR,
    GPGRT_LOGLVL_FATAL,
    GPGRT_LOGLVL_BUG,
    GPGRT_LOGLVL_DEBUG
  };


/* The next 4 functions are not thread-safe - call them early.  */
void gpgrt_log_set_sink (const char *name, gpgrt_stream_t stream, int fd);
void gpgrt_log_set_socket_dir_cb (const char *(*fnc)(void));
void gpgrt_log_set_pid_suffix_cb (int (*cb)(unsigned long *r_value));
void gpgrt_log_set_prefix (const char *text, unsigned int flags);

int  gpgrt_get_errorcount (int clear);
void gpgrt_inc_errorcount (void);
const char *gpgrt_log_get_prefix (unsigned int *flags);
int  gpgrt_log_test_fd (int fd);
int  gpgrt_log_get_fd (void);
gpgrt_stream_t gpgrt_log_get_stream (void);

void gpgrt_log (int level, const char *fmt, ...) GPGRT_ATTR_PRINTF(2,3);
void gpgrt_logv (int level, const char *fmt, va_list arg_ptr);
void gpgrt_logv_prefix (int level, const char *prefix,
                              const char *fmt, va_list arg_ptr);
void gpgrt_log_string (int level, const char *string);
void gpgrt_log_bug (const char *fmt, ...)    GPGRT_ATTR_NR_PRINTF(1,2);
void gpgrt_log_fatal (const char *fmt, ...)  GPGRT_ATTR_NR_PRINTF(1,2);
void gpgrt_log_error (const char *fmt, ...)  GPGRT_ATTR_PRINTF(1,2);
void gpgrt_log_info (const char *fmt, ...)   GPGRT_ATTR_PRINTF(1,2);
void gpgrt_log_debug (const char *fmt, ...)  GPGRT_ATTR_PRINTF(1,2);
void gpgrt_log_debug_string (const char *string,
                             const char *fmt, ...) GPGRT_ATTR_PRINTF(2,3);
void gpgrt_log_printf (const char *fmt, ...) GPGRT_ATTR_PRINTF(1,2);
void gpgrt_log_printhex (const void *buffer, size_t length,
                         const char *fmt, ...) GPGRT_ATTR_PRINTF(3,4);
void gpgrt_log_clock (const char *fmt, ...) GPGRT_ATTR_PRINTF(1,2);
void gpgrt_log_flush (void);
void _gpgrt_log_assert (const char *expr, const char *file, int line,
                        const char *func) GPGRT_ATTR_NORETURN;

#ifdef GPGRT_HAVE_MACRO_FUNCTION
# define gpgrt_assert(expr)                                     \
  ((expr)                                                       \
   ? (void) 0                                                   \
   : _gpgrt_log_assert (#expr, __FILE__, __LINE__, __FUNCTION__))
#else /*!GPGRT_HAVE_MACRO_FUNCTION*/
# define gpgrt_assert(expr)                                     \
  ((expr)                                                       \
   ? (void) 0                                                   \
   : _gpgrt_log_assert (#expr, __FILE__, __LINE__, NULL))
#endif /*!GPGRT_HAVE_MACRO_FUNCTION*/

#ifdef GPGRT_ENABLE_LOG_MACROS
# define log_get_errorcount      gpgrt_get_errorcount
# define log_inc_errorcount      gpgrt_inc_errorcount
# define log_set_file(a)         gpgrt_log_set_sink ((a), NULL, -1)
# define log_set_fd(a)           gpgrt_log_set_sink (NULL, NULL, (a))
# define log_set_stream(a)       gpgrt_log_set_sink (NULL, (a), -1)
# define log_set_socket_dir_cb   gpgrt_log_set_socket_dir_cb
# define log_set_pid_suffix_cb   gpgrt_log_set_pid_suffix_cb
# define log_set_prefix          gpgrt_log_set_prefix
# define log_get_prefix          gpgrt_log_get_prefix
# define log_test_fd             gpgrt_log_test_fd
# define log_get_fd              gpgrt_log_get_fd
# define log_get_stream          gpgrt_log_get_stream
# define log_log                 gpgrt_log
# define log_logv                gpgrt_logv
# define log_logv_prefix         gpgrt_logv_prefix
# define log_string              gpgrt_log_string
# define log_bug                 gpgrt_log_bug
# define log_fatal               gpgrt_log_fatal
# define log_error               gpgrt_log_error
# define log_info                gpgrt_log_info
# define log_debug               gpgrt_log_debug
# define log_debug_string        gpgrt_log_debug_string
# define log_printf              gpgrt_log_printf
# define log_printhex            gpgrt_log_printhex
# define log_clock               gpgrt_log_clock
# define log_flush               gpgrt_log_flush
# ifdef GPGRT_HAVE_MACRO_FUNCTION
#  define log_assert(expr)                                      \
  ((expr)                                                       \
   ? (void) 0                                                   \
   : _gpgrt_log_assert (#expr, __FILE__, __LINE__, __FUNCTION__))
# else /*!GPGRT_HAVE_MACRO_FUNCTION*/
#  define log_assert(expr)                                      \
  ((expr)                                                       \
   ? (void) 0                                                   \
   : _gpgrt_log_assert (#expr, __FILE__, __LINE__, NULL))
# endif /*!GPGRT_HAVE_MACRO_FUNCTION*/

#endif /*GPGRT_ENABLE_LOG_MACROS*/


/*
 * Spawn functions  (Not yet available)
 */
#define GPGRT_SPAWN_NONBLOCK   16 /* Set the streams to non-blocking.      */
#define GPGRT_SPAWN_RUN_ASFW   64 /* Use AllowSetForegroundWindow on W32.  */
#define GPGRT_SPAWN_DETACHED  128 /* Start the process in the background.  */

#if 0

/* Function and convenience macros to create pipes.  */
gpg_err_code_t gpgrt_make_pipe (int filedes[2], gpgrt_stream_t *r_fp,
                                int direction, int nonblock);
#define gpgrt_create_pipe(a)              gpgrt_make_pipe ((a),NULL,  0,  0);
#define gpgrt_create_inbound_pipe(a,b,c)  gpgrt_make_pipe ((a), (b), -1,(c));
#define gpgrt_create_outbound_pipe(a,b,c) gpgrt_make_pipe ((a), (b),  1,(c));


/* Fork and exec PGMNAME.  */
gpg_err_code_t gpgrt_spawn_process (const char *pgmname, const char *argv[],
                                    int *execpt, void (*preexec)(void),
                                    unsigned int flags,
                                    gpgrt_stream_t *r_infp,
                                    gpgrt_stream_t *r_outfp,
                                    gpgrt_stream_t *r_errfp,
                                    pid_t *pid);

/* Fork and exec PGNNAME and connect the process to the given FDs.  */
gpg_err_code_t gpgrt_spawn_process_fd (const char *pgmname, const char *argv[],
                                       int infd, int outfd, int errfd,
                                       pid_t *pid);

/* Fork and exec PGMNAME as a detached process.  */
gpg_err_code_t gpgrt_spawn_process_detached (const char *pgmname,
                                             const char *argv[],
                                             const char *envp[] );

/* Wait for a single process.  */
gpg_err_code_t gpgrt_wait_process (const char *pgmname, pid_t pid, int hang,
                                int *r_exitcode);

/* Wait for a multiple processes.  */
gpg_err_code_t gpgrt_wait_processes (const char **pgmnames, pid_t *pids,
                                     size_t count, int hang, int *r_exitcodes);

/* Kill the process identified by PID.  */
void gpgrt_kill_process (pid_t pid);

/* Release process resources identified by PID.  */
void gpgrt_release_process (pid_t pid);

#endif /*0*/



/*
 * Option parsing.
 */

struct _gpgrt_argparse_internal_s;
typedef struct
{
  int  *argc;	      /* Pointer to ARGC (value subject to change). */
  char ***argv;	      /* Pointer to ARGV (value subject to change). */
  unsigned int flags; /* Global flags.  May be set prior to calling the
                         parser.  The parser may change the value.  */
  int err;            /* Print error description for last option.
                         Either 0,  ARGPARSE_PRINT_WARNING or
                         ARGPARSE_PRINT_ERROR.  */
  unsigned int lineno;/* The current line number.  */
  int r_opt; 	      /* Returns option code. */
  int r_type;	      /* Returns type of option value.  */
  union {
    int   ret_int;
    long  ret_long;
    unsigned long ret_ulong;
    char *ret_str;
  } r;		      /* Return values */

  struct _gpgrt_argparse_internal_s *internal;
} gpgrt_argparse_t;


typedef struct
{
  int          short_opt;
  const char  *long_opt;
  unsigned int flags;
  const char  *description; /* Optional description. */
} gpgrt_opt_t;


#ifdef GPGRT_ENABLE_ARGPARSE_MACROS

/* Global flags for (gpgrt_argparse_t).flags.  */
#define ARGPARSE_FLAG_KEEP        1  /* Do not remove options form argv.     */
#define ARGPARSE_FLAG_ALL         2  /* Do not stop at last option but return
                                        remaining args with R_OPT set to -1. */
#define ARGPARSE_FLAG_MIXED       4  /* Assume options and args are mixed.   */
#define ARGPARSE_FLAG_NOSTOP      8  /* Do not stop processing at "--".      */
#define ARGPARSE_FLAG_ARG0       16  /* Do not skip the first arg.           */
#define ARGPARSE_FLAG_ONEDASH    32  /* Allow long options with one dash.    */
#define ARGPARSE_FLAG_NOVERSION  64  /* No output for "--version".           */
#define ARGPARSE_FLAG_RESET     128  /* Request to reset the internal state. */
#define ARGPARSE_FLAG_STOP_SEEN 256  /* Set to true if a "--" has been seen. */
#define ARGPARSE_FLAG_NOLINENO  512  /* Do not zero the lineno field.        */
#define ARGPARSE_FLAG_SYS      1024  /* Use system config file.              */
#define ARGPARSE_FLAG_USER     2048  /* Use user config file.                */
#define ARGPARSE_FLAG_VERBOSE  4096  /* Print additional argparser info.     */
#define ARGPARSE_FLAG_USERVERS 8192  /* Try version-ed user config files.    */
#define ARGPARSE_FLAG_WITHATTR 16384 /* Return attribute bits.               */

/* Constants for (gpgrt_argparse_t).err.  */
#define ARGPARSE_PRINT_WARNING  1    /* Print a diagnostic.                  */
#define ARGPARSE_PRINT_ERROR    2    /* Print a diagnostic and call exit.    */

/* Special return values of gpgrt_argparse.  */
#define ARGPARSE_IS_ARG            (-1)
#define ARGPARSE_INVALID_OPTION    (-2)
#define ARGPARSE_MISSING_ARG       (-3)
#define ARGPARSE_KEYWORD_TOO_LONG  (-4)
#define ARGPARSE_READ_ERROR        (-5)
#define ARGPARSE_UNEXPECTED_ARG    (-6)
#define ARGPARSE_INVALID_COMMAND   (-7)
#define ARGPARSE_AMBIGUOUS_OPTION  (-8)
#define ARGPARSE_AMBIGUOUS_COMMAND (-9)
#define ARGPARSE_INVALID_ALIAS     (-10)
#define ARGPARSE_OUT_OF_CORE       (-11)
#define ARGPARSE_INVALID_ARG       (-12)
#define ARGPARSE_PERMISSION_ERROR  (-13)
#define ARGPARSE_NO_CONFFILE       (-14)
#define ARGPARSE_CONFFILE          (-15)
#define ARGPARSE_INVALID_META      (-16)
#define ARGPARSE_UNKNOWN_META      (-17)
#define ARGPARSE_UNEXPECTED_META   (-18)

/* Flags for the option descriptor (gpgrt_opt_t)->flags.  Note that a
 * TYPE constant may be or-ed with the OPT constants but when used as
 * return value in r_type these OPT constants are normally not
 * included.  However with ARGPARSE_FLAG_WITHATTR used and an option
 * would normally not be returned, it is returned but
 * ARGPARSE_OPT_IGNORE is then set; further ARPARSE_ATTR_* are set.
 */
#define ARGPARSE_TYPE_MASK   0x0007  /* Mask for the type bits.           */
#define ARGPARSE_TYPE_NONE        0  /* Does not take an argument.        */
#define ARGPARSE_TYPE_INT         1  /* Takes an int argument.            */
#define ARGPARSE_TYPE_STRING      2  /* Takes a string argument.          */
#define ARGPARSE_TYPE_LONG        3  /* Takes a long argument.            */
#define ARGPARSE_TYPE_ULONG       4  /* Takes an unsigned long argument.  */
#define ARGPARSE_OPT_OPTIONAL (1<<3) /* Argument is optional.             */
#define ARGPARSE_OPT_PREFIX   (1<<4) /* Allow 0x etc. prefixed values.    */
#define ARGPARSE_OPT_IGNORE   (1<<6) /* Ignore command or option.         */
#define ARGPARSE_OPT_COMMAND  (1<<7) /* The argument is a command.        */
#define ARGPARSE_OPT_CONFFILE (1<<8) /* The value is a conffile.          */
#define ARGPARSE_OPT_HEADER   (1<<9) /* The value is printed as a header. */
#define ARGPARSE_OPT_VERBATIM (1<<10)/* The value is printed verbatim.    */
#define ARGPARSE_ATTR_FORCE   (1<<14)/* Attribute force is set.           */
#define ARGPARSE_ATTR_IGNORE  (1<<15)/* Attribute ignore is set.          */

/* A set of macros to make option definitions easier to read.  */
#define ARGPARSE_x(s,l,t,f,d) \
     { (s), (l), ARGPARSE_TYPE_ ## t | (f), (d) }

#define ARGPARSE_s(s,l,t,d) \
     { (s), (l), ARGPARSE_TYPE_ ## t, (d) }
#define ARGPARSE_s_n(s,l,d) \
     { (s), (l), ARGPARSE_TYPE_NONE, (d) }
#define ARGPARSE_s_i(s,l,d) \
     { (s), (l), ARGPARSE_TYPE_INT, (d) }
#define ARGPARSE_s_s(s,l,d) \
     { (s), (l), ARGPARSE_TYPE_STRING, (d) }
#define ARGPARSE_s_l(s,l,d) \
     { (s), (l), ARGPARSE_TYPE_LONG, (d) }
#define ARGPARSE_s_u(s,l,d) \
     { (s), (l), ARGPARSE_TYPE_ULONG, (d) }

#define ARGPARSE_o(s,l,t,d) \
     { (s), (l), (ARGPARSE_TYPE_ ## t  | ARGPARSE_OPT_OPTIONAL), (d) }
#define ARGPARSE_o_n(s,l,d) \
     { (s), (l), (ARGPARSE_TYPE_NONE   | ARGPARSE_OPT_OPTIONAL), (d) }
#define ARGPARSE_o_i(s,l,d) \
     { (s), (l), (ARGPARSE_TYPE_INT    | ARGPARSE_OPT_OPTIONAL), (d) }
#define ARGPARSE_o_s(s,l,d) \
     { (s), (l), (ARGPARSE_TYPE_STRING | ARGPARSE_OPT_OPTIONAL), (d) }
#define ARGPARSE_o_l(s,l,d) \
     { (s), (l), (ARGPARSE_TYPE_LONG   | ARGPARSE_OPT_OPTIONAL), (d) }
#define ARGPARSE_o_u(s,l,d) \
     { (s), (l), (ARGPARSE_TYPE_ULONG  | ARGPARSE_OPT_OPTIONAL), (d) }

#define ARGPARSE_p(s,l,t,d) \
     { (s), (l), (ARGPARSE_TYPE_ ## t  | ARGPARSE_OPT_PREFIX), (d) }
#define ARGPARSE_p_n(s,l,d) \
     { (s), (l), (ARGPARSE_TYPE_NONE   | ARGPARSE_OPT_PREFIX), (d) }
#define ARGPARSE_p_i(s,l,d) \
     { (s), (l), (ARGPARSE_TYPE_INT    | ARGPARSE_OPT_PREFIX), (d) }
#define ARGPARSE_p_s(s,l,d) \
     { (s), (l), (ARGPARSE_TYPE_STRING | ARGPARSE_OPT_PREFIX), (d) }
#define ARGPARSE_p_l(s,l,d) \
     { (s), (l), (ARGPARSE_TYPE_LONG   | ARGPARSE_OPT_PREFIX), (d) }
#define ARGPARSE_p_u(s,l,d) \
     { (s), (l), (ARGPARSE_TYPE_ULONG  | ARGPARSE_OPT_PREFIX), (d) }

#define ARGPARSE_op(s,l,t,d) \
     { (s), (l), (ARGPARSE_TYPE_ ## t \
                  | ARGPARSE_OPT_OPTIONAL | ARGPARSE_OPT_PREFIX), (d) }
#define ARGPARSE_op_n(s,l,d) \
     { (s), (l), (ARGPARSE_TYPE_NONE \
                  | ARGPARSE_OPT_OPTIONAL | ARGPARSE_OPT_PREFIX), (d) }
#define ARGPARSE_op_i(s,l,d) \
     { (s), (l), (ARGPARSE_TYPE_INT \
                  | ARGPARSE_OPT_OPTIONAL | ARGPARSE_OPT_PREFIX), (d) }
#define ARGPARSE_op_s(s,l,d) \
     { (s), (l), (ARGPARSE_TYPE_STRING \
                  | ARGPARSE_OPT_OPTIONAL | ARGPARSE_OPT_PREFIX), (d) }
#define ARGPARSE_op_l(s,l,d) \
     { (s), (l), (ARGPARSE_TYPE_LONG \
                  | ARGPARSE_OPT_OPTIONAL | ARGPARSE_OPT_PREFIX), (d) }
#define ARGPARSE_op_u(s,l,d) \
     { (s), (l), (ARGPARSE_TYPE_ULONG \
                  | ARGPARSE_OPT_OPTIONAL | ARGPARSE_OPT_PREFIX), (d) }

#define ARGPARSE_c(s,l,d) \
     { (s), (l), (ARGPARSE_TYPE_NONE | ARGPARSE_OPT_COMMAND), (d) }

#define ARGPARSE_conffile(s,l,d) \
  { (s), (l), (ARGPARSE_TYPE_STRING|ARGPARSE_OPT_CONFFILE), (d) }

#define ARGPARSE_noconffile(s,l,d) \
  { (s), (l), (ARGPARSE_TYPE_NONE|ARGPARSE_OPT_CONFFILE), (d) }

/* This macro is for stub or obsolete options.  */
#define ARGPARSE_ignore(s,l)                    \
  { (s), (l), (ARGPARSE_OPT_IGNORE), "@" }

/* This is a legacy version of ARGPARSE_verbatim which really does
 * verbatim printing.  */
#define ARGPARSE_group(s,d) \
  { (s), NULL, 0, (d) }

/* Verbatim print the string D in the help output.  It does not make
 * use of the "@" hack as ARGPARSE_group does.  */
#define ARGPARSE_verbatim(d) \
  { 1, NULL, (ARGPARSE_OPT_VERBATIM), (d) }

/* Same as ARGPARSE_verbatim but also print a colon and a LF.  N can
 * be used give a symbolic name to the header.  Nothing is printed if
 * D is the empty string.  */
#define ARGPARSE_header(n,d) \
  { 1, (n), (ARGPARSE_OPT_HEADER), (d) }

/* Mark the end of the list (mandatory).  */
#define ARGPARSE_end() \
  { 0, NULL, 0, NULL }

#endif /* GPGRT_ENABLE_ARGPARSE_MACROS */

/* Values used for gpgrt_set_confdir.  */
#define GPGRT_CONFDIR_USER 1   /* The user's configuration dir.    */
#define GPGRT_CONFDIR_SYS  2   /* The systems's configuration dir. */

/* Take care: gpgrt_argparse keeps state in ARG and requires that
 * either ARGPARSE_FLAG_RESET is used after OPTS has been changed or
 * gpgrt_argparse (NULL, ARG, NULL) is called first.  */
int gpgrt_argparse (gpgrt_stream_t fp,
                    gpgrt_argparse_t *arg, gpgrt_opt_t *opts);
int gpgrt_argparser (gpgrt_argparse_t *arg, gpgrt_opt_t *opts,
                     const char *confname);
void gpgrt_usage (int level);
const char *gpgrt_strusage (int level);
void gpgrt_set_strusage (const char *(*f)(int));
void gpgrt_set_usage_outfnc (int (*f)(int, const char *));
void gpgrt_set_fixed_string_mapper (const char *(*f)(const char*));
void gpgrt_set_confdir (int what, const char *name);


/*
 * Various helper functions
 */

/* Compare arbitrary version strings.  For the standard m.n.o version
 * numbering scheme a LEVEL of 3 is suitable; see the manual.  */
int gpgrt_cmp_version (const char *a, const char *b, int level);

/* Construct a filename from the NULL terminated list of parts.  Tilde
 * expansion is done for the first argument.  The caller must release
 * the result using gpgrt_free; on error ERRNO is set and NULL
 * returned.  The second function returns an absolute filename.  */
char *gpgrt_fnameconcat (const char *first, ...) GPGRT_ATTR_SENTINEL(0);
char *gpgrt_absfnameconcat (const char *first, ...) GPGRT_ATTR_SENTINEL(0);


#ifdef __cplusplus
}
#endif
#endif	/* GPGRT_H */
#endif	/* GPG_ERROR_H */