ioctl: Document in Haiku book and in comments

- Convert libroot from a page to a group, so that it can list the
  included file and functions in the generated book (like the kits)
- Add unistd.dox and move the relevant part of ioctl details there
- Make sure to use C89-compatible comments only in POSIX headers

Change-Id: I8f0412e4c75de6f48018a0436909f8b0076342a4
Reviewed-on: https://review.haiku-os.org/c/haiku/+/6369
Reviewed-by: Adrien Destugues <[email protected]>
Haiku-Format: Haiku-format Bot <[email protected]>

headers/posix/unistd.h

@@ -362,6 +362,17 @@ extern int		symlinkat(const char *toPath, int fd, const char *symlinkPath);
 extern int      ftruncate(int fd, off_t newSize);
 extern int      truncate(const char *path, off_t newSize);
 
+/* We want the 3rd and 4th arguments to ioctl to be optional, but we can't use varargs because
+ * then we have no way to know if the optional arguments are present, and calling va_next is
+ * undefined behavior (it may or may not work depending on the calling convention).
+ *
+ * In C++, we implement ioctl using default function arguments, but in C this isn't possible.
+ * So, the C implementation is done as vararg macro that use preprocessor magic to call the
+ * 4 argument function and fill in the omitted arguments.
+ *
+ * The legacy ioctl function in C with vararg arguments is still provided for ABI compatibility
+ * with existing applications, but should not be used anymore by newly compiled code.
+ */
 extern int		__ioctl(int fd, ulong cmd, void* argument, size_t size);
 #ifndef __cplusplus
 extern int		ioctl(int fd, unsigned long op, ...);