Mercurial > irccd

annotate extern/libcompat/README.md @ 974:342fb90f2512

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
irccdctl: re-implement many of the plugin-* commands
author David Demelier <markand@malikania.fr>
date Sun, 07 Feb 2021 14:36:28 +0100
parents 243f9f51b0ff
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
934
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
1 libcompat
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
2 =========
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
3
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
4 This project contains several polyfill for various C extensions that are not
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
5 part of C standard or POSIX.
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
6
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
7 For example, it contains various functions such as:
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
8
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
9 - pledge: privileges separation from OpenBSD (no-op on other systems),
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
10 - reallocarray/recallocarray: safe alternative to realloc for arrays from
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
11 OpenBSD,
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
12 - strlcpy/strlcat: safer alternatives to strncpy/strncat from OpenBSD,
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
13 - strsep: better alternative to strtok from 4.4BSD.
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
14
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
15 Requirements
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
16 ------------
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
17
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
18 - C compiler,
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
19 - POSIX conformant system (ar, make, sh, rm, tr, touch).
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
20
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
21 Usage
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
22 -----
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
23
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
24 The easiest way to use libcompat is to copy the directory content into your
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
25 project and to adapt files you need.
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
26
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
27 Every routine (or group of routines) is implemented into an individual file
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
28 plus tested with a test file.
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
29
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
30 Example with strlcpy:
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
31
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
32 - libcompat/strlcpy.c
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
33 - libcompat/test-strlcpy.c
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
34
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
35 Then, the build process create the following output files, example with
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
36 strlcpy:
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
37
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
38 - libcompat/strlcpy.t: output of the compiler command, usually empty on
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
39 success.
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
40 - libcompat/strlcpy.h: a header file containing `#define COMPAT_HAVE_STRLCPY`
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
41 if the test succeed.
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
42 - libcompat/strlcpy.o: object file containing fallback implementation or
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
43 nothing if the component is available in the host system.
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
44
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
45 Finally, when you want to use one of the extension, you'll have to import the
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
46 header file where it's supposed to be declared (unless this header file is not
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
47 portable) and you also must include libcompat/compat.h.
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
48
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
49 Example with strlcpy:
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
50
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
51 #include <string.h>
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
52 #include "libcompat/compat.h"
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
53
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
54 ### Wrapper script
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
55
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
56 The convenient script libcompat/compile.sh will try co compile the test and
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
57 will either compile the polyfill or a dummy empty file instead. It should be
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
58 invoked with the canonical filename (without extension).
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
59
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
60 It also read `CC`, `CFLAGS` and `LDFLAGS` environment variable which are all
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
61 optional.
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
62
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
63 Example of use:
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
64
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
65 ./libcompat/compile.sh strlcpy
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
66 CC="clang" CFLAGS="-O2" ./libcompat/compile.sh strlcat
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
67
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
68 ### Makefile
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
69
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
70 The included Makefile can be used as boilerplate into your project and create a
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
71 libcompat.a archive ready to use. Simply adapt macros in the Makefile for your
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
72 own use.
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
73
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
74 Licenses
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
75 --------
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
76
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
77 Polyfill code are licensed per their authors and must be checked individually.
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
78 See headers in the libcompat directory.
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
79
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
80 Author
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
81 ------
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
82
243f9f51b0ff irccd: import libcompat and utilities
David Demelier <markand@malikania.fr>
parents:
diff changeset
83 David Demelier <markand@malikania.fr>