annotate libmlk-util/mlk/util/util.h @ 557:944798a59b8a

util: introduce mlk_util_die
author David Demelier <markand@malikania.fr>
date Wed, 08 Mar 2023 13:17:38 +0100
parents 3663e92842dc
children a2443afe8a1f
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
315
3bfaaf5342a9 cmake: add support for Visual Studio 2019
David Demelier <markand@malikania.fr>
parents:
diff changeset
1 /*
517
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 446
diff changeset
2 * util.h -- miscellaneous utilities and portability
315
3bfaaf5342a9 cmake: add support for Visual Studio 2019
David Demelier <markand@malikania.fr>
parents:
diff changeset
3 *
445
773a082f0b91 misc: update copyright years
David Demelier <markand@malikania.fr>
parents: 444
diff changeset
4 * Copyright (c) 2020-2023 David Demelier <markand@malikania.fr>
315
3bfaaf5342a9 cmake: add support for Visual Studio 2019
David Demelier <markand@malikania.fr>
parents:
diff changeset
5 *
3bfaaf5342a9 cmake: add support for Visual Studio 2019
David Demelier <markand@malikania.fr>
parents:
diff changeset
6 * Permission to use, copy, modify, and/or distribute this software for any
3bfaaf5342a9 cmake: add support for Visual Studio 2019
David Demelier <markand@malikania.fr>
parents:
diff changeset
7 * purpose with or without fee is hereby granted, provided that the above
3bfaaf5342a9 cmake: add support for Visual Studio 2019
David Demelier <markand@malikania.fr>
parents:
diff changeset
8 * copyright notice and this permission notice appear in all copies.
3bfaaf5342a9 cmake: add support for Visual Studio 2019
David Demelier <markand@malikania.fr>
parents:
diff changeset
9 *
3bfaaf5342a9 cmake: add support for Visual Studio 2019
David Demelier <markand@malikania.fr>
parents:
diff changeset
10 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
3bfaaf5342a9 cmake: add support for Visual Studio 2019
David Demelier <markand@malikania.fr>
parents:
diff changeset
11 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
3bfaaf5342a9 cmake: add support for Visual Studio 2019
David Demelier <markand@malikania.fr>
parents:
diff changeset
12 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
3bfaaf5342a9 cmake: add support for Visual Studio 2019
David Demelier <markand@malikania.fr>
parents:
diff changeset
13 * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
3bfaaf5342a9 cmake: add support for Visual Studio 2019
David Demelier <markand@malikania.fr>
parents:
diff changeset
14 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
549
3663e92842dc util: fix broken license
David Demelier <markand@malikania.fr>
parents: 524
diff changeset
15 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
3663e92842dc util: fix broken license
David Demelier <markand@malikania.fr>
parents: 524
diff changeset
16 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
315
3bfaaf5342a9 cmake: add support for Visual Studio 2019
David Demelier <markand@malikania.fr>
parents:
diff changeset
17 */
3bfaaf5342a9 cmake: add support for Visual Studio 2019
David Demelier <markand@malikania.fr>
parents:
diff changeset
18
549
3663e92842dc util: fix broken license
David Demelier <markand@malikania.fr>
parents: 524
diff changeset
19 #ifndef MLK_UTIL_UTIL_H
3663e92842dc util: fix broken license
David Demelier <markand@malikania.fr>
parents: 524
diff changeset
20 #define MLK_UTIL_UTIL_H
315
3bfaaf5342a9 cmake: add support for Visual Studio 2019
David Demelier <markand@malikania.fr>
parents:
diff changeset
21
517
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 446
diff changeset
22 /**
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 446
diff changeset
23 * \file mlk/util/util.h
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 446
diff changeset
24 * \brief Miscellaneous utilities and portability
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 446
diff changeset
25 */
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 446
diff changeset
26
348
7d7991f97acf misc: be more barebone portable
David Demelier <markand@malikania.fr>
parents: 320
diff changeset
27 #include <limits.h>
315
3bfaaf5342a9 cmake: add support for Visual Studio 2019
David Demelier <markand@malikania.fr>
parents:
diff changeset
28 #include <stdio.h>
3bfaaf5342a9 cmake: add support for Visual Studio 2019
David Demelier <markand@malikania.fr>
parents:
diff changeset
29
411
d74f53299252 make: add basic GNU make support
David Demelier <markand@malikania.fr>
parents: 378
diff changeset
30 /*
d74f53299252 make: add basic GNU make support
David Demelier <markand@malikania.fr>
parents: 378
diff changeset
31 * This file helps finding what are the available features accross the various
d74f53299252 make: add basic GNU make support
David Demelier <markand@malikania.fr>
parents: 378
diff changeset
32 * operating system in the landscape.
d74f53299252 make: add basic GNU make support
David Demelier <markand@malikania.fr>
parents: 378
diff changeset
33 *
d74f53299252 make: add basic GNU make support
David Demelier <markand@malikania.fr>
parents: 378
diff changeset
34 * The following macros are automatically set depending on the operating
d74f53299252 make: add basic GNU make support
David Demelier <markand@malikania.fr>
parents: 378
diff changeset
35 * system:
d74f53299252 make: add basic GNU make support
David Demelier <markand@malikania.fr>
parents: 378
diff changeset
36 *
d74f53299252 make: add basic GNU make support
David Demelier <markand@malikania.fr>
parents: 378
diff changeset
37 * - MLK_OS_WINDOWS: running on any Windows machine
d74f53299252 make: add basic GNU make support
David Demelier <markand@malikania.fr>
parents: 378
diff changeset
38 * - MLK_OS_POSIX: every mostly POSIX systems
d74f53299252 make: add basic GNU make support
David Demelier <markand@malikania.fr>
parents: 378
diff changeset
39 *
d74f53299252 make: add basic GNU make support
David Demelier <markand@malikania.fr>
parents: 378
diff changeset
40 * The following macro will be automatically defined unless the user override
d74f53299252 make: add basic GNU make support
David Demelier <markand@malikania.fr>
parents: 378
diff changeset
41 * them:
d74f53299252 make: add basic GNU make support
David Demelier <markand@malikania.fr>
parents: 378
diff changeset
42 *
d74f53299252 make: add basic GNU make support
David Demelier <markand@malikania.fr>
parents: 378
diff changeset
43 * - MLK_HAS_FMEMOPEN: defined if fmemopen function is available.
d74f53299252 make: add basic GNU make support
David Demelier <markand@malikania.fr>
parents: 378
diff changeset
44 * - MLK_HAS_SSIZE_T: defined if ssize_t typedef is available.
d74f53299252 make: add basic GNU make support
David Demelier <markand@malikania.fr>
parents: 378
diff changeset
45 */
d74f53299252 make: add basic GNU make support
David Demelier <markand@malikania.fr>
parents: 378
diff changeset
46
d74f53299252 make: add basic GNU make support
David Demelier <markand@malikania.fr>
parents: 378
diff changeset
47 #if defined(_WIN32)
d74f53299252 make: add basic GNU make support
David Demelier <markand@malikania.fr>
parents: 378
diff changeset
48 # define MLK_OS_WINDOWS
d74f53299252 make: add basic GNU make support
David Demelier <markand@malikania.fr>
parents: 378
diff changeset
49 #elif defined(__FreeBSD__)
d74f53299252 make: add basic GNU make support
David Demelier <markand@malikania.fr>
parents: 378
diff changeset
50 # define MLK_OS_POSIX
444
9f062143e675 misc: fix for DragonFlyBSD
David Demelier <markand@malikania.fr>
parents: 432
diff changeset
51 #elif defined(__DragonFly__)
9f062143e675 misc: fix for DragonFlyBSD
David Demelier <markand@malikania.fr>
parents: 432
diff changeset
52 # define MLK_OS_POSIX
411
d74f53299252 make: add basic GNU make support
David Demelier <markand@malikania.fr>
parents: 378
diff changeset
53 #elif defined(__OpenBSD__)
d74f53299252 make: add basic GNU make support
David Demelier <markand@malikania.fr>
parents: 378
diff changeset
54 # define MLK_OS_POSIX
d74f53299252 make: add basic GNU make support
David Demelier <markand@malikania.fr>
parents: 378
diff changeset
55 #elif defined(__NetBSD__)
d74f53299252 make: add basic GNU make support
David Demelier <markand@malikania.fr>
parents: 378
diff changeset
56 # define MLK_OS_POSIX
d74f53299252 make: add basic GNU make support
David Demelier <markand@malikania.fr>
parents: 378
diff changeset
57 #elif defined(__linux__)
d74f53299252 make: add basic GNU make support
David Demelier <markand@malikania.fr>
parents: 378
diff changeset
58 # define MLK_OS_POSIX
d74f53299252 make: add basic GNU make support
David Demelier <markand@malikania.fr>
parents: 378
diff changeset
59 #elif defined(__APPLE__)
d74f53299252 make: add basic GNU make support
David Demelier <markand@malikania.fr>
parents: 378
diff changeset
60 # define MLK_OS_POSIX
d74f53299252 make: add basic GNU make support
David Demelier <markand@malikania.fr>
parents: 378
diff changeset
61 # define MLK_OS_APPLE
d74f53299252 make: add basic GNU make support
David Demelier <markand@malikania.fr>
parents: 378
diff changeset
62 #endif
d74f53299252 make: add basic GNU make support
David Demelier <markand@malikania.fr>
parents: 378
diff changeset
63
524
c2124ecb2423 util: prefix PATH_MAX to MLK_PATH_MAX
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
64 #if defined(PATH_MAX)
c2124ecb2423 util: prefix PATH_MAX to MLK_PATH_MAX
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
65 # define MLK_PATH_MAX PATH_MAX
c2124ecb2423 util: prefix PATH_MAX to MLK_PATH_MAX
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
66 #elif defined(_POSIX_PATH_MAX)
c2124ecb2423 util: prefix PATH_MAX to MLK_PATH_MAX
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
67 # define MLK_PATH_MAX _POSIX_PATH_MAX
c2124ecb2423 util: prefix PATH_MAX to MLK_PATH_MAX
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
68 #else
c2124ecb2423 util: prefix PATH_MAX to MLK_PATH_MAX
David Demelier <markand@malikania.fr>
parents: 517
diff changeset
69 # define MLK_PATH_MAX 4096
315
3bfaaf5342a9 cmake: add support for Visual Studio 2019
David Demelier <markand@malikania.fr>
parents:
diff changeset
70 #endif
3bfaaf5342a9 cmake: add support for Visual Studio 2019
David Demelier <markand@malikania.fr>
parents:
diff changeset
71
411
d74f53299252 make: add basic GNU make support
David Demelier <markand@malikania.fr>
parents: 378
diff changeset
72 #if defined(MLK_OS_POSIX) && !defined(MLK_HAS_SSIZE_T)
d74f53299252 make: add basic GNU make support
David Demelier <markand@malikania.fr>
parents: 378
diff changeset
73 # define MLK_HAS_SSIZE_T
d74f53299252 make: add basic GNU make support
David Demelier <markand@malikania.fr>
parents: 378
diff changeset
74 #endif
d74f53299252 make: add basic GNU make support
David Demelier <markand@malikania.fr>
parents: 378
diff changeset
75
d74f53299252 make: add basic GNU make support
David Demelier <markand@malikania.fr>
parents: 378
diff changeset
76 #if !defined(MLK_HAS_SSIZE_T)
315
3bfaaf5342a9 cmake: add support for Visual Studio 2019
David Demelier <markand@malikania.fr>
parents:
diff changeset
77 typedef long long int ssize_t;
3bfaaf5342a9 cmake: add support for Visual Studio 2019
David Demelier <markand@malikania.fr>
parents:
diff changeset
78 #endif
3bfaaf5342a9 cmake: add support for Visual Studio 2019
David Demelier <markand@malikania.fr>
parents:
diff changeset
79
411
d74f53299252 make: add basic GNU make support
David Demelier <markand@malikania.fr>
parents: 378
diff changeset
80 #if defined(MLK_OS_POSIX) && !defined(MLK_HAS_FMEMOPEN)
d74f53299252 make: add basic GNU make support
David Demelier <markand@malikania.fr>
parents: 378
diff changeset
81 # define MLK_HAS_FMEMOPEN
d74f53299252 make: add basic GNU make support
David Demelier <markand@malikania.fr>
parents: 378
diff changeset
82 #endif
d74f53299252 make: add basic GNU make support
David Demelier <markand@malikania.fr>
parents: 378
diff changeset
83
517
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 446
diff changeset
84 #if defined(__cplusplus)
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 446
diff changeset
85 extern "C" {
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 446
diff changeset
86 #endif
348
7d7991f97acf misc: be more barebone portable
David Demelier <markand@malikania.fr>
parents: 320
diff changeset
87
517
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 446
diff changeset
88 /**
557
944798a59b8a util: introduce mlk_util_die
David Demelier <markand@malikania.fr>
parents: 549
diff changeset
89 * Print a fatal message and exit with code 1.
944798a59b8a util: introduce mlk_util_die
David Demelier <markand@malikania.fr>
parents: 549
diff changeset
90 *
944798a59b8a util: introduce mlk_util_die
David Demelier <markand@malikania.fr>
parents: 549
diff changeset
91 * \pre fmt != NULL
944798a59b8a util: introduce mlk_util_die
David Demelier <markand@malikania.fr>
parents: 549
diff changeset
92 * \param fmt the printf format string
944798a59b8a util: introduce mlk_util_die
David Demelier <markand@malikania.fr>
parents: 549
diff changeset
93 */
944798a59b8a util: introduce mlk_util_die
David Demelier <markand@malikania.fr>
parents: 549
diff changeset
94 void
944798a59b8a util: introduce mlk_util_die
David Demelier <markand@malikania.fr>
parents: 549
diff changeset
95 mlk_util_die(const char *fmt, ...);
944798a59b8a util: introduce mlk_util_die
David Demelier <markand@malikania.fr>
parents: 549
diff changeset
96
944798a59b8a util: introduce mlk_util_die
David Demelier <markand@malikania.fr>
parents: 549
diff changeset
97 /**
517
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 446
diff changeset
98 * Compatibility version of OpenBSD [strlcpy].
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 446
diff changeset
99 *
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 446
diff changeset
100 * [strlcpy]: http://man.openbsd.org/strlcpy
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 446
diff changeset
101 */
348
7d7991f97acf misc: be more barebone portable
David Demelier <markand@malikania.fr>
parents: 320
diff changeset
102 size_t
517
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 446
diff changeset
103 mlk_util_strlcpy(char *dst, const char *src, size_t dstsz);
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 446
diff changeset
104
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 446
diff changeset
105 /**
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 446
diff changeset
106 * Compatibility version of OpenBSD [strlcat].
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 446
diff changeset
107 *
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 446
diff changeset
108 * [strlcat]: http://man.openbsd.org/strlcat
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 446
diff changeset
109 */
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 446
diff changeset
110 size_t
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 446
diff changeset
111 mlk_util_strlcat(char *dst, const char *src, size_t dstsz);
348
7d7991f97acf misc: be more barebone portable
David Demelier <markand@malikania.fr>
parents: 320
diff changeset
112
7d7991f97acf misc: be more barebone portable
David Demelier <markand@malikania.fr>
parents: 320
diff changeset
113 FILE *
446
4607eea0eabc util: prefix with mlk_
David Demelier <markand@malikania.fr>
parents: 445
diff changeset
114 mlk_util_fmemopen(void *, size_t, const char *);
348
7d7991f97acf misc: be more barebone portable
David Demelier <markand@malikania.fr>
parents: 320
diff changeset
115
517
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 446
diff changeset
116 /**
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 446
diff changeset
117 * Portable version of POSIX [basename].
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 446
diff changeset
118 *
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 446
diff changeset
119 * [basename]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/basename.html
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 446
diff changeset
120 */
348
7d7991f97acf misc: be more barebone portable
David Demelier <markand@malikania.fr>
parents: 320
diff changeset
121 char *
446
4607eea0eabc util: prefix with mlk_
David Demelier <markand@malikania.fr>
parents: 445
diff changeset
122 mlk_util_basename(char *);
348
7d7991f97acf misc: be more barebone portable
David Demelier <markand@malikania.fr>
parents: 320
diff changeset
123
517
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 446
diff changeset
124 /**
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 446
diff changeset
125 * Portable version of POSIX [dirname].
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 446
diff changeset
126 *
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 446
diff changeset
127 * [dirname]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/dirname.html
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 446
diff changeset
128 */
348
7d7991f97acf misc: be more barebone portable
David Demelier <markand@malikania.fr>
parents: 320
diff changeset
129 char *
446
4607eea0eabc util: prefix with mlk_
David Demelier <markand@malikania.fr>
parents: 445
diff changeset
130 mlk_util_dirname(char *);
348
7d7991f97acf misc: be more barebone portable
David Demelier <markand@malikania.fr>
parents: 320
diff changeset
131
446
4607eea0eabc util: prefix with mlk_
David Demelier <markand@malikania.fr>
parents: 445
diff changeset
132 extern int mlk_util_opterr;
4607eea0eabc util: prefix with mlk_
David Demelier <markand@malikania.fr>
parents: 445
diff changeset
133 extern int mlk_util_optind;
4607eea0eabc util: prefix with mlk_
David Demelier <markand@malikania.fr>
parents: 445
diff changeset
134 extern int mlk_util_optopt;
4607eea0eabc util: prefix with mlk_
David Demelier <markand@malikania.fr>
parents: 445
diff changeset
135 extern char *mlk_util_optarg;
348
7d7991f97acf misc: be more barebone portable
David Demelier <markand@malikania.fr>
parents: 320
diff changeset
136
517
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 446
diff changeset
137 /**
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 446
diff changeset
138 * Portable version of POSIX [getopt].
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 446
diff changeset
139 *
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 446
diff changeset
140 * All variables that the standard getopt uses are prefixed with `mlk_util_`.
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 446
diff changeset
141 *
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 446
diff changeset
142 * - optarg -> mlk_util_optarg
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 446
diff changeset
143 * - opterr -> mlk_util_opterr
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 446
diff changeset
144 * - optind -> mlk_util_optind
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 446
diff changeset
145 * - optopt -> mlk_util_optopt
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 446
diff changeset
146 *
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 446
diff changeset
147 * [getopt]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/getopt.html
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 446
diff changeset
148 */
348
7d7991f97acf misc: be more barebone portable
David Demelier <markand@malikania.fr>
parents: 320
diff changeset
149 int
517
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 446
diff changeset
150 mlk_util_getopt(int argc, char **argv, const char *optstring);
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 446
diff changeset
151
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 446
diff changeset
152 #if defined(__cplusplus)
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 446
diff changeset
153 }
6e8f6640e05b misc: use extern C manually
David Demelier <markand@malikania.fr>
parents: 446
diff changeset
154 #endif
348
7d7991f97acf misc: be more barebone portable
David Demelier <markand@malikania.fr>
parents: 320
diff changeset
155
549
3663e92842dc util: fix broken license
David Demelier <markand@malikania.fr>
parents: 524
diff changeset
156 #endif /* !MLK_UTIL_UTIL_H */