NameDateSize

..07-Jun-202436

atfork.hH A D26-Aug-20151.9 KiB

cancel.hH A D04-Sep-20172.4 KiB

ctype_private.hH A D26-Aug-2015290

DETAILSH A D13-May-20195.3 KiB

localedef.hH A D22-May-20163.3 KiB

mpool.hH A D09-Sep-20154.5 KiB

namespace.hH A D30-Oct-20233.4 KiB

READMEH A D25-Dec-20214 KiB

thread_private.hH A D07-Jan-202111.7 KiB

README

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