man7/system_data_types.7

   1 .\" Copyright (c) 2020 by Alejandro Colomar <alx@kernel.org>
   2 .\" and Copyright (c) 2020 by Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .\"
   7 .TH system_data_types 7 (date) "Linux man-pages (unreleased)"
   8 .SH NAME
   9 system_data_types \- overview of system data types
  10 .SH DESCRIPTION
  11 .\" Layout:
  12 .\"     A list of type names (the struct/union keyword will be omitted).
  13 .\"     Each entry will have the following parts:
  14 .\"             * Include (see NOTES)
  15 .\"
  16 .\"             * Definition (no "Definition" header)
  17 .\"                     Only struct/union types will have definition;
  18 .\"                     typedefs will remain opaque.
  19 .\"
  20 .\"             * Description (no "Description" header)
  21 .\"                     A few lines describing the type.
  22 .\"
  23 .\"             * Versions (optional)
  24 .\"
  25 .\"             * Conforming to (see NOTES)
  26 .\"                     Format: CXY and later; POSIX.1-XXXX and later.
  27 .\"
  28 .\"             * Notes (optional)
  29 .\"
  30 .\"             * Bugs (if any)
  31 .\"
  32 .\"             * See also
  33 .\"------------------------------------- aiocb ------------------------/
  34 .\"------------------------------------- blkcnt_t ---------------------/
  35 .\"------------------------------------- blksize_t --------------------/
  36 .\"------------------------------------- cc_t -------------------------/
  37 .\"------------------------------------- clock_t ----------------------/
  38 .\"------------------------------------- clockid_t --------------------/
  39 .\"------------------------------------- dev_t ------------------------/
  40 .\"------------------------------------- div_t ------------------------/
  41 .\"------------------------------------- double_t ---------------------/
  42 .\"------------------------------------- fd_set -----------------------/
  43 .\"------------------------------------- fenv_t -----------------------/
  44 .\"------------------------------------- fexcept_t --------------------/
  45 .\"------------------------------------- FILE -------------------------/
  46 .\"------------------------------------- float_t ----------------------/
  47 .\"------------------------------------- gid_t ------------------------/
  48 .\"------------------------------------- id_t -------------------------/
  49 .\"------------------------------------- imaxdiv_t --------------------/
  50 .\"------------------------------------- intmax_t ---------------------/
  51 .\"------------------------------------- intN_t -----------------------/
  52 .\"------------------------------------- intptr_t ---------------------/
  53 .\"------------------------------------- lconv ------------------------/
  54 .\"------------------------------------- ldiv_t -----------------------/
  55 .\"------------------------------------- lldiv_t ----------------------/
  56 .\"------------------------------------- mode_t -----------------------/
  57 .\"------------------------------------- off64_t ----------------------/
  58 .\"------------------------------------- off_t ------------------------/
  59 .\"------------------------------------- pid_t ------------------------/
  60 .\"------------------------------------- ptrdiff_t --------------------/
  61 .\"------------------------------------- regex_t ----------------------/
  62 .\"------------------------------------- regmatch_t -------------------/
  63 .\"------------------------------------- regoff_t ---------------------/
  64 .\"------------------------------------- sigevent ---------------------/
  65 .\"------------------------------------- siginfo_t --------------------/
  66 .TP
  67 .I siginfo_t
  68 .RS
  69 .IR Include :
  70 .IR <signal.h> .
  71 Alternatively,
  72 .IR <sys/wait.h> .
  73 .PP
  74 .EX
  75 typedef struct {
  76     int      si_signo;  /* Signal number */
  77     int      si_code;   /* Signal code */
  78     pid_t    si_pid;    /* Sending process ID */
  79     uid_t    si_uid;    /* Real user ID of sending process */
  80     void    *si_addr;   /* Memory location which caused fault */
  81     int      si_status; /* Exit value or signal */
  82     union sigval si_value;  /* Signal value */
  83 } siginfo_t;
  84 .EE
  85 .PP
  86 Information associated with a signal.
  87 For further details on this structure
  88 (including additional, Linux-specific fields), see
  89 .BR sigaction (2).
  90 .PP
  91 .IR "Conforming to" :
  92 POSIX.1-2001 and later.
  93 .PP
  94 .IR "See also" :
  95 .BR pidfd_send_signal (2),
  96 .BR rt_sigqueueinfo (2),
  97 .BR sigaction (2),
  98 .BR sigwaitinfo (2),
  99 .BR psiginfo (3)
 100 .RE
 101 .\"------------------------------------- sigset_t ---------------------/
 102 .TP
 103 .I sigset_t
 104 .RS
 105 .IR Include :
 106 .IR <signal.h> .
 107 Alternatively,
 108 .IR <spawn.h> ,
 109 or
 110 .IR <sys/select.h> .
 111 .PP
 112 This is a type that represents a set of signals.
 113 According to POSIX, this shall be an integer or structure type.
 114 .PP
 115 .IR "Conforming to" :
 116 POSIX.1-2001 and later.
 117 .PP
 118 .IR "See also" :
 119 .BR epoll_pwait (2),
 120 .BR ppoll (2),
 121 .BR pselect (2),
 122 .BR sigaction (2),
 123 .BR signalfd (2),
 124 .BR sigpending (2),
 125 .BR sigprocmask (2),
 126 .BR sigsuspend (2),
 127 .BR sigwaitinfo (2),
 128 .BR signal (7)
 129 .RE
 130 .\"------------------------------------- sigval -----------------------/
 131 .\"------------------------------------- size_t -----------------------/
 132 .\"------------------------------------- sockaddr ---------------------/
 133 .\"------------------------------------- socklen_t --------------------/
 134 .\"------------------------------------- ssize_t ----------------------/
 135 .\"------------------------------------- stat -------------------------/
 136 .\"------------------------------------- suseconds_t ------------------/
 137 .\"------------------------------------- time_t -----------------------/
 138 .\"------------------------------------- timer_t ----------------------/
 139 .\"------------------------------------- timespec ---------------------/
 140 .\"------------------------------------- timeval ----------------------/
 141 .\"------------------------------------- uid_t ----------------------/
 142 .\"------------------------------------- uintmax_t --------------------/
 143 .\"------------------------------------- uintN_t ----------------------/
 144 .\"------------------------------------- uintptr_t --------------------/
 145 .\"------------------------------------- useconds_t -------------------/
 146 .\"------------------------------------- va_list ----------------------/
 147 .\"------------------------------------- void * -----------------------/
 148 .\"--------------------------------------------------------------------/
 149 .SH NOTES
 150 The structures described in this manual page shall contain,
 151 at least, the members shown in their definition, in no particular order.
 152 .PP
 153 Most of the integer types described in this page don't have
 154 a corresponding length modifier for the
 155 .BR printf (3)
 156 and the
 157 .BR scanf (3)
 158 families of functions.
 159 To print a value of an integer type that doesn't have a length modifier,
 160 it should be converted to
 161 .I intmax_t
 162 or
 163 .I uintmax_t
 164 by an explicit cast.
 165 To scan into a variable of an integer type
 166 that doesn't have a length modifier,
 167 an intermediate temporary variable of type
 168 .I intmax_t
 169 or
 170 .I uintmax_t
 171 should be used.
 172 When copying from the temporary variable to the destination variable,
 173 the value could overflow.
 174 If the type has upper and lower limits,
 175 the user should check that the value is within those limits,
 176 before actually copying the value.
 177 The example below shows how these conversions should be done.
 178 .SS Conventions used in this page
 179 In "Conforming to" we only concern ourselves with
 180 C99 and later and POSIX.1-2001 and later.
 181 Some types may be specified in earlier versions of one of these standards,
 182 but in the interests of simplicity we omit details from earlier standards.
 183 .PP
 184 In "Include", we first note the "primary" header(s) that
 185 define the type according to either the C or POSIX.1 standards.
 186 Under "Alternatively", we note additional headers that
 187 the standards specify shall define the type.
 188 .SH EXAMPLES
 189 The program shown below scans from a string and prints a value stored in
 190 a variable of an integer type that doesn't have a length modifier.
 191 The appropriate conversions from and to
 192 .IR intmax_t ,
 193 and the appropriate range checks,
 194 are used as explained in the notes section above.
 195 .PP
 196 .EX
 197 #include <stdint.h>
 198 #include <stdio.h>
 199 #include <stdlib.h>
 200 #include <sys/types.h>
 201 \&
 202 int
 203 main (void)
 204 {
 205     static const char *const str = "500000 us in half a second";
 206     suseconds_t us;
 207     intmax_t    tmp;
 208 \&
 209     /* Scan the number from the string into the temporary variable. */
 210 \&
 211     sscanf(str, "%jd", &tmp);
 212 \&
 213     /* Check that the value is within the valid range of suseconds_t. */
 214 \&
 215     if (tmp < \-1 || tmp > 1000000) {
 216         fprintf(stderr, "Scanned value outside valid range!\en");
 217         exit(EXIT_FAILURE);
 218     }
 219 \&
 220     /* Copy the value to the suseconds_t variable \[aq]us\[aq]. */
 221 \&
 222     us = tmp;
 223 \&
 224     /* Even though suseconds_t can hold the value \-1, this isn\[aq]t
 225        a sensible number of microseconds. */
 226 \&
 227     if (us < 0) {
 228         fprintf(stderr, "Scanned value shouldn\[aq]t be negative!\en");
 229         exit(EXIT_FAILURE);
 230     }
 231 \&
 232     /* Print the value. */
 233 \&
 234     printf("There are %jd microseconds in half a second.\en",
 235             (intmax_t) us);
 236 \&
 237     exit(EXIT_SUCCESS);
 238 }
 239 .EE
 240 .SH SEE ALSO
 241 .BR feature_test_macros (7),
 242 .BR standards (7)