aboutsummaryrefslogtreecommitdiffstats
path: root/README
blob: 2866b757a7395de4049bff1b55d36c45065933f6 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
libsimple.h includes most POSIX header files so you do need to include lots of
headers in your code, and defines macros and functions that are useful for most
programs and libraries to simplify the code. It also provides *_MIN and *_MAX
values for integer data types.

All functions are namespaced with `libsimple_` and aliased with macro
definitions to unnamespaced names unless there already is a macro with that
name. However, the `libsimple_{,e,en}{,v}{mem,array}alloc` functions do
not have unnamespaced aliases as they are libsimple specific.

Programs using this library should define `char *argv0` and set it to
the 0:th command line argument.



CLOCK_MONOTONIC_RAW is defined to CLOCK_MONOTONIC unless CLOCK_MONOTONIC_RAW
already exists and unless DONT_DEFINE_CLOCK_MONOTONIC_RAW is defined.

AF_LOCAL, AF_UNIX, AF_FILE, PF_LOCAL, PF_UNIX, and PF_FILE are defined to
appropriate values provided that AF_LOCAL, AF_UNIX, or AF_FILE is already
defined.

The following macros are defined, unless already defined:

	MIN(A, B)
		Select the least of two values.

	MAX(A, B)
		Select the greatest of two values.

	MIN3(A, B, C)
		Select the least of three values.

	MAX3(A, B, C)
		Select the greatest of three values.

	ELEMSOF(ARR)
		Gets the number of elements in an array.

	STRLEN(STR)
		Gets the length of a string literal.

	INTSTRLEN(TYPE)
		Gets the maximum length any value with the integer type TYPE can
		have in base 10.

	TYPE_MAX(TYPE)
		Get the greatest value storable in an integer type.

	TYPE_MIN(TYPE)
		Get the least value storable in an integer type.

	FREE(PTR)
		(free(PTR), (PTR) = NULL, 0)
		Ensures that a pointer is not freed twiced.

	CLOSE(FD)
		((FD) >= 0 ? (close(FD), (FD) = -1, 0) : 0)
		Ensures that errno is not modified when closing an
		already closed file descriptor.

	Maximum values:
		BLKCNT64_MAX, BLKCNT_MAX, BLKSIZE_MAX, CC_MAX, CLOCKID_MAX,
		CLOCK_MAX, DEV_MAX, FSBLKCNT64_MAX, FSBLKCNT_MAX,
		FSFILCNT64_MAX, FSFILCNT_MAX, FSID_MAX, FSWORD_MAX, GID_MAX,
		ID_MAX, INO64_MAX, INO_MAX, KEY_MAX, LOFF_MAX, MODE_MAX,
		NLINK_MAX, OFF64_MAX, OFF_MAX, PID_MAX, QUAD_MAX, REGISTER_MAX,
		RLIM64_MAX, RLIM_MAX, SOCKLEN_MAX, SPEED_MAX, SUSECONDS_MAX,
		TCFLAG_MAX, TIMER_MAX, TIME_MAX, UID_MAX, USECONDS_MAX,
		U_QUAD_MAX

	Minimum values:
		BLKCNT64_MIN, BLKCNT_MIN, BLKSIZE_MIN, CC_MIN, CLOCKID_MIN,
		CLOCK_MIN, DEV_MIN, FSBLKCNT64_MIN, FSBLKCNT_MIN,
		FSFILCNT64_MIN, FSFILCNT_MIN, FSID_MIN, FSWORD_MIN, GID_MIN,
		ID_MIN, INO64_MIN, INO_MIN, KEY_MIN, LOFF_MIN, MODE_MIN,
		NLINK_MIN, OFF64_MIN, OFF_MIN, PID_MIN, QUAD_MIN, REGISTER_MIN,
		RLIM64_MIN, RLIM_MIN, SOCKLEN_MIN, SPEED_MIN, SUSECONDS_MIN,
		TCFLAG_MIN, TIMER_MIN, TIME_MIN, UID_MIN, USECONDS_MIN,
		U_QUAD_MIN

