This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Document EXTERN_C macros
authorKarl Williamson <khw@cpan.org>
Tue, 18 Aug 2020 01:40:18 +0000 (19:40 -0600)
committerKarl Williamson <khw@cpan.org>
Sat, 22 Aug 2020 18:54:59 +0000 (12:54 -0600)
perl.h

diff --git a/perl.h b/perl.h
index c88e44e..4f1a9e3 100644 (file)
--- a/perl.h
+++ b/perl.h
 
 /* <--- here ends the logic shared by perl.h and makedef.pl */
 
+/*
+=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