man7/system_data_types.7

   1 .\" Copyright (c) 2020 by Alejandro Colomar <colomar.6.4.3@gmail.com>
   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 2021-03-22 "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 .TP
  66 .I sigevent
  67 .RS
  68 .IR Include :
  69 .IR <signal.h> .
  70 Alternatively,
  71 .IR <aio.h> ,
  72 .IR <mqueue.h> ,
  73 or
  74 .IR <time.h> .
  75 .PP
  76 .EX
  77 struct sigevent {
  78     int             sigev_notify; /* Notification type */
  79     int             sigev_signo;  /* Signal number */
  80     union sigval    sigev_value;  /* Signal value */
  81     void          (*sigev_notify_function)(union sigval);
  82                                   /* Notification function */
  83     pthread_attr_t *sigev_notify_attributes;
  84                                   /* Notification attributes */
  85 };
  86 .EE
  87 .PP
  88 For further details about this type, see
  89 .BR sigevent (7).
  90 .PP
  91 .IR Versions :
  92 .I <aio.h>
  93 and
  94 .I <time.h>
  95 define
  96 .I sigevent
  97 since POSIX.1-2008.
  98 .PP
  99 .IR "Conforming to" :
 100 POSIX.1-2001 and later.
 101 .PP
 102 .IR "See also" :
 103 .BR timer_create (2),
 104 .BR getaddrinfo_a (3),
 105 .BR lio_listio (3),
 106 .BR mq_notify (3)
 107 .PP
 108 See also the
 109 .I aiocb
 110 structure in this page.
 111 .RE
 112 .\"------------------------------------- siginfo_t --------------------/
 113 .TP
 114 .I siginfo_t
 115 .RS
 116 .IR Include :
 117 .IR <signal.h> .
 118 Alternatively,
 119 .IR <sys/wait.h> .
 120 .PP
 121 .EX
 122 typedef struct {
 123     int      si_signo;  /* Signal number */
 124     int      si_code;   /* Signal code */
 125     pid_t    si_pid;    /* Sending process ID */
 126     uid_t    si_uid;    /* Real user ID of sending process */
 127     void    *si_addr;   /* Address of faulting instruction */
 128     int      si_status; /* Exit value or signal */
 129     union sigval si_value;  /* Signal value */
 130 } siginfo_t;
 131 .EE
 132 .PP
 133 Information associated with a signal.
 134 For further details on this structure
 135 (including additional, Linux-specific fields), see
 136 .BR sigaction (2).
 137 .PP
 138 .IR "Conforming to" :
 139 POSIX.1-2001 and later.
 140 .PP
 141 .IR "See also" :
 142 .BR pidfd_send_signal (2),
 143 .BR rt_sigqueueinfo (2),
 144 .BR sigaction (2),
 145 .BR sigwaitinfo (2),
 146 .BR psiginfo (3)
 147 .RE
 148 .\"------------------------------------- sigset_t ---------------------/
 149 .TP
 150 .I sigset_t
 151 .RS
 152 .IR Include :
 153 .IR <signal.h> .
 154 Alternatively,
 155 .IR <spawn.h> ,
 156 or
 157 .IR <sys/select.h> .
 158 .PP
 159 This is a type that represents a set of signals.
 160 According to POSIX, this shall be an integer or structure type.
 161 .PP
 162 .IR "Conforming to" :
 163 POSIX.1-2001 and later.
 164 .PP
 165 .IR "See also" :
 166 .BR epoll_pwait (2),
 167 .BR ppoll (2),
 168 .BR pselect (2),
 169 .BR sigaction (2),
 170 .BR signalfd (2),
 171 .BR sigpending (2),
 172 .BR sigprocmask (2),
 173 .BR sigsuspend (2),
 174 .BR sigwaitinfo (2),
 175 .BR signal (7)
 176 .RE
 177 .\"------------------------------------- sigval -----------------------/
 178 .TP
 179 .I sigval
 180 .RS
 181 .IR Include :
 182 .IR <signal.h> .
 183 .PP
 184 .EX
 185 union sigval {
 186     int     sigval_int; /* Integer value */
 187     void   *sigval_ptr; /* Pointer value */
 188 };
 189 .EE
 190 .PP
 191 Data passed with a signal.
 192 .PP
 193 .IR "Conforming to" :
 194 POSIX.1-2001 and later.
 195 .PP
 196 .IR "See also" :
 197 .BR pthread_sigqueue (3),
 198 .BR sigqueue (3),
 199 .BR sigevent (7)
 200 .PP
 201 See also the
 202 .I sigevent
 203 structure
 204 and the
 205 .I siginfo_t
 206 type
 207 in this page.
 208 .RE
 209 .\"------------------------------------- size_t -----------------------/
 210 .\"------------------------------------- sockaddr ---------------------/
 211 .\"------------------------------------- socklen_t --------------------/
 212 .\"------------------------------------- ssize_t ----------------------/
 213 .\"------------------------------------- stat -------------------------/
 214 .\"------------------------------------- suseconds_t ------------------/
 215 .\"------------------------------------- time_t -----------------------/
 216 .\"------------------------------------- timer_t ----------------------/
 217 .\"------------------------------------- timespec ---------------------/
 218 .\"------------------------------------- timeval ----------------------/
 219 .\"------------------------------------- uid_t ----------------------/
 220 .\"------------------------------------- uintmax_t --------------------/
 221 .\"------------------------------------- uintN_t ----------------------/
 222 .\"------------------------------------- uintptr_t --------------------/
 223 .\"------------------------------------- useconds_t -------------------/
 224 .\"------------------------------------- va_list ----------------------/
 225 .\"------------------------------------- void * -----------------------/
 226 .\"--------------------------------------------------------------------/
 227 .SH NOTES
 228 The structures described in this manual page shall contain,
 229 at least, the members shown in their definition, in no particular order.
 230 .PP
 231 Most of the integer types described in this page don't have
 232 a corresponding length modifier for the
 233 .BR printf (3)
 234 and the
 235 .BR scanf (3)
 236 families of functions.
 237 To print a value of an integer type that doesn't have a length modifier,
 238 it should be converted to
 239 .I intmax_t
 240 or
 241 .I uintmax_t
 242 by an explicit cast.
 243 To scan into a variable of an integer type
 244 that doesn't have a length modifier,
 245 an intermediate temporary variable of type
 246 .I intmax_t
 247 or
 248 .I uintmax_t
 249 should be used.
 250 When copying from the temporary variable to the destination variable,
 251 the value could overflow.
 252 If the type has upper and lower limits,
 253 the user should check that the value is within those limits,
 254 before actually copying the value.
 255 The example below shows how these conversions should be done.
 256 .SS Conventions used in this page
 257 In "Conforming to" we only concern ourselves with
 258 C99 and later and POSIX.1-2001 and later.
 259 Some types may be specified in earlier versions of one of these standards,
 260 but in the interests of simplicity we omit details from earlier standards.
 261 .PP
 262 In "Include", we first note the "primary" header(s) that
 263 define the type according to either the C or POSIX.1 standards.
 264 Under "Alternatively", we note additional headers that
 265 the standards specify shall define the type.
 266 .SH EXAMPLES
 267 The program shown below scans from a string and prints a value stored in
 268 a variable of an integer type that doesn't have a length modifier.
 269 The appropriate conversions from and to
 270 .IR intmax_t ,
 271 and the appropriate range checks,
 272 are used as explained in the notes section above.
 273 .PP
 274 .EX
 275 #include <stdint.h>
 276 #include <stdio.h>
 277 #include <stdlib.h>
 278 #include <sys/types.h>
 279
 280 int
 281 main (void)
 282 {
 283     static const char *const str = "500000 us in half a second";
 284     suseconds_t us;
 285     intmax_t    tmp;
 286
 287     /* Scan the number from the string into the temporary variable. */
 288
 289     sscanf(str, "%jd", &tmp);
 290
 291     /* Check that the value is within the valid range of suseconds_t. */
 292
 293     if (tmp < \-1 || tmp > 1000000) {
 294         fprintf(stderr, "Scanned value outside valid range!\en");
 295         exit(EXIT_FAILURE);
 296     }
 297
 298     /* Copy the value to the suseconds_t variable \(aqus\(aq. */
 299
 300     us = tmp;
 301
 302     /* Even though suseconds_t can hold the value \-1, this isn\(aqt
 303        a sensible number of microseconds. */
 304
 305     if (us < 0) {
 306         fprintf(stderr, "Scanned value shouldn\(aqt be negative!\en");
 307         exit(EXIT_FAILURE);
 308     }
 309
 310     /* Print the value. */
 311
 312     printf("There are %jd microseconds in half a second.\en",
 313             (intmax_t) us);
 314
 315     exit(EXIT_SUCCESS);
 316 }
 317 .EE
 318 .SH SEE ALSO
 319 .BR feature_test_macros (7),
 320 .BR standards (7)