The following functions are defined (some as inline functions):

	int libsimple_close(int *)
		Ensures that errno is not modified when closing an
		already closed file descriptor.

	void *libsimple_rawmemchr(const void *, int)
		memchr without boundary check.

	void *libsimple_memrchr(const void *, int, size_t)
		Like memchr, except finds the last occurrence.

	void *libsimple_rawmemrchr(const void *, int, size_t)
		libsimple_memrchr without boundary check.

	char *libsimple_strchrnul(const char *, int)
		Like strchr, except returns the end if not found.

	char *libsimple_strend(const char *s)
		strchr(s, '\0')

	char *libsimple_inchrset(int c, const char *s)
		c && strchr(s, c)

	void *libsimple_memdup(const void *, size_t)
		Duplicate a memory segment.

	char *libsimple_strndup(const char *, size_t)
		Duplicate a substring.

	void *libsimple_mempcpy(void *, const void *, size_t)
		Like memcpy, except returns the byte after the
		last written byte.

	char *libsimple_strdupa(const char *)
		Like `strdup`, except the returned pointer is stack-allocated.
		This function is implemented as a macro and is only available
		when compiling with GCC or clang.

	char *libsimple_strndupa(const char *, size_t)
		Like `strndup`, except the returned pointer is stack-allocated.
		This function is implemented as a macro and is only available
		when compiling with GCC or clang.

	void *libsimple_memdupa(const void *, size_t)
		Like `memdup`, except the returned pointer is stack-allocated.
		This function is implemented as a macro and is only available
		when compiling with GCC or clang.

	int libsimple_isutf8(const char *s, int allow_modified_nul)
		Returns 1 if `s` is valid UTF-8 (Unicode codepoints are not
		validated) and 0 otherwise. If `allow_modified_nul` is non-zero,
		the byte sequence 0xC0 0x80 is allowed.

	int libsimple_asprintf(char **, const char *, ...)
		Like sprintf accept allocated the buffer.

	int libsimple_vasprintf(char **, const char *, va_list);
		Like vsprintf accept allocated the buffer.

	char *libsimple_asprintfa(const char *, ...)
		Like `asprintf` accept the the buffer is stack-allocated and
		returned instead of stored in a pointer. This function is
		implemented as a macro and is only available when compiling
		with GCC or clang.

	char *libsimple_vasprintfa(const char *, va_list)
		Like `vasprintf` accept the the buffer is stack-allocated and
		returned instead of stored in a pointer. This function is
		implemented as a macro and is only available when compiling
		with GCC or clang.

	void *libsimple_memmem(const void *s, size_t sn, const void *t, size_t tn)
		Finds the first occurrence of `t` in `s`.
		Length of `s` is `sn`. Length of `t` is `tn`.

	void *libsimple_memrmem(const void *s, size_t sn, const void *t, size_t tn)
		Finds the last occurrence of `t` in `s`.
		Length of `s` is `sn`. Length of `t` is `tn`.

	int libsimple_memstarts(const void *s, size_t sn, const void *t, size_t tn)
		Returns 1 if `s` starts with `t`, 0 otherwise.
		Length of `s` is `sn`. Length of `t` is `tn`.

	int libsimple_memends(const void *s, size_t sn, const void *t, size_t tn)
		Returns 1 if `s` ends with `t`, 0 otherwise.
		Length of `s` is `sn`. Length of `t` is `tn`.

	char *libsimple_strrstr(const char *s, const char *t)
		Finds the last occurrence of `t` in `s`.

	char *libsimple_strnstr(const char *s, const char *t, size_t n)
		Finds the first occurrence of the `n` first characters `t`
		in `n` first characters `s`.

	char *libsimple_strrnstr(const char *s, const char *t, size_t n)
		Finds the last occurrence of the `n` first characters `t`
		in `n` first characters `s`.

	int libsimple_strstarts(const char *s, const char *t)
		Returns 1 if `s` starts with `t`, 0 otherwise.

	int libsimple_strcasestarts(const char *, const char *)
		Like strstarts except case-insensitive.

	int libsimple_strends(const char *s, const char *t)
		Returns 1 if `s` ends with `t`, 0 otherwise.

	int libsimple_strcaseends(const char *, const char *)
		Like strends except case-insensitive.

	char *libsimple_strcasestr(const char *, const char *)
		Like strstr except case-insensitive.

	char *libsimple_strrcasestr(const char *, const char *)
		Like strrstr except case-insensitive.

	char *libsimple_strncasestr(const char *, const char *, size_t)
		Like strnstr except case-insensitive.

	char *libsimple_strrncasestr(const char *, const char *, size_t)
		Like strrnstr except case-insensitive.

	int libsimple_strcmpnul(const char *, const char *)
		Like strcmp excepts NULL and gives it a value less than
		the empty string

	int libsimple_strncmpnul(const char *, const char *, size_t)
		Like strncmp excepts NULL and gives it a value less than
		the empty string

	int libsimple_strcasecmpnul(const char *, const char *)
		Like strcasecmp excepts NULL and gives it a value less
		than the empty string

	int libsimple_strncasecmpnul(const char *, const char *, size_t)
		Like strncasecmp excepts NULL and gives it a value less
		than the empty string

	int libsimple_streq(const char *a, const char *b)
		!strcmp(a, b)

	int libsimple_strneq(const char *a, const char *b, size_t n)
		!strncmp(a, b, n)

	int libsimple_streqnul(const char *a, const char *b)
		!strcmpnul(a, b)

	int libsimple_strneqnul(const char *a, const char *b, size_t n)
		!strncmpnul(a, b, n)

	int libsimple_strcaseeq(const char *a, const char *b)
		!strcasecmp(a, b)

	int libsimple_strncaseeq(const char *a, const char *b, size_t n)
		!strncasecmp(a, b, n)

	int libsimple_strcaseeqnul(const char *a, const char *b)
		!strcasecmpnul(a, b)

	int libsimple_strncaseeqnul(const char *a, const char *b, size_t n)
		!strncasecmpnul(a, b, n)

	void *libsimple_vmalloczn(int, size_t, va_list)
		Like malloczn accept uses va_list instead of variadic arguments.

	void *libsimple_vmallocn(size_t, va_list)
		Like mallocn accept uses va_list instead of variadic arguments.

	void *libsimple_vcallocn(size_t, va_list)
		Like callocn accept uses va_list instead of variadic arguments.

	void *libsimple_vreallocn(void *, size_t, va_list)
		Like reallocn accept uses va_list instead of variadic arguments.

	void *libsimple_mallocz(int, size_t)
		Identical to malloc if first argument is zero,
		Identical to calloc, with 1 as the first argument, if first
		argument is non-zero.

	void *libsimple_malloczn(int, size_t, ... /*, (size_t)0 */)
		Identical to mallocn if first argument is zero,
		Identical to callocn if first argument is non-zero.

	void *libsimple_mallocn(size_t, ... /*, (size_t)0 */)
		Like malloc, accept uses the product of all argument, until
		the first 0-argument, the first argument must not be 0.

	void *libsimple_callocn(size_t, ... /*, (size_t)0 */)
		Like calloc, accept uses the product of all argument, until
		the first 0-argument, the first argument must not be 0.

	void *libsimple_reallocn(void *, size_t, ... /*, (size_t)0 */)
		Like realloc, accept uses the product of all argument,
		not counting the first argument, until the first 0-argument,
		the second argument must not be 0.

	char *libsimple_getenv_ne(const char *)
		Like getenv, except returns NULL if the value
		of the environment variable is the empty string.

	const char *libsimple_getenv_e(const char *)
		Like getenv, except returns the empty string if the
		value of the environment variable is undefined.

	int libsimple_vputenvf(const char *, va_list)
		Format a string and call putenv.

	int libsimple_putenvf(const char *, ...)
		Format a string and call putenv.

	void libsimple_vweprintf(const char *, va_list)
		Identical to libsimple_weprintf, except using va_list.

	void libsimple_weprintf(const char *fmt, ...)
		Similar to printf, except prints to stderr and:
		* unless `fmt` starts with "usage: " the `argv` follow by
		  ": " is prepended to the printed string,
		* if `fmt` ends with ":", " " followed by `strerror(errno)`
		  and "\n" and appended to the printed string, and
		* if `fmt` does not end with ":" or "\n", "\n" and appended to
		  the printed string.

		libsimple.h defines `extern int libsimple_default_failure_exit`.

	void libsimple_venprintf(int status, const char *, va_list)
		Like libsimple_vweprintf, but calls exit(status) afterwards.

	void libsimple_enprintf(int status, const char *, ...)
		Like libsimple_weprintf, but calls exit(status) afterwards.

	void libsimple_veprintf(const char *, va_list)
		Like libsimple_veprintf, but calls exit(libsimple_default_failure_exit)
		afterwards.

	void libsimple_eprintf(const char *, ...)
		Like libsimple_weprintf, but calls exit(libsimple_default_failure_exit)
		afterwards.

		libsimple.h defines `extern int libsimple_default_failure_exit`.

	int libsimple_sumtimespec(struct timespec *, const struct timespec *,
	  const struct timespec *)
		Returns the sum of two timestamps.

	int libsimple_difftimespec(struct timespec *, const struct timespec *,
	  const struct timespec *)
		Returns the difference of two timestamps.

	int libsimple_multimespec(struct timespec *, const struct timespec *, int)
		Multiplies a timestamp with an integer.

	int libsimple_cmptimespec(const struct timespec *, const struct timespec *)
		Compares two timestamps, same return semantics as strcmp.

	int libsimple_sumtimeval(struct timeval *, const struct timeval *,
	  const struct timeval *)
		Returns the sum of two timestamps.

	int libsimple_difftimeval(struct timeval *, const struct timeval *,
	  const struct timeval *)
		Returns the difference of two timestamps.

	int libsimple_multimeval(struct timeval *, const struct timeval *, int)
		Multiplies a timestamp with an integer.

	int libsimple_cmptimeval(const struct timeval *, const struct timeval *)
		Compares two timestamps, same return semantics as strcmp.

	void libsimple_timeval2timespec(struct timespec *restrict,
	  const struct timeval *restrict)
		Converts a struct timeval to a struct timespec.

	int libsimple_timespec2timeval(struct timeval *restrict,
	  const struct timespec *restrict)
		Converts a struct timespec to a struct timeval.

	int libsimple_strtotimespec(struct timespec *restrict,
	  const char *restrict, char **restrict)
		Converts a string to a struct timespec.

	int libsimple_strtotimeval(struct timeval *restrict,
	  const char *restrict, char **restrict)
		Converts a string to a struct timeval.

	char *libsimple_timespectostr(char *restrict,
	  const struct timespec *restrict)
		Converts a struct timespec to a string.

	char *libsimple_timevaltostr(char *restrict,
	  const struct timeval *restrict)
		Converts a struct timeval to a string.

	double libsimple_timespectodouble(const struct timespec *)
		Converts a struct timespec to a double.

	double libsimple_timevaltodouble(const struct timeval *)
		Converts a struct timeval to a double.

	void libsimple_doubletotimespec(struct timespec *, double)
		Converts a double to a struct timespec.

	void libsimple_doubletotimeval(struct timeval *, double)
		Converts a double to a struct timeval.

	char *libsimple_minimise_number_string(char *)
		Assumes that the input string is a normal floating-point
		number and removes redundant characters, such '+' sign,
		leading zeroes and trailing zeroes after decimal point.
		The input pointer is returned.

	void libsimple_unlist(void *list, size_t i, size_t *np, size_t width)
		Removes element `i` from the list `list`. `*np` shall be the
		number of elements in the list, it will be updated by the
		function. `width` shall be the byte-width of each element.

		The macro LIBSIMPLE_UNLIST(LIST, I, NP) (alias to UNLIST if no
		such macro already exists) is idential to libsimple_unlist
		except `width` is automatically.


