Give clear directions on how to declare, PROTO_*() and DEF_*() new symbols

prodded by deraadt@

1 files changed, 97 insertions, 0 deletions

diff --git a/src/lib/libc/include/README b/src/lib/libc/include/README
new file mode 100644
index 0000000000..6410072c96
--- /dev/null
+++ b/src/lib/libc/include/README
@@ -0,0 +1,97 @@
+So you want to add an interface to libc...
+
+CASE I: internal symbols
+
+  A) used in a single file
+     Duh: use whatever name you want and make it static
+
+  B) used in multiple files
+     Give it a name in the implementation namespace (leading underbar)
+     and declare it in a __{BEGIN,END}_HIDDEN_DECLS block in a .h
+     file inside libc.  If it's used in just a single subdir of
+     libc *and* that subdir has an appropriate .h file in it, then
+     declare it there.
+     Example: stdio/local.h.
+     Otherwise, declare it in one of the hidden/* files.
+     Example: _mktemp() in hidden/stdio.h
+
+CASE II: external symbols
+
+  First of all, add your symbol to Symbols.list.  MD symbols go in
+  arch/*/Symbols.list (shock, I know)
+
+  Declare your function in the appropriate header.  It almost certainly
+  should be in a public header installed under /usr/include/.  Exceptions
+  are symbols that are just shared between libc and libpthread/csu/ld.so
+  which are only declared in libc/include/* or just in each .c file.
+
+  A) objects (variables)
+     That's it, you're done.
+
+  B) plain C functions (not syscalls)
+     1) functions that are *not* called from inside libc
+
+        If this function is specified in the ISO C standard or its
+        name begins with an underbar, then in the hidden/* version
+        of the header where you declared the function, add this line:
+                PROTO_STD_DEPRECATED(your_function_name);
+
+        Otherwise, this is *not* a function specified in the ISO C
+        standard and its name begins with a letter.  In the hidden/*
+        version of the header where you declared the function, add
+        this line:
+                PROTO_DEPRECATED(your_function_name);
+
+     2) functions that are called from inside libc
+
+        In the hidden/* version of the header where you declared
+        the function, add this line:
+                PROTO_NORMAL(your_function_name);
+
+        Then, in the .c file(s) where the function is defined:
+         - if the function is specified in the ISO C standard or
+           its name begins with an underbar, add
+                DEF_STRONG(your_function_name);
+
+         - 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
+     In the hidden/* version of the header where you declared the
+     function, add this line:
+        PROTO_NORMAL(your_function_name);
+