/
perl.h
8457 lines (7430 loc) · 293 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
/* this is used for functions which take a depth trailing
* argument under debugging */
#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
/* See L<perlguts/"The Perl API"> for detailed notes on
* MULTIPLICITY and PERL_IMPLICIT_SYS */
/* XXX NOTE that from here --> to <-- the same logic is
* repeated in makedef.pl, so be certain to update
* both places when editing. */
#ifdef USE_ITHREADS
# if !defined(MULTIPLICITY)
# define MULTIPLICITY
# endif
#endif
/* PERL_IMPLICIT_CONTEXT is a legacy synonym for MULTIPLICITY */
#ifdef MULTIPLICITY
# ifndef PERL_IMPLICIT_CONTEXT
# define PERL_IMPLICIT_CONTEXT
# endif
#endif
#if defined(PERL_IMPLICIT_CONTEXT) && !defined(MULTIPLICITY)
# define MULTIPLICITY
#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(NETWARE) && !defined(WIN32)
# define USE_REENTRANT_API
#endif
/* <--- here ends the logic shared by perl.h and makedef.pl */
/*
=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
/* 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 __GNUC__ == 3 && __GNUC_MINOR__ >= 1 || __GNUC__ > 3 /* 3.1 -> */
# define HASATTRIBUTE_DEPRECATED
# endif
# if __GNUC__ >= 3 /* 3.0 -> */ /* XXX Verify this version */
# define HASATTRIBUTE_FORMAT
# if defined __MINGW32__
# define PRINTF_FORMAT_NULL_OK
# endif
# endif
# if __GNUC__ >= 3 /* 3.0 -> */
# define HASATTRIBUTE_MALLOC
# endif
# if __GNUC__ == 3 && __GNUC_MINOR__ >= 3 || __GNUC__ > 3 /* 3.3 -> */
# define HASATTRIBUTE_NONNULL
# endif
# if __GNUC__ == 2 && __GNUC_MINOR__ >= 5 || __GNUC__ > 2 /* 2.5 -> */
# define HASATTRIBUTE_NORETURN
# endif
# if __GNUC__ >= 3 /* gcc 3.0 -> */
# define HASATTRIBUTE_PURE
# endif
# if __GNUC__ == 3 && __GNUC_MINOR__ >= 4 || __GNUC__ > 3 /* 3.4 -> */
# 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 __GNUC__ == 3 && __GNUC_MINOR__ >= 4 || __GNUC__ > 3 /* 3.4 -> */
# define HASATTRIBUTE_WARN_UNUSED_RESULT
# endif
/* always_inline is buggy in gcc <= 4.6 and causes compilation errors */
# if __GNUC__ == 4 && __GNUC_MINOR__ >= 7 || __GNUC__ > 4 /* 4.7 -> */
# define HASATTRIBUTE_ALWAYS_INLINE
# 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) || (__GNUC__ == 4 && __GNUC_MINOR__ >= 7 || __GNUC__ > 4)
# define __attribute__always_inline__ __attribute__((always_inline))
# endif
#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
/* 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 Ams||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 some times.
=for apidoc Amns||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 Ams||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) && \
((__GNUC__ < 4) || ((__GNUC__ == 4) && (__GNUC_MINOR__ < 2))))
# 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 C89, 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
#if defined(_MSC_VER) && _MSC_VER < 1400
/* XXX older MSVC versions have a smallish macro buffer */
# define PERL_SMALL_MACRO_BUFFER
#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) || \
(defined( __GNUC__) && ((__GNUC__ * 100) + __GNUC_MINOR__) >= 406)
# 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) && (_MSC_VER >= 1300)
# 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 Amns||NOOP
Do nothing; typically used as a placeholder to replace something that used to
do something.
=for apidoc Amns||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 Amns||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_START
=for apidoc_item ||STMT_END
This allows 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 them, which limits their utility.
But see C<L</PERL_USE_GCC_BRACE_GROUPS>>.
=for apidoc AmnuU|bool|PERL_USE_GCC_BRACE_GROUPS
This C pre-processor value, if defined, indicates that it is permissible to use
the GCC brace groups extension. This extension, of the form
({ statement ... })
turns the block consisting of I<statements ...> into an expression with a
value, unlike plain C language blocks. This can present optimization
possibilities, B<BUT> you generally need to specify an alternative in case this
ability doesn't exist or has otherwise been 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))
# ifdef PERL_USE_GCC_BRACE_GROUPS
# define STMT_START (void)( /* gcc supports "({ STATEMENTS; })" */
# define STMT_END )
# else
# define STMT_START do
# define STMT_END while (0)
# endif
#endif
#ifndef BYTEORDER /* Should never happen -- byteorder is in config.h */
# define BYTEORDER 0x1234
#endif
#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(MSDOS) || defined(WIN32) || defined(NETWARE)
#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
/* 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 = (s))
# define TAINT_get (cBOOL(UNLIKELY(PL_tainted))) /* Is something tainted? */
# define TAINTING_get (cBOOL(UNLIKELY(PL_tainting))) /* Is taint checking enabled? */
# define TAINTING_set(s) (PL_tainting = (s))
# define TAINT_WARN_get (PL_taint_warn) /* FALSE => tainting violations
are fatal
TRUE => they're just
warnings */
# define TAINT_WARN_set(s) (PL_taint_warn = (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
#if defined(BSD_SETPGRP) && !defined(HAS_SETPGRP)
# define HAS_SETPGRP /* Well, effectively it does . . . */
#endif
/* getpgid isn't POSIX, but at least Solaris and Linux have it, and it makes
our life easier :-) so we'll try it.
*/
#ifdef HAS_GETPGID
# define BSD_GETPGRP(pid) getpgid((pid))
#elif defined(HAS_GETPGRP) && defined(USE_BSD_GETPGRP)
# define BSD_GETPGRP(pid) getpgrp((pid))
#elif defined(HAS_GETPGRP2)
# define BSD_GETPGRP(pid) getpgrp2((pid))
#endif
#if defined(BSD_GETPGRP) && !defined(HAS_GETPGRP)
# define HAS_GETPGRP /* Well, effectively it does . . . */
#endif
/* These are not exact synonyms, since setpgrp() and getpgrp() may
have different behaviors, but perl.h used to define USE_BSDPGRP
(prior to 5.003_05) so some extension might depend on it.
*/
#if defined(USE_BSD_SETPGRP) || defined(USE_BSD_GETPGRP)
# ifndef USE_BSDPGRP
# define USE_BSDPGRP
# endif
#endif
/* HP-UX 10.X CMA (Common Multithreaded Architecture) insists that
pthread.h must be included before all other header files.
*/
#if defined(USE_ITHREADS) && defined(PTHREAD_H_FIRST) && defined(I_PTHREAD)
# include <pthread.h>
#endif
#include <sys/types.h>
# ifdef I_WCHAR
# include <wchar.h>
# endif
# include <stdarg.h>
#ifdef I_STDINT
# include <stdint.h>
#endif
#include <ctype.h>
#include <float.h>
#include <limits.h>
#ifdef METHOD /* Defined by OSF/1 v3.0 by ctype.h */
#undef METHOD
#endif
#ifdef PERL_MICRO
# define NO_LOCALE
#endif
#ifdef I_LOCALE
# include <locale.h>
#endif
#ifdef I_XLOCALE
# include <xlocale.h>
#endif
/* If not forbidden, we enable locale handling if either 1) the POSIX 2008
* functions are available, or 2) just the setlocale() function. This logic is
* repeated in t/loc_tools.pl and makedef.pl; The three should be kept in
* sync. */
#if ! defined(NO_LOCALE)
# if ! defined(NO_POSIX_2008_LOCALE) \
&& defined(HAS_NEWLOCALE) \
&& defined(HAS_USELOCALE) \
&& defined(HAS_DUPLOCALE) \
&& defined(HAS_FREELOCALE) \
&& defined(LC_ALL_MASK)
/* For simplicity, the code is written to assume that any platform advanced
* enough to have the Posix 2008 locale functions has LC_ALL. The final
* test above makes sure that assumption is valid */
# define HAS_POSIX_2008_LOCALE
# define USE_LOCALE
# elif defined(HAS_SETLOCALE)
# define USE_LOCALE
# endif
#endif
#ifdef USE_LOCALE
# define HAS_SKIP_LOCALE_INIT /* Solely for XS code to test for this
#define */
# if !defined(NO_LOCALE_COLLATE) && defined(LC_COLLATE) \
&& defined(HAS_STRXFRM)
# define USE_LOCALE_COLLATE
# endif
# if !defined(NO_LOCALE_CTYPE) && defined(LC_CTYPE)
# define USE_LOCALE_CTYPE
# endif
# if !defined(NO_LOCALE_NUMERIC) && defined(LC_NUMERIC)
# define USE_LOCALE_NUMERIC
# endif
# if !defined(NO_LOCALE_MESSAGES) && defined(LC_MESSAGES)
# define USE_LOCALE_MESSAGES
# endif
# if !defined(NO_LOCALE_MONETARY) && defined(LC_MONETARY)
# define USE_LOCALE_MONETARY
# endif
# if !defined(NO_LOCALE_TIME) && defined(LC_TIME)
# define USE_LOCALE_TIME
# endif
# if !defined(NO_LOCALE_ADDRESS) && defined(LC_ADDRESS)
# define USE_LOCALE_ADDRESS
# endif
# if !defined(NO_LOCALE_IDENTIFICATION) && defined(LC_IDENTIFICATION)
# define USE_LOCALE_IDENTIFICATION
# endif
# if !defined(NO_LOCALE_MEASUREMENT) && defined(LC_MEASUREMENT)
# define USE_LOCALE_MEASUREMENT
# endif
# if !defined(NO_LOCALE_PAPER) && defined(LC_PAPER)
# define USE_LOCALE_PAPER
# endif
# if !defined(NO_LOCALE_TELEPHONE) && defined(LC_TELEPHONE)
# define USE_LOCALE_TELEPHONE
# endif
# if !defined(NO_LOCALE_SYNTAX) && defined(LC_SYNTAX)
# define USE_LOCALE_SYNTAX
# endif
# if !defined(NO_LOCALE_TOD) && defined(LC_TOD)
# define USE_LOCALE_TOD
# endif
/* XXX The next few defines are unfortunately duplicated in makedef.pl, and
* changes here MUST also be made there */
# if ! defined(HAS_SETLOCALE) && defined(HAS_POSIX_2008_LOCALE)
# define USE_POSIX_2008_LOCALE
# ifndef USE_THREAD_SAFE_LOCALE
# define USE_THREAD_SAFE_LOCALE