Changelog since dratf v2: - Remove struct/union keywords from list of type names (and sort) - wfix - ffix - Add all the headers that define each type - Specify the layout of the list in a comment - Add size_t type (I had to do it :-) Signed-off-by: Alejandro Colomar <colomar.6.4.3@xxxxxxxxx> --- Hi Michael, On 9/14/20 9:33 PM, Michael Kerrisk (man-pages) wrote: > Hi Alex, > > On 9/14/20 5:52 PM, Alejandro Colomar wrote: >> Hi Michael, > As I think about more, maybe the list of type keywords could even > omit 'struct' and 'union', since the struct/union definition will be shown > in the following text. Your thoughts? Yes, it looks nicer (the eye doesn't need to move to the right at each struct/union) so it is visually easier to find the types. >>> s/It/According to POSIX, it/ >> As this type is POSIX-only, I thought it was redundant. Don't you? > I think it's clearer to be explicit. Otherwise, the reader has to do > some deductive work. > Agreed. >> If I added every header that has a line like that, the lists of headers >> would be much bigger for most of the types. It could be good, but I >> don't know if we should do it. Maybe we should limit to the headers >> that are required by CXX and the ones where the POSIX docs actually >> document the type (this header doesn't define it, and instead it defers >> to <sys//types.h> for example). >> >> Your thoughts? > I think the list would not be so long. Maybe two headers sometimes, > occasionally three, but I doubt more. At least right now, I think we > should do it; I may yet be shown the error of my ways :-). The list is rather long, but now I don't deel it's too much, and it has some value. I'd keep all of them. See my comment (Layout) in the page, and feel free to add to/modify it. > Good progress so far. Thanks, Alex! > > Cheers, > > Michael Thank you too, Michael! Cheers, Alex man3/sigval.3 | 1 + man3/ssize_t.3 | 1 + man3/suseconds_t.3 | 1 + man3/time_t.3 | 1 + man3/timer_t.3 | 1 + man3/timespec.3 | 1 + man3/timeval.3 | 1 + man7/system_data_types.7 | 349 +++++++++++++++++++++++++++++++++++++++ 8 files changed, 356 insertions(+) create mode 100644 man3/sigval.3 create mode 100644 man3/ssize_t.3 create mode 100644 man3/suseconds_t.3 create mode 100644 man3/time_t.3 create mode 100644 man3/timer_t.3 create mode 100644 man3/timespec.3 create mode 100644 man3/timeval.3 create mode 100644 man7/system_data_types.7 diff --git a/man3/sigval.3 b/man3/sigval.3 new file mode 100644 index 000000000..db50c0f09 --- /dev/null +++ b/man3/sigval.3 @@ -0,0 +1 @@ +.so man7/system_data_types.7 diff --git a/man3/ssize_t.3 b/man3/ssize_t.3 new file mode 100644 index 000000000..db50c0f09 --- /dev/null +++ b/man3/ssize_t.3 @@ -0,0 +1 @@ +.so man7/system_data_types.7 diff --git a/man3/suseconds_t.3 b/man3/suseconds_t.3 new file mode 100644 index 000000000..db50c0f09 --- /dev/null +++ b/man3/suseconds_t.3 @@ -0,0 +1 @@ +.so man7/system_data_types.7 diff --git a/man3/time_t.3 b/man3/time_t.3 new file mode 100644 index 000000000..db50c0f09 --- /dev/null +++ b/man3/time_t.3 @@ -0,0 +1 @@ +.so man7/system_data_types.7 diff --git a/man3/timer_t.3 b/man3/timer_t.3 new file mode 100644 index 000000000..db50c0f09 --- /dev/null +++ b/man3/timer_t.3 @@ -0,0 +1 @@ +.so man7/system_data_types.7 diff --git a/man3/timespec.3 b/man3/timespec.3 new file mode 100644 index 000000000..db50c0f09 --- /dev/null +++ b/man3/timespec.3 @@ -0,0 +1 @@ +.so man7/system_data_types.7 diff --git a/man3/timeval.3 b/man3/timeval.3 new file mode 100644 index 000000000..db50c0f09 --- /dev/null +++ b/man3/timeval.3 @@ -0,0 +1 @@ +.so man7/system_data_types.7 diff --git a/man7/system_data_types.7 b/man7/system_data_types.7 new file mode 100644 index 000000000..dd93c6746 --- /dev/null +++ b/man7/system_data_types.7 @@ -0,0 +1,349 @@ +.\" Copyright (c) 2020 by Alejandro Colomar <colomar.6.4.3@xxxxxxxxx> +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" +.TH SYSTEM_DATA_TYPES 7 2020-09-13 "Linux" "Linux Programmer's Manual" +.SH NAME +system_data_types \- overview of system data types +.SH DESCRIPTION +.\" TODO: +.\" * Add types +.\" * Check specific POSIX "Conforming to" versions +.\" * Correctly highlight function names and similar (see timer_t) +.\" * Curate "See also" +.\" Layout: +.\" A list of type names (the struct/union keyword will be omitted). +.\" Each entry will have the following parts: +.\" * Include +.\" The headers will be in the following order: +.\" 1) The header(s) that shall define the type +.\" according to the C standard, +.\" in alphabetical order. +.\" 2) The header that shall define the type +.\" according to POSIX. +.\" 3) All other headers that shall define the type +.\" as described in the previous header +.\" according to POSIX, +.\" in alphabetical order. +.\" 4) All other headers that define the type +.\" that are Linux specific, +.\" in alphabetical order. +.\" +.\" * Definition (no "Definition" header) +.\" Only struct/union types will have definition; +.\" typedefs will remain opaque. +.\" +.\" * Description (no "Description" header) +.\" A few lines describing the type. +.\" +.\" * Conforming to +.\" example: CXY and later; POSIX.1-XXXX and later +.\" Forget about pre-C99 C standards (i.e., C89/C90) +.\" +.\" * Notes (optional) +.\" +.\" * See also +.TP +.I sigval +.IP +Include: +.I <signal.h> +.IP +.EX +union sigval { + int sigval_int; /* Integer value */ + void *sigval_ptr; /* Pointer value */ +}; +.EE +.IP +Data passed with a signal. +.IP +Conforming to: POSIX.1-xxxx and later. +.IP +See also: +.BR rt_sigqueueinfo (2), +.BR sigaction (2), +.BR mq_notify (3), +.BR pthread_sigqueue (3), +.BR sigqueue (3), +.BR sigevent (7) +.TP +.I ssize_t +.IP +Include: +.I <sys/types.h> +or +.I <aio.h> +or +.I <limits.h> +or +.I <monetary.h> +or +.I <mqueue.h> +or +.I <regex.h> +or +.I <stdio.h> +or +.I <sys/msg.h> +or +.I <sys/socket.h> +or +.I <sys/uio.h> +or +.I <unistd.h> +.IP +Used for a count of bytes or an error indication. +According to POSIX, it shall be a signed integer type +capable of storing values at least in the range [-1, +.BR SSIZE_MAX ]. +.IP +Conforming to: POSIX.1-xxxx and later. +.IP +See also: +.BR TODO (XXX), +.BR TODO (may be too large) +.TP +.I suseconds_t +.IP +Include: +.I <sys/types.h> +or +.I <sys/select.h> +or +.I <sys/time.h> +or +.I <unistd.h> +.IP +Used for time in microseconds. +According to POSIX, it shall be a signed integer type +capable of storing values at least in the range [-1, 1000000]. +.IP +Conforming to: POSIX.1-xxxx and later. +.IP +See also: +.\".BR getitimer (2), +.\".BR gettimeofday (2), +.\".BR select (2), +.\".BR adjtime (3), +.\".BR ntp_gettime (3), +.\".BR timeval (3), +.\".BR timeradd (3) +.IP +See also the +.B timeval +structure in this page. +.TP +.I time_t +.IP +Include: +.I <time.h> +or +.I <sys/types.h> +or +.I <sched.h> +or +.I <sys/msg.h> +or +.I <sys/select.h> +or +.I <sys/sem.h> +or +.I <sys/shm.h> +or +.I <sys/stat.h> +or +.I <sys/time.h> +or +.I <utime.h> +.IP +Used for time in seconds. +According to POSIX, it shall be an integer type. +.IP +Conforming to: C99 and later; POSIX.1-xxxx and later. +.IP +See also: +.BR clock_getres (2), +.BR clock_nanosleep (2), +.BR getitimer (2), +.BR gettimeofday (2), +.BR io_getevents (2), +.BR keyctl (2), +.BR msgctl (2), +.BR msgop (2), +.BR nanosleep (2), +.BR sched_rr_get_interval (2), +.BR select (2), +.BR semctl (2), +.BR shmctl (2), +.BR stat (2), +.BR stime (2), +.BR time (2), +.BR timerfd_create (2), +.BR timer_settime (2), +.BR times (2), +.BR utime (2), +.BR utimensat (2), +.BR adjtime (3), +.BR ctime (3), +.BR difftime (3), +.BR ftime (3), +.BR mq_receive (3), +.BR mq_send (3), +.BR newlocale (3), +.BR ntp_gettime (3), +.BR pthread_cleanup_push (3), +.BR pthread_tryjoin_np (3), +.BR rtime (3), +.BR sem_wait (3), +.BR strcat (3), +.BR strftime (3), +.BR timegm (3), +.BR timeradd (3) +.TP +.I timer_t +.IP +Include: +.I <sys/types.h> +or +.I <time.h> +.IP +Used for timer ID returned by +.BR timer_create (2). +There are no defined comparison or assignment operators for this type. +.IP +Conforming to: POSIX.1-xxxx and later. +.IP +See also: +.BR timer_create (2), +.BR timer_delete (2), +.BR timer_getoverrun (2), +.BR timer_settime (2) +.TP +.I timespec +.IP +Include: +.I <time.h> +or +.I <aio.h> +or +.I <mqueue.h> +or +.I <pthread.h> +or +.I <sched.h> +or +.I <semaphore.h> +or +.I <signal.h> +or +.I <sys/select.h> +or +.I <sys/stat.h> +or +.I <trace.h> +.IP +.EX +struct timespec { + time_t tv_sec; /* Seconds */ + long tv_nsec; /* Nanoseconds */ +}; +.EE +.IP +Describes times in seconds and nanoseconds. +.IP +Conforming to: C11 and later; POSIX.1-xxxx and later. +.IP +See also: +.\".BR clock_getres (2), +.BR clock_gettime (2), +.BR clock_nanosleep (2), +.\".BR futex (2), +.\".BR io_getevents (2), +.BR nanosleep (2), +.\".BR poll (2), +.\".BR recvmmsg (2), +.\".BR sched_rr_get_interval (2), +.\".BR select (2), +.\".BR semop (2), +.\".BR sigwaitinfo (2), +.\".BR stat (2), +.\".BR timerfd_create (2), +.BR timerfd_gettime (2), +.BR timer_gettime (2) +.\".BR timer_settime (2), +.\".BR utimensat (2), +.\".BR aio_suspend (3), +.\".BR clock_getcpuclockid (3), +.\".BR getaddrinfo_a (3), +.\".BR mq_receive (3), +.\".BR mq_send (3), +.\".BR pthread_getcpuclockid (3), +.\".BR pthread_tryjoin_np (3), +.\".BR sem_wait (3), +.\".BR socket (7) +.TP +.I timeval +.IP +Include: +.I <sys/time.h> +or +.I <sys/resource.h> +or +.I <sys/select.h> +or +.I <utmpx.h> +.IP +.EX +struct timeval { + time_t tv_sec; /* Seconds */ + suseconds_t tv_usec; /* Microseconds */ +}; +.EE +.IP +Describes times in seconds and microseconds. +.IP +Conforming to: POSIX.1-xxxx and later. +.IP +See also: +.BR adjtimex (2), +.BR futimesat (2), +.BR getitimer (2), +.BR getpriority (2), +.BR getrusage (2), +.BR gettimeofday (2), +.BR select (2), +.BR syscall (2), +.BR syscalls (2), +.BR utime (2), +.BR wait4 (2), +.BR adjtime (3), +.BR futimes (3), +.BR ntp_gettime (3), +.BR rpc (3), +.BR rtime (3), +.BR timeradd (3), +.BR utmp (5), +.BR packet (7), +.BR socket (7) -- 2.28.0