The following functions, which call `eprintf` on failure, are also defined:

	void libsimple_evputenvf(const char *, va_list)
	void libsimple_eputenvf(const char *, ...)
	void *libsimple_emallocz(int, size_t)
	void *libsimple_emalloc(size_t)
	void *libsimple_ecalloc(size_t, size_t)
	void *libsimple_erealloc(void *, size_t)
	char *libsimple_estrdup(const char *)
	char *libsimple_estrndup(const char *, size_t)
	void *libsimple_ememdup(const void *, size_t)
	void *libsimple_evmallocn(size_t, va_list)
	void *libsimple_evcallocn(size_t, va_list)
	void *libsimple_evreallocn(void *, size_t, va_list)
	void *libsimple_evmalloczn(int, size_t, va_list)
	void *libsimple_emalloczn(int, size_t, ...)
	void *libsimple_emallocn(size_t, ...)
	void *libsimple_ecallocn(size_t, ...)
	void *libsimple_ereallocn(void *, size_t, ...)


The following functions, which call `enprintf` on failure, are also defined,
the first argument is used as the first argument for `enprintf`:

	void libsimple_envputenvf(int, const char *, va_list)
	void libsimple_enputenvf(int, const char *, ...)
	void *libsimple_enmallocz(int, size_t)
	void *libsimple_enmalloc(int, size_t)
	void *libsimple_encalloc(int, size_t, size_t)
	void *libsimple_enrealloc(int, void *, size_t)
	char *libsimple_enstrdup(int, const char *)
	char *libsimple_enstrndup(int, const char *, size_t)
	void *libsimple_enmemdup(int, const void *, size_t)
	void *libsimple_envmallocn(int, size_t, va_list)
	void *libsimple_envcallocn(int, size_t, va_list)
	void *libsimple_envreallocn(int, void *, size_t, va_list)
	void *libsimple_envmalloczn(int, int, size_t, va_list)
	void *libsimple_enmalloczn(int, int, size_t, ...)
	void *libsimple_enmallocn(int, size_t, ...)
	void *libsimple_encallocn(int, size_t, ...)
	void *libsimple_enreallocn(int, void *, size_t, ...)