1So you want to add an interface to libc... 2 3CASE I: internal symbols 4 5 A) used in a single file 6 Duh: use whatever name you want and make it static 7 8 B) used in multiple files 9 Give it a name in the implementation namespace (leading underbar) 10 and declare it in a __{BEGIN,END}_HIDDEN_DECLS block in a .h 11 file inside libc. If it's used in just a single subdir of 12 libc *and* that subdir has an appropriate .h file in it, then 13 declare it there. 14 Example: stdio/local.h. 15 Otherwise, declare it in one of the hidden/* files. 16 Example: _mktemp() in hidden/stdio.h 17 18CASE II: external symbols 19 20 First of all, add your symbol to Symbols.list. MD symbols go in 21 arch/*/Symbols.list (shock, I know) 22 23 Declare your function in the appropriate header. It almost certainly 24 should be in a public header installed under /usr/include/. Exceptions 25 are symbols that are just shared between libc and libpthread/csu/ld.so 26 which are only declared in libc/include/* or just in each .c file. 27 28 A) objects (variables) 29 That's it, you're done. 30 31 32 B) plain C functions (not syscalls) 33 1) functions that are *not* called from inside libc 34 35 If this function is specified in the ISO C standard or its 36 name begins with an underbar, then in the hidden/* version 37 of the header where you declared the function, add this line: 38 PROTO_STD_DEPRECATED(your_function_name); 39 40 Otherwise, this is *not* a function specified in the ISO C 41 standard and its name begins with a letter. In the hidden/* 42 version of the header where you declared the function, add 43 this line: 44 PROTO_DEPRECATED(your_function_name); 45 46 Note: the "DEPRECATED" suffix is about a detail of 47 how the macros work and has nothing to do with whether the 48 function itself is a Good Thing vs deprecated. 49 50 2) functions that are called from inside libc 51 52 In the hidden/* version of the header where you declared 53 the function, add this line: 54 PROTO_NORMAL(your_function_name); 55 56 Then, in the .c file(s) where the function is defined: 57 - if the function is specified in the ISO C standard or 58 its name begins with an underbar, add 59 DEF_STRONG(your_function_name); 60 61 - otherwise, add: 62 DEF_WEAK(your_function_name); 63 64 65 C) syscalls that don't require any wrapping 66 67 In the hidden/* version of the header where you declared the 68 function, add this line: 69 PROTO_NORMAL(your_function_name); 70 71 Generate the stub by adding it to the ASM variable in 72 libc/sys/Makefile.inc 73 74 75 D) syscalls that require cancellation or similar wrappers that don't 76 change the function signature 77 78 Generate the stub by adding it to the HIDDEN (*not* ASM!) 79 variable in libc/sys/Makefile.inc 80 81 In the hidden/* version of the header where you declared the 82 function, add this line: 83 PROTO_WRAP(your_function_name); 84 85 The wrapper function should be defined in 86 libc/sys/w_your_function_name.c 87 which should define WRAP(your_function_name) and follow it 88 with DEF_WRAP(your_function_name). Look at libc/sys/w_sigaction.c 89 for an example. 90 91 By default, libc code that calls your_function_name() will get 92 the real syscall and *not* the wrapper. libc calls that need 93 to go through the wrapper should invoke WRAP(your_function_name) 94 95 96 E) syscalls that require libc wrappers for other reasons 97 First of all, make sure this really is the Right Thing. Talk 98 with kettenis, deraadt, millert, and guenther. 99 100 If the actual syscall doesn't have the same calling convention 101 as the C interface, then maybe it shouldn't be exported at all 102 and you should just have an ASM stub, like SYS___tfork --> 103 __tfork_thread() or SYS_break --> brk() and sbrk(). If it 104 _could_ be called from C, then give the syscall a name different 105 from the C API. Syscalls that fail this for historical reasons 106 (e.g., exit == _exit(2)) are generated with PSEUDO/PSEUDO_NOERR 107 in libc/sys/Makefile.inc, so the ASM stub has a leading underbar. 108 Go read gen/getlogin.c rev 1.13 for an example of how to do 109 this, but don't pick this option, really. 110 111