/
perl.h
9403 lines (8255 loc) · 330 KB
/
perl.h
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
/* perl.h
*
* Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001
* 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 by Larry Wall and others
*
* You may distribute under the terms of either the GNU General Public
* License or the Artistic License, as specified in the README file.
*
*/
#ifndef H_PERL
#define H_PERL 1
#ifdef PERL_FOR_X2P
/*
* This file is being used for x2p stuff.
* Above symbol is defined via -D in 'x2p/Makefile.SH'
* Decouple x2p stuff from some of perls more extreme eccentricities.
*/
#undef MULTIPLICITY
#undef USE_STDIO
#define USE_STDIO
#endif /* PERL_FOR_X2P */
#ifdef PERL_MICRO
# include "uconfig.h"
#else
# include "config.h"
#endif
#ifndef WIN32 /* XXX temp */
# define _configthreadlocale(x) (! cBOOL(x))
# define _DISABLE_PER_THREAD_LOCALE 0
# define _ENABLE_PER_THREAD_LOCALE 1
#endif
/*
=for apidoc_section $debugging
=for apidoc CmnW ||_aDEPTH
Some functions when compiled under DEBUGGING take an extra final argument named
C<depth>, indicating the C stack depth. This argument is omitted otherwise.
This macro expands to either S<C<, depth>> under DEBUGGING, or to nothing at
all when not under DEBUGGING, reducing the number of C<#ifdef>'s in the code.
The program is responsible for maintaining the correct value for C<depth>.
=for apidoc CyW ||_pDEPTH
This is used in the prototype declarations for functions that take a L</C<_aDEPTH>>
final parameter, much like L<C<pTHX_>|perlguts/Background and MULTIPLICITY>
is used in functions that take a thread context initial parameter.
=cut
*/
#ifdef DEBUGGING
# define _pDEPTH ,U32 depth
# define _aDEPTH ,depth
#else
# define _pDEPTH
# define _aDEPTH
#endif
/* NOTE 1: that with gcc -std=c89 the __STDC_VERSION__ is *not* defined
* because the __STDC_VERSION__ became a thing only with C90. Therefore,
* with gcc, HAS_C99 will never become true as long as we use -std=c89.
* NOTE 2: headers lie. Do not expect that if HAS_C99 gets to be true,
* all the C99 features are there and are correct. */
#if (defined(__STDC_VERSION__) && __STDC_VERSION__ >= 199901L) || \
defined(_STDC_C99) || defined(__c99)
# define HAS_C99 1
#endif
/* =========================================================================
* The defines from here to the following ===== line are unfortunately
* duplicated in makedef.pl, and changes here MUST also be made there */
/* See L<perlguts/"The Perl API"> for detailed notes on
* MULTIPLICITY and PERL_IMPLICIT_SYS */
#ifdef USE_ITHREADS
# if !defined(MULTIPLICITY)
# define MULTIPLICITY
# endif
#endif
/* PERL_IMPLICIT_CONTEXT is a legacy synonym for MULTIPLICITY */
#if defined(MULTIPLICITY) \
&& ! defined(PERL_CORE) \
&& ! defined(PERL_IMPLICIT_CONTEXT)
# define PERL_IMPLICIT_CONTEXT
#endif
#if defined(PERL_IMPLICIT_CONTEXT) && !defined(MULTIPLICITY)
# define MULTIPLICITY
#endif
#ifdef PERL_CORE /* Make sure doesn't creep back in to core code */
# undef PERL_IMPLICIT_CONTEXT
#endif
/* undef WIN32 when building on Cygwin (for libwin32) - gph */
#ifdef __CYGWIN__
# undef WIN32
# undef _WIN32
#endif
/* Use the reentrant APIs like localtime_r and getpwent_r */
/* Win32 has naturally threadsafe libraries, no need to use any _r variants.
* XXX KEEP makedef.pl copy of this code in sync */
#if defined(USE_ITHREADS) && !defined(USE_REENTRANT_API) && !defined(WIN32)
# define USE_REENTRANT_API
#endif
/* end of makedef.pl logic duplication. But there are other groups below.
* ========================================================================= */
/*
=for apidoc_section $directives
=for apidoc AmnUu|void|EXTERN_C
When not compiling using C++, expands to nothing.
Otherwise is used in a declaration of a function to indicate the function
should have external C linkage. This is required for things to work for just
about all functions with external linkage compiled into perl.
Often, you can use C<L</START_EXTERN_C>> ... C<L</END_EXTERN_C>> blocks
surrounding all your code that you need to have this linkage.
Example usage:
EXTERN_C int flock(int fd, int op);
=for apidoc Amnu||START_EXTERN_C
When not compiling using C++, expands to nothing.
Otherwise begins a section of code in which every function will effectively
have C<L</EXTERN_C>> applied to it, that is to have external C linkage. The
section is ended by a C<L</END_EXTERN_C>>.
=for apidoc Amnu||END_EXTERN_C
When not compiling using C++, expands to nothing.
Otherwise ends a section of code already begun by a C<L</START_EXTERN_C>>.
=cut
*/
#undef START_EXTERN_C
#undef END_EXTERN_C
#undef EXTERN_C
#ifdef __cplusplus
# define EXTERN_C extern "C"
# define START_EXTERN_C EXTERN_C {
# define END_EXTERN_C }
#else
# define START_EXTERN_C
# define END_EXTERN_C
# define EXTERN_C extern
#endif
/* Fallback definitions in case we don't have definitions from config.h.
This should only matter for systems that don't use Configure and
haven't been modified to define PERL_STATIC_INLINE yet.
*/
#if !defined(PERL_STATIC_INLINE)
# ifdef HAS_STATIC_INLINE
# define PERL_STATIC_INLINE static inline
# else
# define PERL_STATIC_INLINE static
# endif
#endif
/*
=for apidoc_section $concurrency
=for apidoc AmU|void|dTHXa|PerlInterpreter * a
On threaded perls, set C<pTHX> to C<a>; on unthreaded perls, do nothing
=for apidoc AmU|void|dTHXoa|PerlInterpreter * a
Now a synonym for C<L</dTHXa>>.
=cut
*/
#ifdef MULTIPLICITY
# define tTHX PerlInterpreter*
# define pTHX tTHX my_perl PERL_UNUSED_DECL
# define aTHX my_perl
# define aTHXa(a) aTHX = (tTHX)a
# define dTHXa(a) pTHX = (tTHX)a
# define dTHX pTHX = PERL_GET_THX
# define pTHX_ pTHX,
# define aTHX_ aTHX,
# define pTHX_1 2
# define pTHX_2 3
# define pTHX_3 4
# define pTHX_4 5
# define pTHX_5 6
# define pTHX_6 7
# define pTHX_7 8
# define pTHX_8 9
# define pTHX_9 10
# define pTHX_12 13
# if defined(DEBUGGING) && !defined(PERL_TRACK_MEMPOOL)
# define PERL_TRACK_MEMPOOL
# endif
#else
# undef PERL_TRACK_MEMPOOL
#endif
#ifdef DEBUGGING
# define dTHX_DEBUGGING dTHX
#else
# define dTHX_DEBUGGING dNOOP
#endif
#define STATIC static
#ifndef PERL_CORE
/* Do not use these macros. They were part of PERL_OBJECT, which was an
* implementation of multiplicity using C++ objects. They have been left
* here solely for the sake of XS code which has incorrectly
* cargo-culted them.
*
* The only one Devel::PPPort handles is this; list it as deprecated
=for apidoc_section $concurrency
=for apidoc AmD|void|CPERLscope|void x
Now a no-op.
=cut
*/
# define CPERLscope(x) x
# define CPERLarg void
# define CPERLarg_
# define _CPERLarg
# define PERL_OBJECT_THIS
# define _PERL_OBJECT_THIS
# define PERL_OBJECT_THIS_
# define CALL_FPTR(fptr) (*fptr)
# define MEMBER_TO_FPTR(name) name
#endif /* !PERL_CORE */
#define CALLRUNOPS PL_runops
#define CALLREGCOMP(sv, flags) Perl_pregcomp(aTHX_ (sv),(flags))
#define CALLREGCOMP_ENG(prog, sv, flags) (prog)->comp(aTHX_ sv, flags)
#define CALLREGEXEC(prog,stringarg,strend,strbeg,minend,sv,data,flags) \
RX_ENGINE(prog)->exec(aTHX_ (prog),(stringarg),(strend), \
(strbeg),(minend),(sv),(data),(flags))
#define CALLREG_INTUIT_START(prog,sv,strbeg,strpos,strend,flags,data) \
RX_ENGINE(prog)->intuit(aTHX_ (prog), (sv), (strbeg), (strpos), \
(strend),(flags),(data))
#define CALLREG_INTUIT_STRING(prog) \
RX_ENGINE(prog)->checkstr(aTHX_ (prog))
#define CALLREGFREE(prog) \
Perl_pregfree(aTHX_ (prog))
#define CALLREGFREE_PVT(prog) \
if(prog && RX_ENGINE(prog)) RX_ENGINE(prog)->rxfree(aTHX_ (prog))
#define CALLREG_NUMBUF_FETCH(rx,paren,usesv) \
RX_ENGINE(rx)->numbered_buff_FETCH(aTHX_ (rx),(paren),(usesv))
#define CALLREG_NUMBUF_STORE(rx,paren,value) \
RX_ENGINE(rx)->numbered_buff_STORE(aTHX_ (rx),(paren),(value))
#define CALLREG_NUMBUF_LENGTH(rx,sv,paren) \
RX_ENGINE(rx)->numbered_buff_LENGTH(aTHX_ (rx),(sv),(paren))
#define CALLREG_NAMED_BUFF_FETCH(rx, key, flags) \
RX_ENGINE(rx)->named_buff(aTHX_ (rx), (key), NULL, ((flags) | RXapif_FETCH))
#define CALLREG_NAMED_BUFF_STORE(rx, key, value, flags) \
RX_ENGINE(rx)->named_buff(aTHX_ (rx), (key), (value), ((flags) | RXapif_STORE))
#define CALLREG_NAMED_BUFF_DELETE(rx, key, flags) \
RX_ENGINE(rx)->named_buff(aTHX_ (rx),(key), NULL, ((flags) | RXapif_DELETE))
#define CALLREG_NAMED_BUFF_CLEAR(rx, flags) \
RX_ENGINE(rx)->named_buff(aTHX_ (rx), NULL, NULL, ((flags) | RXapif_CLEAR))
#define CALLREG_NAMED_BUFF_EXISTS(rx, key, flags) \
RX_ENGINE(rx)->named_buff(aTHX_ (rx), (key), NULL, ((flags) | RXapif_EXISTS))
#define CALLREG_NAMED_BUFF_FIRSTKEY(rx, flags) \
RX_ENGINE(rx)->named_buff_iter(aTHX_ (rx), NULL, ((flags) | RXapif_FIRSTKEY))
#define CALLREG_NAMED_BUFF_NEXTKEY(rx, lastkey, flags) \
RX_ENGINE(rx)->named_buff_iter(aTHX_ (rx), (lastkey), ((flags) | RXapif_NEXTKEY))
#define CALLREG_NAMED_BUFF_SCALAR(rx, flags) \
RX_ENGINE(rx)->named_buff(aTHX_ (rx), NULL, NULL, ((flags) | RXapif_SCALAR))
#define CALLREG_NAMED_BUFF_COUNT(rx) \
RX_ENGINE(rx)->named_buff(aTHX_ (rx), NULL, NULL, RXapif_REGNAMES_COUNT)
#define CALLREG_NAMED_BUFF_ALL(rx, flags) \
RX_ENGINE(rx)->named_buff(aTHX_ (rx), NULL, NULL, flags)
#define CALLREG_PACKAGE(rx) \
RX_ENGINE(rx)->qr_package(aTHX_ (rx))
#if defined(USE_ITHREADS)
# define CALLREGDUPE(prog,param) \
Perl_re_dup(aTHX_ (prog),(param))
# define CALLREGDUPE_PVT(prog,param) \
(prog ? RX_ENGINE(prog)->dupe(aTHX_ (prog),(param)) \
: (REGEXP *)NULL)
#endif
/* some compilers impersonate gcc */
#if defined(__GNUC__) && !defined(__clang__) && !defined(__INTEL_COMPILER)
# define PERL_IS_GCC 1
#endif
#define PERL_GCC_VERSION_GE(major,minor,patch) \
(((100000 * __GNUC__) + (1000 * __GNUC_MINOR__) + __GNUC_PATCHLEVEL__) \
>= ((100000 * (major)) + (1000 * (minor)) + (patch)))
#define PERL_GCC_VERSION_GT(major,minor,patch) \
(((100000 * __GNUC__) + (1000 * __GNUC_MINOR__) + __GNUC_PATCHLEVEL__) \
> ((100000 * (major)) + (1000 * (minor)) + (patch)))
#define PERL_GCC_VERSION_LE(major,minor,patch) \
(((100000 * __GNUC__) + (1000 * __GNUC_MINOR__) + __GNUC_PATCHLEVEL__) \
<= ((100000 * (major)) + (1000 * (minor)) + (patch)))
#define PERL_GCC_VERSION_LT(major,minor,patch) \
(((100000 * __GNUC__) + (1000 * __GNUC_MINOR__) + __GNUC_PATCHLEVEL__) \
< ((100000 * (major)) + (1000 * (minor)) + (patch)))
/* In case Configure was not used (we are using a "canned config"
* such as Win32, or a cross-compilation setup, for example) try going
* by the gcc major and minor versions. One useful URL is
* http://www.ohse.de/uwe/articles/gcc-attributes.html,
* but contrary to this information warn_unused_result seems
* not to be in gcc 3.3.5, at least. --jhi
* Also, when building extensions with an installed perl, this allows
* the user to upgrade gcc and get the right attributes, rather than
* relying on the list generated at Configure time. --AD
* Set these up now otherwise we get confused when some of the <*thread.h>
* includes below indirectly pull in <perlio.h> (which needs to know if we
* have HASATTRIBUTE_FORMAT).
*/
#ifndef PERL_MICRO
# if defined __GNUC__ && !defined(__INTEL_COMPILER)
# if PERL_GCC_VERSION_GE(3,1,0)
# define HASATTRIBUTE_DEPRECATED
# endif
# if PERL_GCC_VERSION_GE(3,0,0) /* XXX Verify this version */
# define HASATTRIBUTE_FORMAT
# if defined __MINGW32__
# define PRINTF_FORMAT_NULL_OK
# endif
# endif
# if PERL_GCC_VERSION_GE(3,0,0)
# define HASATTRIBUTE_MALLOC
# endif
# if PERL_GCC_VERSION_GE(3,3,0)
# define HASATTRIBUTE_NONNULL
# endif
# if PERL_GCC_VERSION_GE(2,5,0)
# define HASATTRIBUTE_NORETURN
# endif
# if PERL_GCC_VERSION_GE(3,0,0)
# define HASATTRIBUTE_PURE
# endif
# if PERL_GCC_VERSION_GE(3,4,0)
# define HASATTRIBUTE_UNUSED
# endif
# if __GNUC__ == 3 && __GNUC_MINOR__ == 3 && !defined(__cplusplus)
# define HASATTRIBUTE_UNUSED /* gcc-3.3, but not g++-3.3. */
# endif
# if PERL_GCC_VERSION_GE(3,4,0)
# define HASATTRIBUTE_WARN_UNUSED_RESULT
# endif
/* always_inline is buggy in gcc <= 4.6 and causes compilation errors */
# if PERL_GCC_VERSION_GE(4,7,0)
# define HASATTRIBUTE_ALWAYS_INLINE
# endif
# if PERL_GCC_VERSION_GE(3,3,0)
# define HASATTRIBUTE_VISIBILITY
# endif
# endif
#endif /* #ifndef PERL_MICRO */
#ifdef HASATTRIBUTE_DEPRECATED
# define __attribute__deprecated__ __attribute__((deprecated))
#endif
#ifdef HASATTRIBUTE_FORMAT
# define __attribute__format__(x,y,z) __attribute__((format(x,y,z)))
#endif
#ifdef HASATTRIBUTE_MALLOC
# define __attribute__malloc__ __attribute__((__malloc__))
#endif
#ifdef HASATTRIBUTE_NONNULL
# define __attribute__nonnull__(a) __attribute__((nonnull(a)))
#endif
#ifdef HASATTRIBUTE_NORETURN
# define __attribute__noreturn__ __attribute__((noreturn))
#endif
#ifdef HASATTRIBUTE_PURE
# define __attribute__pure__ __attribute__((pure))
#endif
#ifdef HASATTRIBUTE_UNUSED
# define __attribute__unused__ __attribute__((unused))
#endif
#ifdef HASATTRIBUTE_WARN_UNUSED_RESULT
# define __attribute__warn_unused_result__ __attribute__((warn_unused_result))
#endif
#ifdef HASATTRIBUTE_ALWAYS_INLINE
/* always_inline is buggy in gcc <= 4.6 and causes compilation errors */
# if !defined(PERL_IS_GCC) || PERL_GCC_VERSION_GE(4,7,0)
# define __attribute__always_inline__ __attribute__((always_inline))
# endif
#endif
#if defined(HASATTRIBUTE_VISIBILITY) && !defined(_WIN32) && !defined(__CYGWIN__)
/* On Windows instead of this, we use __declspec(dllexport) and a .def file
* Cygwin works by exporting every global symbol, see the definition of ldflags
* near the end of hints/cygwin.sh and the visibility attribute doesn't appear
* to control that.
*/
# define __attribute__visibility__(x) __attribute__((visibility(x)))
#endif
/* If we haven't defined the attributes yet, define them to blank. */
#ifndef __attribute__deprecated__
# define __attribute__deprecated__
#endif
#ifndef __attribute__format__
# define __attribute__format__(x,y,z)
#endif
#ifndef __attribute__malloc__
# define __attribute__malloc__
#endif
#ifndef __attribute__nonnull__
# define __attribute__nonnull__(a)
#endif
#ifndef __attribute__noreturn__
# define __attribute__noreturn__
#endif
#ifndef __attribute__pure__
# define __attribute__pure__
#endif
#ifndef __attribute__unused__
# define __attribute__unused__
#endif
#ifndef __attribute__warn_unused_result__
# define __attribute__warn_unused_result__
#endif
#ifndef __attribute__always_inline__
# define __attribute__always_inline__
#endif
#ifndef __attribute__visibility__
# define __attribute__visibility__(x)
#endif
/* Some OS warn on NULL format to printf */
#ifdef PRINTF_FORMAT_NULL_OK
# define __attribute__format__null_ok__(x,y,z) __attribute__format__(x,y,z)
#else
# define __attribute__format__null_ok__(x,y,z)
#endif
/*
* Because of backward compatibility reasons the PERL_UNUSED_DECL
* cannot be changed from postfix to PERL_UNUSED_DECL(x). Sigh.
*
* Note that there are C compilers such as MetroWerks CodeWarrior
* which do not have an "inlined" way (like the gcc __attribute__) of
* marking unused variables (they need e.g. a #pragma) and therefore
* cpp macros like PERL_UNUSED_DECL cannot work for this purpose, even
* if it were PERL_UNUSED_DECL(x), which it cannot be (see above).
=for apidoc_section $directives
=for apidoc AmnU||PERL_UNUSED_DECL
Tells the compiler that the parameter in the function prototype just before it
is not necessarily expected to be used in the function. Not that many
compilers understand this, so this should only be used in cases where
C<L</PERL_UNUSED_ARG>> can't conveniently be used.
Example usage:
=over
Signal_t
Perl_perly_sighandler(int sig, Siginfo_t *sip PERL_UNUSED_DECL,
void *uap PERL_UNUSED_DECL, bool safe)
=back
=cut
*/
#ifndef PERL_UNUSED_DECL
# define PERL_UNUSED_DECL __attribute__unused__
#endif
/* gcc -Wall:
* for silencing unused variables that are actually used most of the time,
* but we cannot quite get rid of, such as "ax" in PPCODE+noargs xsubs,
* or variables/arguments that are used only in certain configurations.
=for apidoc Am;||PERL_UNUSED_ARG|void x
This is used to suppress compiler warnings that a parameter to a function is
not used. This situation can arise, for example, when a parameter is needed
under some configuration conditions, but not others, so that C preprocessor
conditional compilation causes it be used just sometimes.
=for apidoc Amn;||PERL_UNUSED_CONTEXT
This is used to suppress compiler warnings that the thread context parameter to
a function is not used. This situation can arise, for example, when a
C preprocessor conditional compilation causes it be used just some times.
=for apidoc Am;||PERL_UNUSED_VAR|void x
This is used to suppress compiler warnings that the variable I<x> is not used.
This situation can arise, for example, when a C preprocessor conditional
compilation causes it be used just some times.
=cut
*/
#ifndef PERL_UNUSED_ARG
# define PERL_UNUSED_ARG(x) ((void)sizeof(x))
#endif
#ifndef PERL_UNUSED_VAR
# define PERL_UNUSED_VAR(x) ((void)sizeof(x))
#endif
#if defined(USE_ITHREADS)
# define PERL_UNUSED_CONTEXT PERL_UNUSED_ARG(my_perl)
#else
# define PERL_UNUSED_CONTEXT
#endif
/* gcc (-ansi) -pedantic doesn't allow gcc statement expressions,
* g++ allows them but seems to have problems with them
* (insane errors ensue).
* g++ does not give insane errors now (RMB 2008-01-30, gcc 4.2.2).
*/
#if defined(PERL_GCC_PEDANTIC) || \
(defined(__GNUC__) && defined(__cplusplus) && \
(PERL_GCC_VERSION_LT(4,2,0)))
# ifndef PERL_GCC_BRACE_GROUPS_FORBIDDEN
# define PERL_GCC_BRACE_GROUPS_FORBIDDEN
# endif
#endif
/*
=for apidoc Am||PERL_UNUSED_RESULT|void x
This macro indicates to discard the return value of the function call inside
it, I<e.g.>,
PERL_UNUSED_RESULT(foo(a, b))
The main reason for this is that the combination of C<gcc -Wunused-result>
(part of C<-Wall>) and the C<__attribute__((warn_unused_result))> cannot
be silenced with casting to C<void>. This causes trouble when the system
header files use the attribute.
Use C<PERL_UNUSED_RESULT> sparingly, though, since usually the warning
is there for a good reason: you might lose success/failure information,
or leak resources, or changes in resources.
But sometimes you just want to ignore the return value, I<e.g.>, on
codepaths soon ending up in abort, or in "best effort" attempts,
or in situations where there is no good way to handle failures.
Sometimes C<PERL_UNUSED_RESULT> might not be the most natural way:
another possibility is that you can capture the return value
and use C<L</PERL_UNUSED_VAR>> on that.
=cut
The __typeof__() is used instead of typeof() since typeof() is not
available under strict ISO C, and because of compilers masquerading
as gcc (clang and icc), we want exactly the gcc extension
__typeof__ and nothing else.
*/
#ifndef PERL_UNUSED_RESULT
# if defined(__GNUC__) && defined(HASATTRIBUTE_WARN_UNUSED_RESULT)
# define PERL_UNUSED_RESULT(v) STMT_START { __typeof__(v) z = (v); (void)sizeof(z); } STMT_END
# else
# define PERL_UNUSED_RESULT(v) ((void)(v))
# endif
#endif
/* on gcc (and clang), specify that a warning should be temporarily
* ignored; e.g.
*
* GCC_DIAG_IGNORE_DECL(-Wmultichar);
* char b = 'ab';
* GCC_DIAG_RESTORE_DECL;
*
* based on http://dbp-consulting.com/tutorials/SuppressingGCCWarnings.html
*
* Note that "pragma GCC diagnostic push/pop" was added in GCC 4.6, Mar 2011;
* clang only pretends to be GCC 4.2, but still supports push/pop.
*
* Note on usage: all macros must be used at a place where a declaration
* or statement can occur, i.e., not in the middle of an expression.
* *_DIAG_IGNORE() and *_DIAG_RESTORE can be used in any such place, but
* must be used without a following semicolon. *_DIAG_IGNORE_DECL() and
* *_DIAG_RESTORE_DECL must be used with a following semicolon, and behave
* syntactically as declarations (like dNOOP). *_DIAG_IGNORE_STMT()
* and *_DIAG_RESTORE_STMT must be used with a following semicolon,
* and behave syntactically as statements (like NOOP).
*
*/
#if defined(__clang__) || defined(__clang) || PERL_GCC_VERSION_GE(4,6,0)
# define GCC_DIAG_PRAGMA(x) _Pragma (#x)
/* clang has "clang diagnostic" pragmas, but also understands gcc. */
# define GCC_DIAG_IGNORE(x) _Pragma("GCC diagnostic push") \
GCC_DIAG_PRAGMA(GCC diagnostic ignored #x)
# define GCC_DIAG_RESTORE _Pragma("GCC diagnostic pop")
#else
# define GCC_DIAG_IGNORE(w)
# define GCC_DIAG_RESTORE
#endif
#define GCC_DIAG_IGNORE_DECL(x) GCC_DIAG_IGNORE(x) dNOOP
#define GCC_DIAG_RESTORE_DECL GCC_DIAG_RESTORE dNOOP
#define GCC_DIAG_IGNORE_STMT(x) GCC_DIAG_IGNORE(x) NOOP
#define GCC_DIAG_RESTORE_STMT GCC_DIAG_RESTORE NOOP
/* for clang specific pragmas */
#if defined(__clang__) || defined(__clang)
# define CLANG_DIAG_PRAGMA(x) _Pragma (#x)
# define CLANG_DIAG_IGNORE(x) _Pragma("clang diagnostic push") \
CLANG_DIAG_PRAGMA(clang diagnostic ignored #x)
# define CLANG_DIAG_RESTORE _Pragma("clang diagnostic pop")
#else
# define CLANG_DIAG_IGNORE(w)
# define CLANG_DIAG_RESTORE
#endif
#define CLANG_DIAG_IGNORE_DECL(x) CLANG_DIAG_IGNORE(x) dNOOP
#define CLANG_DIAG_RESTORE_DECL CLANG_DIAG_RESTORE dNOOP
#define CLANG_DIAG_IGNORE_STMT(x) CLANG_DIAG_IGNORE(x) NOOP
#define CLANG_DIAG_RESTORE_STMT CLANG_DIAG_RESTORE NOOP
#if defined(_MSC_VER)
# define MSVC_DIAG_IGNORE(x) __pragma(warning(push)) \
__pragma(warning(disable : x))
# define MSVC_DIAG_RESTORE __pragma(warning(pop))
#else
# define MSVC_DIAG_IGNORE(x)
# define MSVC_DIAG_RESTORE
#endif
#define MSVC_DIAG_IGNORE_DECL(x) MSVC_DIAG_IGNORE(x) dNOOP
#define MSVC_DIAG_RESTORE_DECL MSVC_DIAG_RESTORE dNOOP
#define MSVC_DIAG_IGNORE_STMT(x) MSVC_DIAG_IGNORE(x) NOOP
#define MSVC_DIAG_RESTORE_STMT MSVC_DIAG_RESTORE NOOP
/*
=for apidoc Amn;||NOOP
Do nothing; typically used as a placeholder to replace something that used to
do something.
=for apidoc Amn;||dNOOP
Declare nothing; typically used as a placeholder to replace something that used
to declare something. Works on compilers that require declarations before any
code.
=cut
*/
#define NOOP /*EMPTY*/(void)0
#define dNOOP struct Perl___notused_struct
#ifndef pTHX
/* Don't bother defining tTHX ; using it outside
* code guarded by MULTIPLICITY is an error.
*/
# define pTHX void
# define pTHX_
# define aTHX
# define aTHX_
# define aTHXa(a) NOOP
# define dTHXa(a) dNOOP
# define dTHX dNOOP
# define pTHX_1 1
# define pTHX_2 2
# define pTHX_3 3
# define pTHX_4 4
# define pTHX_5 5
# define pTHX_6 6
# define pTHX_7 7
# define pTHX_8 8
# define pTHX_9 9
# define pTHX_12 12
#endif
/*
=for apidoc_section $concurrency
=for apidoc AmnU||dVAR
This is now a synonym for dNOOP: declare nothing
=for apidoc_section $XS
=for apidoc Amn;||dMY_CXT_SV
Now a placeholder that declares nothing
=cut
*/
#ifndef PERL_CORE
/* Backwards compatibility macro for XS code. It used to be part of the
* PERL_GLOBAL_STRUCT(_PRIVATE) feature, which no longer exists */
# define dVAR dNOOP
/* these are only defined for compatibility; should not be used internally.
* */
# define dMY_CXT_SV dNOOP
# ifndef pTHXo
# define pTHXo pTHX
# define pTHXo_ pTHX_
# define aTHXo aTHX
# define aTHXo_ aTHX_
# define dTHXo dTHX
# define dTHXoa(x) dTHXa(x)
# endif
#endif
#ifndef pTHXx
# define pTHXx PerlInterpreter *my_perl
# define pTHXx_ pTHXx,
# define aTHXx my_perl
# define aTHXx_ aTHXx,
# define dTHXx dTHX
#endif
/* Under PERL_IMPLICIT_SYS (used in Windows for fork emulation)
* PerlIO_foo() expands to PL_StdIO->pFOO(PL_StdIO, ...).
* dTHXs is therefore needed for all functions using PerlIO_foo(). */
#ifdef PERL_IMPLICIT_SYS
# define dTHXs dTHX
#else
# define dTHXs dNOOP
#endif
#if defined(__GNUC__) && !defined(PERL_GCC_BRACE_GROUPS_FORBIDDEN) && !defined(__cplusplus)
# ifndef PERL_USE_GCC_BRACE_GROUPS
# define PERL_USE_GCC_BRACE_GROUPS
# endif
#endif
/*
=for apidoc_section $directives
=for apidoc AmnUu|void|STMT_END
=for apidoc_item | |STMT_START
These allow a series of statements in a macro to be used as a single statement,
as in
if (x) STMT_START { ... } STMT_END else ...
Note that you can't return a value out of this construct and cannot use it as
an operand to the comma operator. These limit its utility.
But, a value could be returned by constructing the API so that a pointer is
passed and the macro dereferences this to set the return. If the value can be
any of various types, depending on context, you can handle that situation in
some situations by adding the type of the return as an extra accompanying
parameter:
#define foo(param, type) STMT_START {
type * param; *param = do_calc; ...
} STMT_END
This could be awkward, so consider instead using a C language C<static inline>
function.
If you do use this construct, it is easy to forget that it is a macro and not a
function, and hence fall into traps that might not show up until someone
someday writes code which contains names that clash with the ones you chose
here, or calls it with a parameter which is an expression with side effects,
the consequences of which you didn't think about. See L<perlhacktips/Writing
safer macros> for how to avoid these.
=for apidoc_section $genconfig
=for apidoc Amn#||PERL_USE_GCC_BRACE_GROUPS
This C pre-processor value, if defined, indicates that it is permissible to use
the GCC brace groups extension. However, use of this extension is DISCOURAGED.
Use a C<static inline> function instead.
The extension, of the form
({ statement ... })
turns the block consisting of I<statement ...> into an expression with a
value, unlike plain C language blocks. This can present optimization
possibilities, B<BUT>, unless you know for sure that this will never be
compiled without this extension being available and not forbidden, you need to
specify an alternative. Thus two code paths have to be maintained, which can
get out-of-sync. All these issues are solved by using a C<static inline>
function instead.
Perl can be configured to not use this feature by passing the parameter
C<-Accflags=-DPERL_GCC_BRACE_GROUPS_FORBIDDEN> to F<Configure>.
=for apidoc Amnh#||PERL_GCC_BRACE_GROUPS_FORBIDDEN
Example usage:
=over
#ifdef PERL_USE_GCC_BRACE_GROUPS
...
#else
...
#endif
=back
=cut
Trying to select a version that gives no warnings...
*/
#if !(defined(STMT_START) && defined(STMT_END))
# define STMT_START do
# define STMT_END while (0)
#endif
#ifndef BYTEORDER /* Should never happen -- byteorder is in config.h */
# define BYTEORDER 0x1234
#endif
/*
=for apidoc_section $genconfig
=for apidoc Amn#||ASCIIish
A preprocessor symbol that is defined iff the system is an ASCII platform; this
symbol would not be defined on C<L</EBCDIC>> platforms.
=cut
*/
#if 'A' == 65 && 'I' == 73 && 'J' == 74 && 'Z' == 90
# define ASCIIish
#else
# undef ASCIIish
#endif
/*
* The following contortions are brought to you on behalf of all the
* standards, semi-standards, de facto standards, not-so-de-facto standards
* of the world, as well as all the other botches anyone ever thought of.
* The basic theory is that if we work hard enough here, the rest of the
* code can be a lot prettier. Well, so much for theory. Sorry, Henry...
*/
/* define this once if either system, instead of cluttering up the src */
#if defined(WIN32)
#define DOSISH 1
#endif
/* These exist only for back-compat with XS modules. */
#ifndef PERL_CORE
#define VOL volatile
#define CAN_PROTOTYPE
#define _(args) args
#define I_LIMITS
#define I_STDARG
#define STANDARD_C
#endif
/* By compiling a perl with -DNO_TAINT_SUPPORT or -DSILENT_NO_TAINT_SUPPORT,
* you get a perl without taint support, but doubtlessly with a lesser
* degree of support. Do not do so unless you know exactly what it means
* technically, have a good reason to do so, and know exactly how the
* perl will be used. perls with -DSILENT_NO_TAINT_SUPPORT are considered
* a potential security risk due to flat out ignoring the security-relevant
* taint flags. This being said, a perl without taint support compiled in
* has marginal run-time performance benefits.
* SILENT_NO_TAINT_SUPPORT implies NO_TAINT_SUPPORT.
* SILENT_NO_TAINT_SUPPORT is the same as NO_TAINT_SUPPORT except it
* silently ignores -t/-T instead of throwing an exception.
*
* DANGER! Using NO_TAINT_SUPPORT or SILENT_NO_TAINT_SUPPORT
* voids your nonexistent warranty!
*/
#if defined(SILENT_NO_TAINT_SUPPORT) && !defined(NO_TAINT_SUPPORT)
# define NO_TAINT_SUPPORT 1
#endif
/* NO_TAINT_SUPPORT can be set to transform virtually all taint-related
* operations into no-ops for a very modest speed-up. Enable only if you
* know what you're doing: tests and CPAN modules' tests are bound to fail.
*/
#ifdef NO_TAINT_SUPPORT
# define TAINT NOOP
# define TAINT_NOT NOOP
# define TAINT_IF(c) NOOP
# define TAINT_ENV() NOOP
# define TAINT_PROPER(s) NOOP
# define TAINT_set(s) NOOP
# define TAINT_get 0
# define TAINTING_get 0
# define TAINTING_set(s) NOOP
# define TAINT_WARN_get 0
# define TAINT_WARN_set(s) NOOP
#else
/*
=for apidoc_section $tainting
=for apidoc Cm|void|TAINT
If we aren't in taint checking mode, do nothing;
otherwise indicate to L</C<TAINT_set>> and L</C<TAINT_PROPER>> that some
unspecified element is tainted.
=for apidoc Cm|void|TAINT_NOT
Remove any taintedness previously set by, I<e.g.>, C<TAINT>.
=for apidoc Cm|void|TAINT_IF|bool c
If C<c> evaluates to true, call L</C<TAINT>> to indicate that something is
tainted; otherwise do nothing.
=for apidoc Cmn|void|TAINT_ENV
Looks at several components of L<C<%ENV>|perlvar/%ENV> for taintedness, and
calls L</C<taint_proper>> if any are tainted. The components it searches are
things like C<$PATH>.
=for apidoc Cm|void|TAINT_PROPER|const char * s
If no element is tainted, do nothing;
otherwise output a message (containing C<s>) that indicates there is a
tainting violation. If such violations are fatal, it croaks.
=for apidoc Cm|void|TAINT_set|bool s
If C<s> is true, L</C<TAINT_get>> returns true;
If C<s> is false, L</C<TAINT_get>> returns false;
=for apidoc Cm|bool|TAINT_get
Returns a boolean as to whether some element is tainted or not.
=for apidoc Cm|bool|TAINTING_get
Returns a boolean as to whether taint checking is enabled or not.
=for apidoc Cm|void|TAINTING_set|bool s
Turn taint checking mode off/on
=for apidoc Cm|bool|TAINT_WARN_get
Returns false if tainting violations are fatal;
Returns true if they're just warnings
=for apidoc Cm|void|TAINT_WARN_set|bool s
C<s> being true indicates L</C<TAINT_WARN_get>> should return that tainting
violations are just warnings
C<s> being false indicates L</C<TAINT_WARN_get>> should return that tainting
violations are fatal.
=cut
*/
/* Set to tainted if we are running under tainting mode */
# define TAINT (PL_tainted = PL_tainting)
# define TAINT_NOT (PL_tainted = FALSE) /* Untaint */
# define TAINT_IF(c) if (UNLIKELY(c)) { TAINT; } /* Conditionally taint */
# define TAINT_ENV() if (UNLIKELY(PL_tainting)) { taint_env(); }
/* croak or warn if tainting */
# define TAINT_PROPER(s) if (UNLIKELY(PL_tainting)) { \
taint_proper(NULL, s); \
}
# define TAINT_set(s) (PL_tainted = cBOOL(s))
# define TAINT_get (cBOOL(UNLIKELY(PL_tainted))) /* Is something tainted? */
# define TAINTING_get (cBOOL(UNLIKELY(PL_tainting)))
# define TAINTING_set(s) (PL_tainting = cBOOL(s))
# define TAINT_WARN_get (PL_taint_warn)
# define TAINT_WARN_set(s) (PL_taint_warn = cBOOL(s))
#endif
/* flags used internally only within pp_subst and pp_substcont */
#ifdef PERL_CORE
# define SUBST_TAINT_STR 1 /* string tainted */
# define SUBST_TAINT_PAT 2 /* pattern tainted */
# define SUBST_TAINT_REPL 4 /* replacement tainted */
# define SUBST_TAINT_RETAINT 8 /* use re'taint' in scope */
# define SUBST_TAINT_BOOLRET 16 /* return is boolean (don't taint) */
#endif
/* XXX All process group stuff is handled in pp_sys.c. Should these
defines move there? If so, I could simplify this a lot. --AD 9/96.
*/
/* Process group stuff changed from traditional BSD to POSIX.
perlfunc.pod documents the traditional BSD-style syntax, so we'll
try to preserve that, if possible.
*/
#ifdef HAS_SETPGID
# define BSD_SETPGRP(pid, pgrp) setpgid((pid), (pgrp))
#elif defined(HAS_SETPGRP) && defined(USE_BSD_SETPGRP)
# define BSD_SETPGRP(pid, pgrp) setpgrp((pid), (pgrp))
#elif defined(HAS_SETPGRP2)
# define BSD_SETPGRP(pid, pgrp) setpgrp2((pid), (pgrp))
#endif