posix: move doc

core/sys/posix/posix.odin

@@ -1,3 +1,47 @@
+/*
+Bindings for most POSIX APIs.
+
+APIs that have been left out are due to not being useful,
+being fully replaced (and better) by other Odin packages,
+or when one of the targets hasn't implemented the API or option.
+
+The struct fields that are cross-platform are documented with `[PSX]`.
+Accessing these fields on one target should be the same on others.
+Other fields are implementation specific.
+
+Most macros have been reimplemented in Odin with inlined functions.
+
+Unimplemented headers:
+- aio.h
+- complex.h | See `core:c/libc` and our own complex types
+- cpio.h
+- ctype.h | See `core:c/libc` for most of it
+- ndbm.h
+- fenv.h
+- float.h
+- fmtmsg.h
+- ftw.h
+- semaphore.h | See `core:sync`
+- inttypes.h | See `core:c`
+- iso646.h | Impossible
+- math.h | See `core:c/libc`
+- mqueue.h | Targets don't seem to have implemented it
+- regex.h | See `core:regex`
+- search.h | Not useful in Odin
+- spawn.h | Use `fork`, `execve`, etc.
+- stdarg.h | See `core:c/libc`
+- stdint.h | See `core:c`
+- stropts.h
+- syslog.h
+- pthread.h | Only the actual threads API is bound, see `core:sync` for synchronization primitives
+- string.h | Most of this is not useful in Odin, only a select few symbols are bound
+- tar.h
+- tgmath.h
+- trace.h
+- wchar.h
+- wctype.h
+
+*/
 package posix
 
 import "base:intrinsics"