I think we should expand the ioctl section a bit: I can do most of it in the kernel, but need help from glibc for a few things in which we need to agree on calling conventions. Here is what I'd suggest having in the document, feel free to take that into your document or edit as you wish:
== IOCTLs and Y2038 ==
Some Linux IOCTLs may be Y2038-unsafe, or use types defined by glibc that do not match the kernel internal types. Known important cases are:
An ioctl command number is defined using the _IOR/_IOW/_IORW macros by the kernel with a structure whose size changes based on glibc's time_t. The kernel can handle these transparently by implementing handlers for both command numbers with the correct structure format.
The binary ABI changes based on the glibc time_t type, but the command number does not change. In this case, the kernel header files defining the data structure will check the "__USE_TIME_BITS64" macro [do we need a new macro for the kernel headers?] to provide a different command number for the new data structure layout. glibc will define this macro at an appropriate location [where?] to make it visible before including kernel header files.
An ioctl command passes time information in a structure that is not based on time_t but another integer type that does not get changed. The kernel header files will provide both a new structure layout and command number when "__USE_TIME_BITS64" is set.
[I can find examples for ioctl commands in each of those categories if needed.]
Please do -- I understand the first two cases, but I am not sure I understand the third one.
== Socket options ==
Like ioctl(), setsockopt()/getsockopt() has a few interfaces that are passing time data:
SO_TIMESTAMP/SO_TIMESTAMPNS/SO_TIMESTAMPING: These enable the timestamping infrastructure for a socket, which will consecutively return data to user space using "cmsg" data on the socket. The kernel does not know the layout of 'struct timespec' and 'struct timeval' when filling the cmsg data, so we need to define new binary values for the three flags, which then get used if __USE_TIME_BITS64 is set.
IOW, introduce three new optname values (say 51, 52, and 53 as on my machine, /usr/include/asm-generic/socket.h stops at 50 right now) that would behave similar to options 29, 35 and 37 but would use Y2038-safe timestamps; and define option names SO_TIMESTAMP, SO_TIMESTAMPNS and SO_TIMESTAMPING to be either 29, 35 and 37 (the Y2038-unsafe options) or 51, 52 and 53 (the Y2038-safe ones) depending on __USE_TIME_BITS64. Right?
Another way of handling this would be to use the flags in sendmsg/recvmsg. Since cmsg is sent using these calls, at the time of call, sendmsg/recvmsg can indicate whether 64 bit time_t or 32 bit time_t is used. This will eliminate the need for new options and kernel need not depend on __USE_TIME_BITS64.
SO_RCVTIMEO/SO_SNTTIMEO: These pass a 'struct timeval' and a length. Assuming that the 'optlen' argument of the setsockopt syscall always matches the size of 'struct timeval', the kernel will be able to access the data in the same format that was passed by glibc. [alternatively, we could handle this the same way as SO_TIMESTAMP*, using new numbers for the flags].
I would prefer new numbers, that's more explicit and slightly safer, as if we rely on optlen, Murphy's Law will see to it that in practice it will have the wrong value.
But, if we are not using optlen here, then probably just using new numbers for timestamps also makes sense.
-Deepa