forked from Perl/perl5
-
Notifications
You must be signed in to change notification settings - Fork 0
/
embed.fnc
6367 lines (6315 loc) · 199 KB
/
embed.fnc
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
: BEGIN{die "You meant to run regen/embed.pl"} # Stop early if fed to perl.
:
: WARNING: The meanings of some flags have been changed as of v5.31.0
:
: This file is known to be processed by regen/embed.pl, autodoc.pl,
: makedef.pl, Devel::PPPort, and porting/diag.t.
:
: This file contains entries for various functions and macros defined by perl.
: Each entry includes the name, parameters, and various attributes about it.
: In most functions listed here, the name is a short name, and the function's
: real name is the short one, prefixed by either 'Perl_' (for publicly visible
: functions) or 'S_' (for internal-to-a-file static ones). In many instances a
: macro is defined that is the name in this file, and which expands to call the
: real (full) name, with any appropriate thread context paramaters, thus hiding
: that detail from the typical code.
:
: Many macros (as opposed to functions) listed here are the complete full name,
: though we may want to start converting those to have full names.
:
: All non-static functions defined by perl need to be listed in this file.
: embed.pl uses the entries here to construct:
: 1) proto.h to declare to the compiler the function interfaces; and
: 2) embed.h to create short name macros
:
: Static functions internal to a file need not appear here, but there is
: benefit to declaring them here:
: 1) It generally handles the thread context parameter invisibly making it
: trivial to add or remove needing thread context passed;
: 2) It defines a PERL_ARGS_ASSERT_foo macro, which can save you debugging
: time;
: 3) It is is automatically known to Devel::PPPort, making it quicker to
: later find out when it came into existence. For example
: perl ppport.h --api-info=/edit_distance/
: yields
: Supported at least since perl-5.23.8, with or without ppport.h.
:
: Lines in this file are of the form:
: flags|return_type|name|arg1|arg2|...|argN
:
: 'flags' is a string of single letters. Most of the flags are meaningful only
: to embed.pl; some only to autodoc.pl, and others only to makedef.pl. The
: comments here mostly don't include how Devel::PPPort or diag.t use them:
: All the possible flags and their meanings are given below.
:
: A function taking no parameters will have no 'arg' elements.
: A line may be continued onto the next by ending it with a backslash.
: Leading and trailing whitespace will be ignored in each component.
:
: Most entries here have a macro created with the entry name. This presents
: name space collision potentials which haven't been well thought out, but are
: now documented here. In practice this has rarely been an issue. At least,
: with a macro, the XS author can #undef it, unlike a function.
:
: The default without flags is to declare a function for internal perl-core use
: only. The short name is visible only when the PERL_CORE symbol is defined.
: On some platforms all non-static functions are currently externally visible.
: Because of this, and also for programs that embed perl, most non-static
: functions should have the 'p' flag to avoid namespace clashes.
:
: There are several advantages to using a macro instead of the full Perl_foo or
: S_foo form: it hides the need to know if the called function requires a
: thread context parameter or not, and the code using it is more readable
: because of fewer parameters being visible. And if there is some bug in it
: that gets fixed in a later release, ppport.h can be changed to automatically
: backport the fixed version to modules. The only disadvantage khw can think
: of is the namespace pollution one.
:
: WARNING: Any macro created in a header file is visible to XS code, unless
: care is taken to wrap it within C preprocessor guards like the following
:
: #if defined(PERL_CORE)
: ...
: #endif
:
: A common pattern is to use defines like 'PERL_IN_FILE_C' (with FILE_C being
: appropriately replaced with the real filename). Most, if not all, of the
: perl core C files define such a symbol before importing perl.h. Some groups
: of files define more generalized flags which are referenced in this file and
: the files generated from it.
:
: In general you should restrict the exposure of your exports as much as
: possible, although older code may not do so. Be aware that non-static
: exports can be "over exported" and things will likely work out fine, but
: inline and static macros will cause errors unless restricted to the specific
: file they are intended for, and the generated PERL_ARGS_ macros will only
: be available to inline functions in the appropriate context.
:
: From time to time it may be necessary to change or expand which files can
: see a function, therefore we prefer the '#if defined()' form of condition
: instead of the '#ifdef' form as the latter only works with one symbol and
: the former can be combined with more than one. It is also why you may see
: functions with an 's' or 'i' export type grouped together into a single
: conditional block separate from most of the other functions from the same
: file with 'p' in them.
:
: The 'A' flag is used to make a function and its short name visible everywhere
: on all platforms. This should be used to make it part of Perl's API
: contract with XS developers. The documentation for these is usually
: placed in perlapi. If no documentation exists, that fact is also
: noted in perlapi.
:
: The 'C' flag is used instead for functions and their short names that need to
: be accessible everywhere, typically because they are called from a
: publicly available macro or inline function, but they are not for
: public use by themselves. The documentation for these is placed in
: perlintern. If no documentation exists, that fact is also noted in
: perlintern.
:
: These really need the 'p' flag to avoid name space collisions.
:
: Some of these have been constructed so that the wrapper macro names
: begin with an underscore to lessen the chances of a name collision.
: However, this is contrary to the C standard, and those should be
: changed.
:
: The 'E' flag is used instead for a function and its short name that is
: supposed to be used only in the core plus extensions compiled with
: the PERL_EXT symbol defined. Again, on some platforms, the function
: will be visible everywhere, so one of the 'p' or 'S' flags is
: generally needed. Also note that an XS writer can always cheat and
: pretend to be an extension by #defining PERL_EXT.
:
: The 'X' flag is similar to the 'C' flag in that the function (whose entry
: better have the 'p' flag) is accessible everywhere on all platforms.
: However the short name macro that normally gets generated is
: suppressed outside the core. (Except it is also visible in PERL_EXT
: extensions if the 'E' flag is also specified.) This flag is used for
: functions that are called from a public macro, the name of which
: isn't derived from the function name. You'll have to write the macro
: yourself, and from within it, refer to the function in its full
: 'Perl_' form with any necessary thread context parameter.
:
: Just below is a description of the relevant parts of the automatic
: documentation generation system which heavily involves this file. Below that
: is a description of all the flags used in this file.
:
: Scattered around the perl source are lines of the form:
:
: =for apidoc name ...
: =for apidoc_item name ...
: =for apidoc_defn name ...
:
: The purpose of these lines is to furnish documentation for functions and
: macros. The lines tend to be placed near the source for the item they
: describe. autodoc.pl is run as part of the standard build process to
: extract this documentation and build either perlapi.pod (from the elements
: that are flagged as A in this file), or perlintern.pod (from the other
: elements.
:
: Functions need to be specified in this file, but macros may not necessarily
: be. The information in this file is sufficient to generate a usage line for
: the element to be documented; otherwise that information needs to be
: specified in the apidoc-ish lines.
:
: 'apidoc_defn' was added to supplement, for macros, the information in this
: file. It is designed to be placed at the point of definition of the macro
: it is for, so that the information can easily be checked for correctness,
: and you know at a glance that the macro actually has documentation. It
: doesn't by itself create any documentation; instead the other apidoc lines
: pull in information specified by these lines. Many of the lines in this
: file for macros that don't also have the 'p' flag (described below) could be
: pulled out of here and replaced by these lines throughout the source. It is
: a goal to do that as convenience dictates.
:
: The other apidoc lines either have the usage data as part of the line, or
: pull in the data from this file or apidoc_defn lines.
:
: Many macros and functions are variants of each other. It makes sense to use
: a single group to document such elements so their similarities and
: differences stand out, with less repetition than if there were separate
: entries. Such groups start with a plain 'apidoc' line, followed by any
: number of 'apidoc_item' lines. These indicate that the macro or function
: listed as 'name' on each is part of the group whose head entry is the one
: specified by 'name' on the apidoc line.
:
: After the block of apidoc-like statements, is the text that is the
: documentation, ending with the next =cut or '=for apidoc foo' lines.
:
: The apidoc_item lines must all come after the apidoc line and before the pod
: text for the entry. There need not be empty lines between the apidoc line
: and any of its apidoc_item lines.
:
: The entries in this file that have corresponding '=for apidoc' entries must
: have the 'd' flag set in this file.
:
: In C files, the apidoc lines are inside comment blocks. They may also be
: placed in pod files. In those, the =for causes lines from there until the
: next line beginning with an '=' to not be considered part of that pod.
:
: The 'h' flag is used to hide (suppress) the pod associated with =apidoc lines
: from being placed in the generated perlapi or perlintern. There are several
: reasons you might want to do this, given in the 'h' flag description below,
: but one is for the case where the =apidoc occurs in a file that contains
: regular pod. Without that flag, the associated pod will be placed in both
: it, and perlapi or perlintern. That may be what you want, but it gives you
: the flexibility to choose that, or instead have just a link to the source pod
: inserted in perlapi or perlintern. This allows single-source browsing for
: someone; they don't have to scan multiple pods trying to find whether
: something suitable exists.
:
: There are also lines of this form scattered around the perl
: source:
:
: =for apidoc_section Section Name
: =head1 Section Name
:
: These organize the resultant pod file into major subgroups of related
: functionality, but aren't tied to this embed.fnc file, and so are documented
: in autodoc.pl.
:
: What goes into the documentation of a particular function ends with the next
: line that begins with an '='. In particular, an '=cut' line ends that
: documentation without introducing something new.
:
: Various macros and other elements aren't listed here in embed.fnc (though
: they could be). They are documented in the same manner, but since they don't
: have this file to get information from, the defining lines have the syntax
: and meaning they do in this file, so it can be specified:
:
: =for apidoc flags|return_type|name|arg1|arg2|...|argN
: =for apidoc_item flags|return_type|name|arg1|arg2|...|argN
: =for apidoc_defn flags|return_type|name|arg1|arg2|...|argN
:
: The 'name' in any such line must not be the same as any in this file (i.e.,
: no redundant definitions), and one of the flags on the apidoc lines must be
: 'm' or 'y', indicating it is not a function.
:
: All but the name field of an apidoc_item line are optional, and if empty,
: inherits from a corresponding apidoc_defn line, if one exists, or the
: controlling plain apidoc line if none such exist. The flags field is
: generally empty, and in fact, the only flags it can have are ones directly
: related to its display. For example it might have the T flag to indicate no
: thread context parameter is used, whereas the apidoc entry does have a
: thread context. Here is an example:
:
: =for apidoc Am|char* |SvPV |SV* sv|STRLEN len
: =for apidoc_item |const char*|SvPV_const |SV* sv|STRLEN len
: =for apidoc_item |char* |SvPV_nolen |SV* sv
:
: Since these are macros, the arguments need not be legal C parameters. To
: indicate this to downstream software that inspects these lines, there are a
: few conventions. An example would be:
:
: =for apidoc Am|void|Newxc|void* ptr|int nitems|type|cast
:
: In this example, a real call of Newxc, 'type' would be specified as something
: like 'int' or 'char', and 'cast' by perhaps 'struct foo'.
:
: The complete list of conventions is:
: type the argument names a type
: cast the argument names a type which the macro casts to
: SP the argument is the stack pointer, SP
: block the argument is a C brace-enclosed block
: number the argument is a C numeric constant, like 3
: token the argument is a generic C preprocessor token, like abc
: "string" the argument is a literal C double-quoted string; what's important
: here are the quotes; for clarity, you can say whatever you want
: inside them
:
: Unlike other arguments, none of these is of the form 'int name'. There is no
: name.
:
: If any argument or return value is not one of the above, and isn't legal C
: language, the entry still can be specified, using the 'u' flag.
:
: 'return_type' in these lines can be empty, unlike in this file:
:
: =for apidoc Amnu||START_EXTERN_C
:
: Devel::PPPort also looks at both this file and the '=for apidoc' lines. In
: part it is to construct lists of elements that are or are not backported.
:
: makedef.pl uses this file for constructing the export list which lists the
: symbols that should be available on all platforms.
:
: porting/diag.t checks some things for consistency based on this file.
:
: The remainder of these introductory comments detail all the possible flags:
:
: 'A' Both long and short names are accessible fully everywhere (usually
: part of the public API). If the function is not part of the public
: API, instead use 'C', 'E', or 'X'.
:
: * adds entry to the list of symbols available on all platforms unless
: 'e' or 'm' are also specified;
: * any doc entry goes in perlapi.pod rather than perlintern.pod. If
: there isn't a doc entry, autodoc.pl lists this in perlapi as
: existing and being undocumented; unless 'x' is also specified, in
: which case it simply isn't listed.
: * makes the short name defined for everywhere, not just for PERL_CORE
: or PERL_EXT
:
: 'a' Allocates memory a la malloc/calloc. Also implies 'R'. This flag
: should only be on a function which returns "empty" memory which has no
: other pointers to it, and which does not contain any pointers to other
: things. So for example realloc() can not be 'a'.
:
: proto.h: add __attribute__malloc__
:
: 'b' Binary backward compatibility. This is used for functions which are
: kept only to not have to change legacy applications that call them. If
: there are no such legacy applications in a Perl installation for all
: functions flagged with this, the installation can run Configure with
: the -Accflags='-DNO_MATHOMS' parameter to not even compile them.
:
: If the function can be implemented as a macro (that evaluates its
: arguments exactly once), use the 'm' and 'p' flags together to implement
: this. (See the discussion under 'm'.) Another option for this is to
: use the 'M' flag.
:
: Without the m or M flags, these functions should be deprecated, and it
: is an error to not also specify the 'D' flag.
:
: The 'b' functions are normally moved to mathoms.c, but if
: circumstances dictate otherwise, they can be anywhere, provided the
: whole function is wrapped with
:
: #ifndef NO_MATHOMS
: ...
: #endif
:
: Note that this flag no longer automatically adds a 'Perl_' prefix to
: the name. Additionally specify 'p' to do that.
:
: This flag effectively causes nothing to happen if the perl interpreter
: is compiled with -DNO_MATHOMS (which causes any functions with this
: flag to not be compiled); otherwise these happen:
:
: * add entry to the list of symbols available on all platforms;
: * create PERL_ARGS_ASSERT_foo;
: * add embed.h entry (unless overridden by the 'M' or 'o' flags)
:
: 'C' Intended for core use only. This indicates to XS writers that they
: shouldn't be using this function. Devel::PPPort informs them of this,
: for example. Some functions have to be accessible everywhere even if
: they are not intended for public use. An example is helper functions
: that are called from inline ones that are publicly available.
:
: * add entry to the list of symbols available on all platforms unless e
: or m are also specified;
: * any doc entry goes in perlintern.pod rather than perlapi.pod. If
: there isn't a doc entry, autodoc.pl lists this in perlintern as
: existing and being undocumented
: * makes the short name defined for everywhere, not just for PERL_CORE
: or PERL_EXT
:
: 'D' Function is deprecated:
:
: proto.h: add __attribute__deprecated__
: autodoc.pl adds a note to this effect in the doc entry
:
: 'd' Function has documentation (somewhere) in the source:
:
: Enables 'no docs for foo" warning in autodoc.pl if the documentation
: isn't found.
:
: 'E' Visible to extensions included in the Perl core:
:
: in embed.h, change "#ifdef PERL_CORE"
: into "#if defined(PERL_CORE) || defined(PERL_EXT)"
:
: To be usable from dynamically loaded extensions, either:
: 1) it must be static to its containing file ('i' or 'S' flag); or
: 2) be combined with the 'X' flag.
:
: 'e' Not exported
:
: suppress entry in the list of symbols available on all platforms
:
: 'f' Function takes a format string. If the function name =~ qr/strftime/
: then it is assumed to take a strftime-style format string as the 1st
: arg; otherwise it's assumed to take a printf style format string, not
: necessarily the 1st arg. All the arguments following the second form
: (including possibly '...') are assumed to be for the format.
:
: embed.h: any entry in here for the second form is suppressed because
: of varargs
: proto.h: add __attribute__format__ (or ...null_ok__)
:
: 'F' Function has a '...' parameter, but don't assume it is a format. This
: is to make sure that new functions with formats can't be added without
: considering if they are format functions or not. A reason to use this
: flag even on a format function is if the format would generate error:
: format string argument is not a string type
:
: 'G' Suppress empty PERL_ARGS_ASSERT_foo macro. Normally such a macro is
: generated for all entries for functions 'foo' in this file. If there
: is a pointer argument to 'foo', it needs to be declared in this file
: as either NN or NULLOK, and the function definition must call its
: corresponding PERL_ARGS_ASSERT_foo macro (a porting test ensures this)
: which asserts at runtime (under DEBUGGING builds) that NN arguments
: are not NULL. If there aren't NN arguments, use of this macro is
: optional. Rarely, a function will define its own PERL_ARGS_ASSERT_foo
: macro, and in those cases, adding this flag to its entry in this file
: will suppress the normal one. It is not possible to suppress the
: generated macro if it isn't optional, that is, if there is at least
: one NN argument.
:
: proto.h: PERL_ARGS_ASSERT macro is not defined unless the function
: has NN arguments
:
: 'h' Hide any documentation that would normally go into perlapi or
: perlintern. This is typically used when the documentation is actually
: in another pod. If you don't use the 'h', that documentation is
: displayed in both places; with the flag, it stays in the pod, and a
: link to that pod is instead placed in perlapi or perlintern. This
: allows one to browse perlapi or perlintern and see all the potentially
: relevant elements. A good example is perlapio. It has documentation
: about PerlIO functions with other text giving context. There's no
: point in writing a second entry for perlapi, but it would be good if
: someone browsing perlapi knew about the function and where it is
: documented. By adding '=for apidoc' lines in perlapio, the appropriate
: text could be simply copied into perlapi if deemed appropriate, or
: just a link added there when the 'h' flag is specified.
:
: This flag is useful for symbolic names for flags. A single =for apidoc
: line can be added to the pod where the meaning is discussed, and
: perlapi will list the name, with a link to the pod. Another use would
: be if there are a bunch of macros which follow a common paradigm in
: their naming, so rather than having an entry for each slight
: variation, there is an overarching one. This flag is useful for
: downstream programs, such as Devel::PPPort.
:
: 'i' inline static. This is used for functions that the compiler is being
: requested to inline. If the function is in a header file its
: definition will be visible (unless guarded by #if..#endif) to all XS
: code. (A typical guard will be that it is being included in a
: particular C file(s) or in the perl core.) Therefore, all non-guarded
: functions should also have the 'p' flag specified to avoid polluting
: the XS code name space. Otherwise, this flag also turns on the 'S'
: flag.
:
: proto.h: function is declared as PERL_STATIC_INLINE
:
: 'I' This flag works exactly the same as 'i' but it also adds
: __attribute__((always_inline)) or __forceinline if either of them is
: supported by the compiler.
:
: proto.h: function is declared as PERL_STATIC_FORCE_INLINE and
: __attribute__always_inline__ is added
:
: 'm' Implemented as a macro; there is no function associated with this
: name. There is no long S_ name.
:
: However, you may #define the macro with a long name like 'Perl_foo',
: and specify the 'p' flag. This will cause an embed.h entry to be
: created that #defines 'foo' as 'Perl_foo'. This can be used to make
: any macro have a long name, perhaps to avoid name collisions. If
: instead you define the macro as 'PERL_FOO' (all uppercase), the
: embed.h entry will use all uppercase.
:
: It is particularly useful tp preserve backward compatibility when a
: function is converted to be a macro (remembering to not create a macro
: which evaluates its parameters more than once). Most of mathoms.c
: could be converted to use this facility. When there is no thread
: context involved, you just do something like
:
: #define Perl_foo(a, b, c) Perl_bar(a, b, 0, c)
:
: Otherwise consider this general case where there is a series of macros
: that build on the previous ones by calling something with a different
: name or with an extra parameter beyond what the previous one did:
:
: #define Perl_foo(mTHX, a) Perl_bar1(aTHX, a)
: #define Perl_bar1(mTHX, a) Perl_bar2(aTHX, a, 0)
: #define Perl_bar2(mTHX, a, b) Perl_bar3(aTHX, a, b, 0)
: #define Perl_bar3(mTHX, a, b, c) Perl_func(aTHX_ a, b, c, 0)
:
: Use the formal parameter name 'mTHX,' (which stands for "macro thread
: context") as the first in each macro definition, and call the next
: macro in the sequence with 'aTHX,' (Note the commas). Eventually, the
: sequence will end with a function call (or else there would be no need
: for thread context). For that instead call it with 'aTHX_' (with an
: underscore instead of a comma).
:
: suppress proto.h entry (actually, not suppressed, but commented out)
: suppress entry in the list of exported symbols available on all
: platforms
: suppress embed.h entry (when no 'p' flag), as the implementation
: should furnish the macro
:
: 'M' The implementation is furnishing its own macro instead of relying on
: the automatically generated short name macro (which simply expands to
: call the real name function). One reason to do this is if the
: parameters need to be cast from what the caller has. There is less
: need to do this now that 'm' and 'p' together is supported.
:
: This flag requires the 'p' flag to be specified, as there would be no
: need to do this if the function weren't publicly accessible before.
:
: The entry is processed based on the other flags, but the:
: embed.h entry is suppressed
:
: 'N' The name in the entry isn't strictly a name
:
: Normally, the name of the function or macro must contain all \w
: characters, and a warning is raised otherwise. This flag suppresses
: that warning, so that weird things can be documented
:
: 'n' Has no argument list (used only in =for apidoc entries)
:
: The macro (it can't be a function) is used without any parameters nor
: empty parentheses.
:
: Perhaps a better name for this flag would have been '0'. The reason
: the flag was not changed to that from 'n', is if D:P were to be
: regenerated on an older perl, it still would use the new embed.fnc
: shipped with it, but would be using the flags from the older perl
: source code.
:
: 'O' Has a perl_ compatibility macro.
:
: The really OLD name for API funcs.
:
: autodoc.pl adds a note that the perl_ form of this function is
: deprecated.
:
: 'o' Has no Perl_foo or S_foo compatibility macro:
:
: This is used for whatever reason to force the function to be called
: with the long name. Perhaps there is a varargs issue. Use the 'M'
: or 'm' flags instead for wrapper macros, and legacy-only functions
: should also use 'b'.
:
: embed.h: suppress "#define foo Perl_foo"
:
: mnemonic: 'omit' generated macro
:
: 'P' Pure function:
:
: A pure function has no effects except the return value, and the return
: value depends only on params and/or globals. This is a hint to the
: compiler that it can optimize calls to this function out of common
: subexpressions. Consequently if this flag is wrongly specified, it can
: lead to subtle bugs that vary by platform, compiler, compiler version,
: and optimization level. Also, a future commit could easily change a
: currently-pure function without even noticing this flag. So it should
: be used sparingly, only for functions that are unlikely to ever become
: not pure by future commits. It should not be used for static
: functions, as the compiler already has the information needed to make
: the 'pure' determination and doesn't need any hint; so it doesn't add
: value in those cases, and could be dangerous if it causes the compiler
: to skip doing its own checks. It should not be used on functions that
: touch SVs, as those can trigger unexpected magic. Also implies "R":
:
: proto.h: add __attribute__pure__
:
: 'p' Function or macro in source code has a Perl_ prefix:
:
: proto.h: function or macro is declared as Perl_foo rather than foo
: (though the entries for macros will be commented out)
: embed.h: "#define foo Perl_foo" entries added
:
: 'R' Return value must not be ignored (also implied by 'a' and 'P' flags):
:
: gcc has a bug (which they claim is a feature) in which casting the
: result of one of these to (void) doesn't silence the warning that the
: result is ignored. (Perl has a workaround for this bug, see
: PERL_UNUSED_RESULT docs)
:
: proto.h: add __attribute__warn_unused_result__
:
: 'r' Function never returns:
:
: proto.h: add __attribute__noreturn__
:
: 'S' Static function: function in source code has a S_ prefix:
:
: proto.h: function is declared as S_foo rather than foo,
: STATIC is added to declaration;
: embed.h: "#define foo S_foo" entries added
:
: 's' Static function, but function in source code has a Perl_ prefix:
:
: This is used for functions that have always had a Perl_ prefix, but
: have been moved to a header file and declared static.
:
: proto.h: function is declared as Perl_foo rather than foo
: STATIC is added to declaration;
: embed.h: "#define foo Perl_foo" entries added
:
: 'T' Has no implicit interpreter/thread context argument:
:
: suppress the pTHX part of "foo(pTHX...)" in proto.h;
: In the PERL_IMPLICIT_SYS branch of embed.h, generates
: "#define foo Perl_foo", rather than
: "#define foo(a,b,c) Perl_foo(aTHX_ a,b,c)
:
: 'u' The macro's (it has to be a macro) return value or parameters are
: unorthodox, and aren't in the list above of recognized weird ones. For
: example, they aren't C parameters, or the macro expands to something
: that isn't a symbol.
:
: For example, the expansion of STR_WITH_LEN is a comma separated pair
: of values, so would have this flag; or some macros take preprocessor
: tokens, so would have this flag.
:
: This also is used for entries that require processing for use, such as
: being compiled by xsubpp. This flag is an indication to downstream
: tools, such as Devel::PPPort, that this requires special handling.
:
: 'U' autodoc.pl will not output a usage example
:
: 'v' Guard the macro by !MULTIPLICITY || PERL_CORE if it uses __VA_ARGS__.
: This flag exists for backward-compatibility to ensure that code does
: not break when calling older functions without an aTHX in scope. It
: should not be added to newly-added functions as they will have no such
: compatibility issues.
:
: 'W' Add a comma_pDEPTH argument to function prototypes, and a comma_aDEPTH
: argument to the function calls. This means that under DEBUGGING a
: depth argument is added to the functions, which is used for example by
: the regex engine for debugging and trace output. A non DEBUGGING build
: will not pass the unused argument. Currently restricted to functions
: with at least one argument.
:
: 'X' Explicitly exported:
:
: add entry to the list of symbols available on all platforms, unless
: 'e' or 'm'
:
: This is often used for private functions that are used by public
: macros. In those cases the macros must use the long form of the name
: (Perl_blah(aTHX_ ...)).
:
: 'x' Experimental, may change:
:
: Any doc entry is marked that it may change. An undocumented
: experimental function is listed in perlintern rather than perlapi,
: even if it is allegedly API.
:
: 'y' Typedef. The element names a type rather than being a macro
:
: ';' autodoc.pl adds a terminating semi-colon to the usage example in the
: documentation.
:
: '#' The number sign flag indicates that this is a pre-processor symbol
: that is just #define'd or #undef'd. Must NOT be the first symbol on
: the line.
:
: '?' The question mark flag is used internally by Devel::PPPort to
: indicate that it does not have enough information to generate a
: proper test case.
:
: In this file, pointer parameters that must not be passed NULLs should be
: prefixed with NN.
:
: And, pointer parameters that may be NULL should be prefixed with NULLOK.
: This has no effect on output yet. It's a notation for the maintainers to
: know "I have defined whether NULL is OK or not" rather than having neither
: NULL or NULLOK, which is ambiguous.
:
: Pointer parameters that point to AVs, CVs or HVs will generate additional
: checks in the arguments assertion macro, that check on entry to the
: function that the SV being pointed to is of the intended type, by
: inspecting its SvTYPE(). For some functions this check may be inappropriate
: as in rare cases the arguments passed may not be of the correct type. To
: skip checking on an argument type, prefix its type with NOCHECK.
:
: Numeric arguments may also be prefixed with NZ, which will cause the
: appropriate asserts to be generated to validate that this is the case.
:
: Flags should be sorted asciibetically.
:
: Please keep the next line *BLANK*
pr |void |abort_execution|NULLOK SV *msg_sv \
|NN const char * const name
px |LOGOP *|alloc_LOGOP |I32 type \
|NULLOK OP *first \
|NULLOK OP *other
: Used in toke.c and perly.y
p |PADOFFSET|allocmy |NN const char * const name \
|const STRLEN len \
|const U32 flags
Xdp |bool |amagic_applies |NN SV *sv \
|int method \
|int flags
Adp |SV * |amagic_call |NN SV *left \
|NN SV *right \
|int method \
|int dir
Adp |SV * |amagic_deref_call \
|NN SV *ref \
|int method
p |bool |amagic_is_enabled \
|int method
ETXip |void |append_utf8_from_native_byte \
|const U8 byte \
|NN U8 **dest
: FIXME - this is only called by pp_chown. They should be merged.
p |SSize_t|apply |I32 type \
|NN SV **mark \
|NN SV **sp
Apx |void |apply_attrs_string \
|NN const char *stashpv \
|NN CV *cv \
|NN const char *attrstr \
|STRLEN len
Adp |OP * |apply_builtin_cv_attributes \
|NN CV *cv \
|NULLOK OP *attrlist
CTp |void |atfork_lock
CTp |void |atfork_unlock
Cop |SV ** |av_arylen_p |NN AV *av
Adp |void |av_clear |NN AV *av
ARdip |Size_t |av_count |NN AV *av
Adeop |void |av_create_and_push \
|NN AV ** const avp \
|NN SV * const val
Adeop |SV ** |av_create_and_unshift_one \
|NN AV ** const avp \
|NN SV * const val
Adp |SV * |av_delete |NN AV *av \
|SSize_t key \
|I32 flags
Adp |void |av_dump |NULLOK AV *av
ARdp |bool |av_exists |NN AV *av \
|SSize_t key
Adp |void |av_extend |NN AV *av \
|SSize_t key
p |void |av_extend_guts |NULLOK AV *av \
|SSize_t key \
|NN SSize_t *maxp \
|NN SV ***allocp \
|NN SV ***arrayp
ARdp |SV ** |av_fetch |NN AV *av \
|SSize_t key \
|I32 lval
CRdip |SV ** |av_fetch_simple|NN AV *av \
|SSize_t key \
|I32 lval
Adp |void |av_fill |NN AV *av \
|SSize_t fill
Cop |IV * |av_iter_p |NN AV *av
ARdp |SSize_t|av_len |NN AV *av
ARdp |AV * |av_make |SSize_t size \
|NN SV **strp
CRdip |AV * |av_new_alloc |SSize_t size \
|bool zeroflag
p |SV * |av_nonelem |NN AV *av \
|SSize_t ix
Adp |SV * |av_pop |NN AV *av
Adp |void |av_push |NN AV *av \
|NN SV *val
Adip |void |av_push_simple |NN AV *av \
|NN SV *val
: Used in scope.c, and by Data::Alias
EXp |void |av_reify |NN AV *av
ipx |void |av_remove_offset \
|NN AV *av
ARdp |SV * |av_shift |NN AV *av
Adp |SV ** |av_store |NN AV *av \
|SSize_t key \
|NULLOK SV *val
Cdip |SV ** |av_store_simple|NN AV *av \
|SSize_t key \
|NULLOK SV *val
Adp |void |av_undef |NN AV *av
Adp |void |av_unshift |NN AV *av \
|SSize_t num
: Used in perly.y
Rp |OP * |bind_match |I32 type \
|NN OP *left \
|NN OP *right
: Used in perly.y
ARdp |OP * |block_end |I32 floor \
|NULLOK OP *seq
CRp |U8 |block_gimme
Adopx |void |blockhook_register \
|NN BHK *hk
: Used in perly.y
ARdp |int |block_start |int full
p |void |boot_core_builtin
: Only used in perl.c
p |void |boot_core_mro
: Used in perl.c
p |void |boot_core_PerlIO
: Used in perl.c
p |void |boot_core_UNIVERSAL
p |OP * |build_infix_plugin \
|NN OP *lhs \
|NN OP *rhs \
|NN void *tokendata
EXp |const char *|_byte_dump_string \
|NULLOK const U8 * const start \
|const STRLEN len \
|const bool format
Adp |int |bytes_cmp_utf8 |NN const U8 *b \
|STRLEN blen \
|NN const U8 *u \
|STRLEN ulen
Adp |U8 * |bytes_from_utf8|NN const U8 *s \
|NN STRLEN *lenp \
|NN bool *is_utf8p
Adp |U8 * |bytes_to_utf8 |NN const U8 *s \
|NN STRLEN *lenp
AOdp |SSize_t|call_argv |NN const char *sub_name \
|I32 flags \
|NN char **argv
: "Very" special - can't use the O flag for this one:
: (The rename from perl_atexit to Perl_call_atexit was in 864dbfa3ca8032ef)
Adp |void |call_atexit |ATEXIT_t fn \
|NULLOK void *ptr
Adp |const PERL_CONTEXT *|caller_cx \
|I32 level \
|NULLOK const PERL_CONTEXT **dbcxp
Cp |void |call_list |I32 oldscope \
|NN AV *paramList
AOdp |SSize_t|call_method |NN const char *methname \
|I32 flags
CTadop |Malloc_t|calloc |MEM_SIZE elements \
|MEM_SIZE size
AOdp |SSize_t|call_pv |NN const char *sub_name \
|I32 flags
AOdp |SSize_t|call_sv |NN SV *sv \
|I32 flags
: Used in several source files
Rp |bool |cando |Mode_t mode \
|bool effective \
|NN const Stat_t *statbufp
CRTp |I32 |cast_i32 |NV f
CRTp |IV |cast_iv |NV f
CRTp |U32 |cast_ulong |NV f
CRTp |UV |cast_uv |NV f
p |bool |check_utf8_print \
|NN const U8 *s \
|const STRLEN len
op |OP * |ck_entersub_args_core \
|NN OP *entersubop \
|NN GV *namegv \
|NN SV *protosv
Adp |OP * |ck_entersub_args_list \
|NN OP *entersubop
Adp |OP * |ck_entersub_args_proto \
|NN OP *entersubop \
|NN GV *namegv \
|NN SV *protosv
Adp |OP * |ck_entersub_args_proto_or_list \
|NN OP *entersubop \
|NN GV *namegv \
|NN SV *protosv
CPop |bool |ckwarn |U32 w
CPop |bool |ckwarn_d |U32 w
Adfpv |void |ck_warner |U32 err \
|NN const char *pat \
|...
Adfpv |void |ck_warner_d |U32 err \
|NN const char *pat \
|...
: Some static inline functions need predeclaration because they are used
: inside other static inline functions.
Cp |void |clear_defarray |NN AV *av \
|bool abandon
Cipx |void |clear_defarray_simple \
|NN AV *av
p |const COP *|closest_cop|NN const COP *cop \
|NULLOK const OP *o \
|NULLOK const OP *curop \
|bool opnext
Rp |OP * |cmpchain_extend|I32 type \
|NN OP *ch \
|NULLOK OP *right
Rp |OP * |cmpchain_finish|NN OP *ch
Rp |OP * |cmpchain_start |I32 type \
|NULLOK OP *left \
|NULLOK OP *right
ERTXp |const char *|cntrl_to_mnemonic \
|const U8 c
Adpx |const char *|cop_fetch_label \
|NN COP * const cop \
|NULLOK STRLEN *len \
|NULLOK U32 *flags
: Only used in op.c and the perl compiler
Adpx |void |cop_store_label|NN COP * const cop \
|NN const char *label \
|STRLEN len \
|U32 flags
: Used in pp.c
dp |SV * |core_prototype |NULLOK SV *sv \
|NN const char *name \
|const int code \
|NULLOK int * const opnum
: Used in gv.c
p |OP * |coresub_op |NN SV * const coreargssv \
|const int code \
|const int opnum
: Used in op.c and perl.c
px |void |create_eval_scope \
|NULLOK OP *retop \
|NN SV **sp \
|U32 flags
: croak()'s first parm can be NULL. Otherwise, mod_perl breaks.
Adfprv |void |croak |NULLOK const char *pat \
|...
Tfprv |void |croak_caller |NULLOK const char *pat \
|...
CTrs |void |croak_memory_wrap
Tpr |void |croak_no_mem
Tpr |void |croak_no_mem_ext \
|NN const char *context \
|STRLEN len
ATdpr |void |croak_no_modify
TXpr |void |croak_popstack
Adpr |void |croak_sv |NN SV *baseex
ATdpr |void |croak_xs_usage |NN const CV * const cv \
|NN const char * const params
CTp |Signal_t|csighandler1 |int sig
CTp |Signal_t|csighandler3 |int sig \
|NULLOK Siginfo_t *info \
|NULLOK void *uap
EXp |regexp_engine const *|current_re_engine
RXp |XOPRETANY|custom_op_get_field \
|NN const OP *o \
|const xop_flags_enum field
Adop |void |custom_op_register \
|NN Perl_ppaddr_t ppaddr \
|NN const XOP *xop
: Used in sv.c
EXpx |void |cv_ckproto_len_flags \
|NN const CV *cv \
|NULLOK const GV *gv \
|NULLOK const char *p \
|const STRLEN len \
|const U32 flags
Adp |CV * |cv_clone |NN CV *proto
p |CV * |cv_clone_into |NN CV *proto \
|NN CV *target
ARTdp |SV * |cv_const_sv |NULLOK const CV * const cv
RTp |SV * |cv_const_sv_or_av \
|NULLOK const CV * const cv
AMTdip |I32 * |CvDEPTH |NN const CV * const sv
dp |void |cv_forget_slab |NULLOK CV *cv
Adp |void |cv_get_call_checker \
|NN CV *cv \
|NN Perl_call_checker *ckfun_p \
|NN SV **ckobj_p
Adp |void |cv_get_call_checker_flags \
|NN CV *cv \
|U32 gflags \
|NN Perl_call_checker *ckfun_p \
|NN SV **ckobj_p \
|NN U32 *ckflags_p
AMdip |GV * |CvGV |NN CV *sv
Xop |GV * |cvgv_from_hek |NN CV *cv
Xp |void |cvgv_set |NN CV *cv \
|NULLOK GV *gv
Adp |SV * |cv_name |NN NOCHECK CV *cv \
|NULLOK SV *sv \
|U32 flags
Adp |void |cv_set_call_checker \
|NN CV *cv \
|NN Perl_call_checker ckfun \
|NN SV *ckobj
Adp |void |cv_set_call_checker_flags \
|NN CV *cv \
|NN Perl_call_checker ckfun \
|NN SV *ckobj \
|U32 ckflags
Xp |void |cvstash_set |NN CV *cv \
|NULLOK HV *stash
Adp |void |cv_undef |NN CV *cv
p |void |cv_undef_flags |NN CV *cv \
|U32 flags
Cp |void |cx_dump |NN PERL_CONTEXT *cx
: Used by CXINC, which appears to be in widespread use
CRp |I32 |cxinc
Adfpv |void |deb |NN const char *pat \
|...
Cdp |I32 |debop |NN const OP *o
Cdp |void |debprofdump
Adp |I32 |debstack
: Only used in dump.c
p |void |deb_stack_all
Cp |I32 |debstackptrs
p |void |debug_hash_seed|bool via_debug_h
Rp |SV * |defelem_target |NN SV *sv \
|NULLOK MAGIC *mg
: Used in op.c, perl.c
px |void |delete_eval_scope
ATdp |char * |delimcpy |NN char *to \
|NN const char *to_end \
|NN const char *from \
|NN const char *from_end \
|const int delim \
|NN I32 *retlen
ETXdp |char * |delimcpy_no_escape \
|NN char *to \
|NN const char *to_end \
|NN const char *from \
|NN const char *from_end \
|const int delim \
|NN I32 *retlen
Cp |void |despatch_signals