[doc] System call wrappers not documented

[khwilliamson]

The system call wrappers are not documented: PerlLIO_*(), PerlSock_*(), PerlProc_*(), PerlMem(Shared|Parse|)*() (nothing uses the Parse variants), PerlSIO_*, PerlDir_*.

[Leont]

I'd argue for leaving PerlSIO_* private (I'd rather remove it entirely in due time). I'm not sure when one would need PerlMemParse_* so I can't judge that. The others actually make sense to me.

[khwilliamson]

Maybe we could just say for PerlSIO that they are deprecated

[Leont]

I suspect this is more a matter for perlclib than perlapi though.

[bulk88]

Under the original design concept of iperlsys.h all of these are supposed to be public API and all CPAN XS module are supposes to use these macros instead of using the all lower case generic ISO C/generic POSIX functions , that came with whatever the current permutation of host os/CC/libc implementation of the moment is being used.

"No" # define NO_XSLOCKS mode exists because the vast majority of CPAN XS modules and their authors either don't know about the "rules" in (dont know how else to describe it) perlclib and iperlsys.h, and don't use , won't use , doesnt effect them because their perl build is using the NOOP / disabled implementation of iperlsys.h.

So basically "No" # define NO_XSLOCKS mode is forcing iperlsys.h onto non compliant .xs files invisibly, but in a perfect unrealistic world,
"No" # define NO_XSLOCKS mode would never exist because all .xs files on CPAN and DarkPAN would be 100% perfectly portable because they are written to only use iperlsys.h calls and never ever any ISO C/Host os/libc function calls.

Iperlsys.h 's design purpose is to allow swapping out the .so/.dll file containing libc that libperl or /bin/perl is using at perl OS process startup, very very early in the process startup. The swapping out is done with array/vtables containing vanilla very portable ISO C function pointers with any ELF/PE/MachO/aout/etc OS specific API being uses.

Windows, Symbian, and Netware were/are the 3 OS that by default, all perl interp builds in their default P5P config, for those 3 OSs, use the indirection layer in iperlsys.h.

The consumers of iperlsys.h is Perl win32 psuedo fork, and libperl embedders that want libperl the shard lib, to be inside a SQL server process or inside an Apache or IIS http server process.

The last 3 use cases, those types of applications typically static link their own version of C standard library heavily customized and maintained by them, into their SQL/http server binaries, and never use whatever random version and build date, random implementation (muscl gnu microsoft newlib commercial Unix borland turbo C++, yes borland, last release of their non Microsoft LibC for windows was spring 2025) that appears on the disk of the end users system.

Highest low level use case of iperlsys.h is to make libperl.so.dll use the alternate memory pool alternate implementation of malloc/free that the root executable SQL or HTTP binary is using.

There is plenty of overlap, dual implementations of the same thing going, between util.c handy.h perl.c cross OS p5p maintained portability tools vs iperlsys.h and win32 specific iperlsys.h naming convention specific P5p maintained portability tools, eghhh.... let's call it "P5P maintained platform adaptation layer tools [for windows os]".

One hypothetical use case / example why Perl can't just use whatever ISO C macros/linker symbols that came with the CC, would be, if let's say some LibC for some commercial Unix OS had a ZERO optimizations, 1 byte at a time loop, memcpy() implementation, and Perl5 needs to replace that host os/host CC memcpy with a "proper" or "anything ANYTHING is faster than hot garbage" with a P5P maintained implementation of memcpy just for that particular OS/ or that particular C compiler toolchain.

In 2025 the above is sorta unrealistic since all commercial grade Foss and proprietary OSes that perl compiles on have full-featured freeware, not shareware but freeware, big difference, C compiler easily available for them.

In 1995 and even in 2005, other than Linux and BSD, all other Unix and non Unix oses that perl compiles on use C toolchains were paid licensed software. I can easily see "C compiler workstation edition" or "C compiler trial ware edition" have a 1 byte at a time for loop memcpy to force users to pay for "C compiler enterprise edition". A more realistic example would be if they want to compile their C code to use hardware/CPU native IEEE 754 math instead of a software emulated FP math. Trialware edition of the CC is not capable of emitting a binary using native hardware FP , because it's trial ware edition, no other reason.