C libraries -- document per-libc interface/support

[heshamelmatary]

We might need a separate standalone chapter to document and move writings on what a C programmer should expect from a C library (and probably explicitly say this is how it's done in CheriBSD's C library, but not all of the other targets or C libraries yet, but that's how it should be):

Functions like the followings are examples:

• memcpy, memmove, strcpy, printf, snprintf, malloc, free, mmap, sbrk, etc

Otherwise someone who's developing non CheriBSD-specific projects might get misled thinking this is universally supported by any/all targets that support CHERI.

The current content (e.g., chapter 7) could either go under the CheriABI chapter, or we refactor to make sure to make it is non CheriBSD-specific

[rwatson]

A distinction I'm starting to tease out through some (but not yet complete) reworking is those things that are 'extensions to C' vs those things that are 'extensions to POSIX [etc]'. Of the above, most will be C extensions, and not POSIX extensions, and I think it will be pretty reasonable to start to expect that 'complete' implementations of CHERI C/C++ will implement the same format-string extensions, broad malloc() semantics, etc. regardless of 'platform'.

[heshamelmatary]

Makes sense. Some functions like malloc/free are mostly user-space, but they still call/assume an OS backend which could or couldn't be implemented, especially for different bare-metal. I've come up with the following categorisation when it comes a C libraries and CHERI:

1. C extensions that don't need any OS support (eg pure baremetal)
2. C extensions that do require an OS, syscalls, and/or backend (could or couldn't be implemented, in various ways)
3. POSIX extensions

Categorization of C, POSIX, and System Functions

Function	Category	Needs OS Syscall?	Notes
memcpy, memmove, memset	C Standard (Pure User-Space)	No	Pure memory manipulation
strlen, strcpy, strcmp, strfcap	C Standard (Pure User-Space)	No	String operations
qsort, bsearch	C Standard (Pure User-Space)	No	Algorithms
sprintf, snprintf	C Standard (Pure User-Space)	No	Formats to memory
malloc, free	C Standard (OS-Dependent)	Yes	Uses brk/mmap internally
printf, puts	C Standard (OS-Dependent)	Yes	Writes to stdout using syscalls
fprintf	C Standard (OS-Dependent)	Yes	Writes to file streams
fopen, fclose	C Standard (OS-Dependent)	Yes	File stream abstraction
fread, fwrite, fflush	C Standard (OS-Dependent)	Yes	Buffered file I/O
time, clock	C Standard / POSIX	Yes	Uses gettimeofday or similar
system()	C Standard (OS-Dependent)	Yes	Executes shell command via fork/exec
mmap, munmap	POSIX	Yes	Memory mapping
mprotect, msync	POSIX	Yes	Memory protection
open, read, write, close	POSIX	Yes	File descriptor I/O
fork, exec, waitpid	POSIX	Yes	Process control

---

[rwatson]

I wonder if including information on whether a system call is required might be "too much information" -- underlying implementations may make different design choices there. For example, in CHERI-enabled MMU-less Linux the system call might be a domain transition rather than a classical architectural system call. And on most POSIX OSes, C-level I/O routines may (but don't always) make system calls.

Overall a table followed by a series of sections for each API seems a good way forward. Some will be quite involved. Others less so.

I think the way forward might be for me to jot down a first cut in a pull request and for us to iterate on that draft.