From 8e2ed19fa86ecd0e9ca643bf599ec72da376ab49 Mon Sep 17 00:00:00 2001 From: guenther Date: Sat, 25 Dec 2021 01:13:44 +0000 Subject: [PATCH] Update to reflect changes over the last six years --- lib/libc/include/README | 81 ++++++++++++++++++++++++----------------- 1 file changed, 47 insertions(+), 34 deletions(-) diff --git a/lib/libc/include/README b/lib/libc/include/README index 6410072c963..89acee491ee 100644 --- a/lib/libc/include/README +++ b/lib/libc/include/README @@ -28,6 +28,7 @@ CASE II: external symbols A) objects (variables) That's it, you're done. + B) plain C functions (not syscalls) 1) functions that are *not* called from inside libc @@ -42,6 +43,10 @@ CASE II: external symbols this line: PROTO_DEPRECATED(your_function_name); + Note: the "DEPRECATED" suffix is about a detail of + how the macros work and has nothing to do with whether the + function itself is a Good Thing vs deprecated. + 2) functions that are called from inside libc In the hidden/* version of the header where you declared @@ -56,42 +61,50 @@ CASE II: external symbols - otherwise, add: DEF_WEAK(your_function_name); - C) syscalls that require cancellation or other libpthread wrappers - You're done in libc, but go to libpthread and add the wrapper there. - D) syscalls that require libc wrappers for other reasons - First of all, make sure this really is the Right Thing. Talk - with kettenis, deraadt, miod, and guenther. - - 1) If the actual syscall doesn't have the same calling convention - as the C interface, then maybe it shouldn't be exported at - all and you should just have an ASM stub, like SYS___tfork - --> __tfork_thread() or SYS_break --> brk() and sbrk(). If - it _could_ be called from C, then give the syscall a name - different from the C API. Syscalls that fail this for - historical reasons (e.g., getlogin) are generated with - PSEUDO in libc/sys/Makefile.inc, so the ASM stub has a - leading underbar. Go read gen/getlogin.c for an example - of how to do this. - - 2) Otherwise, you're sane and have a syscall like sigaction() - which requires a wrapper but whose syscall API is the same - as the C API. Then: - - generate the ASM stub with HIDDEN in libc/sys/Makefile.inc - - in the proper hidden/*.h file add - PROTO_WRAP(your_function_name) - - the wrapper function should be defined in - libc/sys/w_your_function_name.c - which should define WRAP(your_function_name) and - follow it with DEF_WRAP(your_function_name). Look at - libc/sys/w_sigaction.c for an example. - - by default, libc code that calls your_function_name() - will get the real syscall and *not* the wrapper. libc - calls that needd to go through the wrapper should invoke - WRAP(your_function_name) - - E) syscalls that don't require any wrapping + C) syscalls that don't require any wrapping + In the hidden/* version of the header where you declared the function, add this line: PROTO_NORMAL(your_function_name); + Generate the stub by adding it to the ASM variable in + libc/sys/Makefile.inc + + + D) syscalls that require cancellation or similar wrappers that don't + change the function signature + + Generate the stub by adding it to the HIDDEN (*not* ASM!) + variable in libc/sys/Makefile.inc + + In the hidden/* version of the header where you declared the + function, add this line: + PROTO_WRAP(your_function_name); + + The wrapper function should be defined in + libc/sys/w_your_function_name.c + which should define WRAP(your_function_name) and follow it + with DEF_WRAP(your_function_name). Look at libc/sys/w_sigaction.c + for an example. + + By default, libc code that calls your_function_name() will get + the real syscall and *not* the wrapper. libc calls that need + to go through the wrapper should invoke WRAP(your_function_name) + + + E) syscalls that require libc wrappers for other reasons + First of all, make sure this really is the Right Thing. Talk + with kettenis, deraadt, millert, and guenther. + + If the actual syscall doesn't have the same calling convention + as the C interface, then maybe it shouldn't be exported at all + and you should just have an ASM stub, like SYS___tfork --> + __tfork_thread() or SYS_break --> brk() and sbrk(). If it + _could_ be called from C, then give the syscall a name different + from the C API. Syscalls that fail this for historical reasons + (e.g., exit == _exit(2)) are generated with PSEUDO/PSEUDO_NOERR + in libc/sys/Makefile.inc, so the ASM stub has a leading underbar. + Go read gen/getlogin.c rev 1.13 for an example of how to do + this, but don't pick this option, really. + -- 2.20.1