Split README.md in two, create a new doc/API.md
Signed-off-by: Joachim Wiberg <troglobit@gmail.com>
Joachim Wiberg
2 years ago
130 | 130 | # INLINE_INHERITED_MEMB = |
131 | 131 | # INLINE_SIMPLE_STRUCTS = |
132 | 132 | # INLINE_SOURCES = |
133 | INPUT = src/ README.md | |
133 | INPUT = src/ README.md doc/API.md | |
134 | 134 | # INPUT_ENCODING = |
135 | 135 | # INTERACTIVE_SVG = |
136 | 136 | # INTERNAL_DOCS = |
7 | 7 | * [Introduction](#introduction) |
8 | 8 | * [Using -lite](#using--lite) |
9 | 9 | * [Important Node](#important-note) |
10 | * [Helper Macros](#helper-macros) | |
11 | * [Generic Functions](#generic-functions) | |
12 | * [GNU Functions](#gnu-functions) | |
13 | * [OpenBSD/NetBSD/FreeBSD Functions](#openbsd-netbsd-freebsd-functions) | |
10 | * [Helper Macros](doc/API.md#helper-macros) | |
11 | * [Generic Functions](doc/API.md#generic-functions) | |
12 | * [GNU Functions](doc/API.md#gnu-functions) | |
13 | * [OpenBSD/NetBSD/FreeBSD Functions](doc/API.md#openbsd-netbsd-freebsd-functions) | |
14 | 14 | * [Build & Install](#build--install) |
15 | 15 | * [Origin & References](#origin--references) |
16 | 16 | |
72 | 72 | > API Documentaion: https://codedocs.xyz/troglobit/libite/ |
73 | 73 | |
74 | 74 | |
75 | Important Note | |
76 | -------------- | |
77 | ||
78 | When using functions like `mkpath()`, `makepath()`, and `makefifo()`, | |
79 | make sure your `umask()` is correct so you do not accidentally create | |
80 | files and directories accessible to other users than intended. | |
81 | ||
82 | ||
83 | Helper Macros | |
84 | ------------- | |
85 | ||
86 | - `atonum(str)` | |
87 | ||
88 | Convert string to natural number, works for 32-bit non-negative | |
89 | integers. Returns -1 on error. (Uses `strtonum()` internally.) | |
90 | ||
91 | - `blkdev(dev)` | |
92 | ||
93 | Create block device | |
94 | ||
95 | - `chardev(dev)` | |
96 | ||
97 | Create character device | |
98 | ||
99 | - `erase(path)` | |
100 | ||
101 | Erase file/directory with `remove()`. Errors on `stderr` | |
102 | ||
103 | - `erasef(fmt, ...)` | |
104 | ||
105 | Like `erase()` but takes a formatted printf-like string as argument. | |
106 | ||
107 | - `makedir(path)` | |
108 | ||
109 | Create directory, like `mkdir()`. Errors on `stderr` | |
110 | ||
111 | - `makefifo(path)` | |
112 | ||
113 | Create a FIFO, like `mkfifo()`. Errors on `stderr` | |
114 | ||
115 | - `min(a,b)`/`max(a,b)` | |
116 | ||
117 | These macros take care to avoid double evaluation. | |
118 | ||
119 | - `touch(path)` | |
120 | ||
121 | Create a file, or update mtime. Errors on `stderr` | |
122 | ||
123 | - `touchf(fmt, ...)` | |
124 | ||
125 | Like `touch()` but takes a formatted printf-like string as argument. | |
126 | ||
127 | - `S_ISEXEC(mode_t m)` | |
128 | ||
129 | Mysteriously missing from GLIBC | |
130 | ||
131 | - `ISCLR(word,bit)` | |
132 | ||
133 | Is bit in (integer) word cleared? | |
134 | ||
135 | - `ISSET(word,bit)` | |
136 | ||
137 | Is bit in (integer) word set? | |
138 | ||
139 | - `ISOTHER(word,bit)` | |
140 | ||
141 | Are any other bits, except bit, in (integer) word set? | |
142 | ||
143 | - `SETBIT(word,bit)` | |
144 | ||
145 | Set bit in (integer) word. | |
146 | ||
147 | - `CLRBIT(word,bit)` | |
148 | ||
149 | Clear bit in (integer) word. | |
150 | ||
151 | - `NELEMS(array)` | |
152 | ||
153 | Returns the number of elements in an array. From the great book, The | |
154 | Practice of Programming, by Kernighan and Pike. | |
155 | ||
156 | ||
157 | Generic Functions | |
158 | ----------------- | |
159 | ||
160 | - `chomp(str)` | |
161 | ||
162 | Perl like chomp function, chop off last char if newline. | |
163 | ||
164 | - `copyfile(src, dst, len, opt)` | |
165 | ||
166 | Like the shell `cp(1)` and `dd(1),`, can also copy symlinks and | |
167 | preserve the mtime of the source file. The opt argument can be | |
168 | a mask of: | |
169 | ||
170 | - `LITE_FOPT_COPYFILE_SYM (0x01)` | |
171 | - `LITE_FOPT_KEEP_MTIME (0x02)` | |
172 | ||
173 | In releases prior to v2.0 the opt argument was called `symlink`. | |
174 | The APIs are 100% compatible if the value `1` was used to enable | |
175 | the symlink option. | |
176 | ||
177 | - `dir(dir, ext, filter, list, strip)` | |
178 | ||
179 | Wrapper for `scandir()` with optional filter. Returns a list of | |
180 | names: files and directories that must be freed after use. See | |
181 | the unit test for an example, or take a look at `glob(3)`, it's | |
182 | probably what you want anyway. | |
183 | ||
184 | - `fcopyfile(src, dst)` | |
185 | ||
186 | Like `copyfile()` but uses already open `FILE *` pointers. Copies | |
187 | from current file positions to current file positions until EOF. | |
188 | ||
189 | - `fexist(file)` | |
190 | ||
191 | Check for the existence of a file, returns True(1) or False(0). | |
192 | ||
193 | - `fisdir(path)` | |
194 | ||
195 | Check for the existence of a directory, returns True(1) or False(0). | |
196 | ||
197 | - `fopenf(mode, fmt, ...)` | |
198 | ||
199 | Like `fopen()`, but takes a formatted string as argument. This | |
200 | greatly simplifies operations that usually consist of composing a | |
201 | filename from parts into a dynamic buffer before actually opening | |
202 | the file. | |
203 | ||
204 | > **Notice:** the swapped order of `pathname` and `mode`! | |
205 | ||
206 | - `fremove(fmt, ...)` | |
207 | ||
208 | Like `remove()`, but takes a formatted string as argument. This | |
209 | greatly simplifies operations that usually consist of composing a | |
210 | filename from parts into a dynamic buffer before actually removing | |
211 | the file. | |
212 | ||
213 | - `fsendfile(src, dst, len)` | |
214 | ||
215 | Copy data between file streams, very similar to `fcopyfile()`, but | |
216 | `dst` is allowed to be `NULL` to be able to read and discard `len` | |
217 | bytes from `src`. | |
218 | ||
219 | - `ifconfig(ifname, addr, mask, up)` | |
220 | ||
221 | Basic ifconfig like operations on an interface. Only supports IPv4 | |
222 | addresses. Note that mask is not CIDR notation. | |
223 | ||
224 | - `lfopen(file, sep)`, `lfclose(lf)` | |
225 | ||
226 | LITE file API for parsing UNIX style configuration files like | |
227 | `/etc/protocols` and `/etc/services`. | |
228 | ||
229 | - `lftok(lf)` | |
230 | ||
231 | Read tokens, delimited by `sep`, from file opened with `lfopen()`. | |
232 | ||
233 | - `lfgetkey(lf, key)` | |
234 | ||
235 | Find `key` in file opened with `lfopen()`, return value/argument. | |
236 | ||
237 | - `lfgetint(lf, key)` | |
238 | ||
239 | Wrapper for `lfgetkey()`, returns positive integer value to `key`, | |
240 | or `-1` if `key` is not found. | |
241 | ||
242 | - `fgetint(file, sep, key)` | |
243 | ||
244 | Wrapper for `lfopen()`, `lfgetint()`, and `lfclose()`. Useful for | |
245 | when only reading a single `key` from a file. | |
246 | ||
247 | - `makepath(dir)` | |
248 | ||
249 | Create all components of the specified directory. | |
250 | ||
251 | - `mkpath(dir, mode)` | |
252 | ||
253 | Like `makepath()`, but also takes a `mode_t` permission mode argument. | |
254 | ||
255 | - `fmkpath(mode, fmt, ...)` | |
256 | ||
257 | Like `mkpath()`, but takes a formatted string as argument. | |
258 | ||
259 | > **Notice:** the swapped order of `pathname` and `mode`! | |
260 | ||
261 | - `movefile(src, dst)` | |
262 | ||
263 | Like `copyfile()`, but renames `src` to `dst`, or recreates symlink | |
264 | with the `dst` name. On successful operation the source is removed | |
265 | and the function returns POSIX OK (0). | |
266 | ||
267 | - `pidfile(name)` | |
268 | ||
269 | Create a daemon PID file using either the `name` as a full path, if | |
270 | `name` starts with `/`, or in `_PATH_VARRUN` using `name` as the | |
271 | basename of the application. If `name` is `NULL`, then `__progname` | |
272 | is used as the basename. The resulting file name is available to the | |
273 | user as a read-only pointer: | |
274 | ||
275 | extern char *__pidfile_name; | |
276 | ||
277 | Use this function to create a PID file for your daemon when it is | |
278 | ready to receive signals. A client application may poll for the | |
279 | existence of this file, so make sure to have your signal handlers | |
280 | properly setup before calling this function. | |
281 | ||
282 | The PID file is removed when the program exits, using an `atexit()` | |
283 | handler. However, depending on how the program terminates the file | |
284 | may still exist even though the program is no longer running. | |
285 | ||
286 | Calling this function multiple times updates the mtime of the file. | |
287 | Only one `atexit()` handler is created, regardless of the amount of | |
288 | times the function is called. If the file is removed, subsequent | |
289 | calls to this function will recreate the file. | |
290 | ||
291 | See below for a link to OpenBSD man page. | |
292 | ||
293 | - `pidfile_read(pidfile)` | |
294 | ||
295 | Read PID from pid file created by `pidfile()`. | |
296 | ||
297 | - `pidfile_signal(pidfile, signal)` | |
298 | ||
299 | Send signal to PID found in pid file created by `pidfile()`. | |
300 | ||
301 | - `progress(percent, max_width)` | |
302 | ||
303 | Simple ASCII progress bar with a spinner. Start it with `percent=0` | |
304 | and set the `max_width=chars` to indicate width of the progress bar. | |
305 | Called multiple times with the same percentage value cause spinner to | |
306 | spin. | |
307 | ||
308 | - `rsync(src, dst, opt, *filter())` | |
309 | ||
310 | Very simple `rsync()` to copy files and directories recursively. It | |
311 | supports pruning files from the destination tree that do not exist in | |
312 | the source tree and preserving the mtime of the source files. The opt | |
313 | argument can be a mask of: | |
314 | ||
315 | - `LITE_FOPT_RSYNC_DELETE (0x01)` | |
316 | - `LITE_FOPT_KEEP_MTIME (0x02)` | |
317 | ||
318 | In releases prior to v2.0 the argument controlling pruning was called | |
319 | `delete`, it is now called `opt`. The APIs are 100% compatible if the | |
320 | value `1` was used. | |
321 | ||
322 | - `strmatch(str, list)`, `strnmatch(str, list, len)` | |
323 | ||
324 | Find matching string in an array of strings. Returns index in array on | |
325 | match, or `-1` on error or not found. `strnmatch()` takes an extra arg | |
326 | to compare only `len` number of characters from `str`. | |
327 | ||
328 | - `strtrim(str)` | |
329 | ||
330 | Trims a string from any leading and trailing white-space, returns the | |
331 | trimmed result in the same buffer. | |
332 | ||
333 | - `systemf(fmt, ...)` | |
334 | ||
335 | Like `system()`, but takes a formatted string as argument. This | |
336 | greatly simplifies operations that usually consist of composing a | |
337 | command from parts into a dynamic buffer before calling it. | |
338 | ||
339 | - `telnet_open(addr, port), telnet_close(ctx), telnet_expect(ctx, script, output)` | |
340 | ||
341 | Poor mans telnet expect in C. Opens connection to a Telnet service; | |
342 | FTP, Telnet, similar, and run an expect-like script. | |
343 | ||
344 | - `telnet_session(addr, port, script output)` | |
345 | ||
346 | Wrapper for the above three in one API. | |
347 | ||
348 | - `tempfile()` | |
349 | ||
350 | Secure replacement for `tmpfile()`. Creates an invisible temporary | |
351 | file in `/tmp` that is removed when the returned `FILE` pointer is | |
352 | closed. | |
353 | ||
354 | **Note:** Requires Linux v3.11, or later, will fall back to the old | |
355 | and unsafe `tmpfile()` on older systems. | |
356 | ||
357 | - `truncatef(length, fmt, ...)` | |
358 | ||
359 | Like `truncate()`, but takes a formatted string as argument. This | |
360 | simplifies some operations when the filename otherwise have to be | |
361 | composed from parts into a separate array before calling the real | |
362 | function. | |
363 | ||
364 | - `which(cmd)`, `whichp(cmd)` | |
365 | ||
366 | C implementation of UNIX which(1). Returns a malloc'ed string with the | |
367 | full path to `cmd` on success, otherwise `NULL`. | |
368 | ||
369 | `whichp()` is a predicate function, returns `TRUE` or `FALSE`. | |
370 | ||
371 | **Note:** `which("/bin/ps aux")` will return `/bin/ps`, or `TRUE`, | |
372 | provided of course `/bin/ps` exists. | |
373 | ||
374 | - `yorn(fmt, ...)` | |
375 | ||
376 | Pose a question to user, appended with `(y/N)?`, returns `TRUE` for | |
377 | yes (both `y` and `Y` are handled) and `FALSE` for everything else. | |
378 | ||
379 | ||
380 | GNU Functions | |
381 | ------------- | |
382 | ||
383 | The following are useful GNU functions, that do not exist on *BSD, and | |
384 | some other platforms. | |
385 | ||
386 | - `strdupa(str)` | |
387 | ||
388 | http://man7.org/linux/man-pages/man3/strdupa.3.html | |
389 | ||
390 | - `strndupa(str)` | |
391 | ||
392 | http://man7.org/linux/man-pages/man3/strndupa.3.html | |
393 | ||
394 | - `strnlen(str, lim)` | |
395 | ||
396 | http://man7.org/linux/man-pages/man3/strnlen.3.html | |
397 | ||
398 | ||
399 | OpenBSD/NetBSD/FreeBSD Functions | |
400 | -------------------------------- | |
401 | ||
402 | The following are popular functions and highly useful macros from the | |
403 | *BSD world of UNIX that are sadly missing on Linux. | |
404 | ||
405 | - `fparseln(fp, *len, *lineno, delim, flags)` | |
406 | ||
407 | http://man.openbsd.org/OpenBSD-current/man3/fparseln.3 | |
408 | ||
409 | - `pidfile(basename)` | |
410 | ||
411 | http://www.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man3/pidfile.3 | |
412 | ||
413 | **Note:** the version of `pidfile()` in -lite has been extended to | |
414 | handle it being called multiple times, i.e. to not create multiple | |
415 | `atexit()` handlers, and also to export a few internal paths: | |
416 | ||
417 | - `__pidfile_path`: prefix path, default `_PATH_VARRUN`. Notice the | |
418 | trailing slash requirement if you want to override it! | |
419 | - `__pidfile_name`: full path to PID file , similar to `__progname`. | |
420 | See previous section for details. | |
421 | ||
422 | - `reallocarray(ptr, nmemb, size)` | |
423 | ||
424 | http://man.openbsd.org/OpenBSD-current/man3/reallocarray.3 | |
425 | ||
426 | - `strlcpy(dst, src, len)` | |
427 | ||
428 | http://www.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man3/strlcpy.3 | |
429 | ||
430 | - `strlcat(dst, src, len)` | |
431 | ||
432 | http://www.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man3/strlcat.3 | |
433 | ||
434 | - `strtonum()` | |
435 | ||
436 | http://www.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man3/strtonum.3 | |
437 | ||
438 | - `sys/queue.h` API | |
439 | ||
440 | http://www.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man3/LIST_EMPTY.3 | |
441 | ||
442 | - `sys/tree.h` API | |
443 | ||
444 | Niels Provos' famous splay and red-black tree implementation. | |
445 | ||
446 | http://www.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man3/SPLAY_FOREACH.3 | |
447 | ||
448 | ||
449 | 75 | Build & Install |
450 | 76 | --------------- |
451 | 77 |
0 | API Documentation | |
1 | ================= | |
2 | ||
3 | ||
4 | Important Note | |
5 | -------------- | |
6 | ||
7 | When using functions like `mkpath()`, `makepath()`, and `makefifo()`, | |
8 | make sure your `umask()` is correct so you do not accidentally create | |
9 | files and directories accessible to other users than intended. | |
10 | ||
11 | ||
12 | Helper Macros | |
13 | ------------- | |
14 | ||
15 | - `atonum(str)` | |
16 | ||
17 | Convert string to natural number, works for 32-bit non-negative | |
18 | integers. Returns -1 on error. (Uses `strtonum()` internally.) | |
19 | ||
20 | - `blkdev(dev)` | |
21 | ||
22 | Create block device | |
23 | ||
24 | - `chardev(dev)` | |
25 | ||
26 | Create character device | |
27 | ||
28 | - `erase(path)` | |
29 | ||
30 | Erase file/directory with `remove()`. Errors on `stderr` | |
31 | ||
32 | - `erasef(fmt, ...)` | |
33 | ||
34 | Like `erase()` but takes a formatted printf-like string as argument. | |
35 | ||
36 | - `makedir(path)` | |
37 | ||
38 | Create directory, like `mkdir()`. Errors on `stderr` | |
39 | ||
40 | - `makefifo(path)` | |
41 | ||
42 | Create a FIFO, like `mkfifo()`. Errors on `stderr` | |
43 | ||
44 | - `min(a,b)`/`max(a,b)` | |
45 | ||
46 | These macros take care to avoid double evaluation. | |
47 | ||
48 | - `touch(path)` | |
49 | ||
50 | Create a file, or update mtime. Errors on `stderr` | |
51 | ||
52 | - `touchf(fmt, ...)` | |
53 | ||
54 | Like `touch()` but takes a formatted printf-like string as argument. | |
55 | ||
56 | - `S_ISEXEC(mode_t m)` | |
57 | ||
58 | Mysteriously missing from GLIBC | |
59 | ||
60 | - `ISCLR(word,bit)` | |
61 | ||
62 | Is bit in (integer) word cleared? | |
63 | ||
64 | - `ISSET(word,bit)` | |
65 | ||
66 | Is bit in (integer) word set? | |
67 | ||
68 | - `ISOTHER(word,bit)` | |
69 | ||
70 | Are any other bits, except bit, in (integer) word set? | |
71 | ||
72 | - `SETBIT(word,bit)` | |
73 | ||
74 | Set bit in (integer) word. | |
75 | ||
76 | - `CLRBIT(word,bit)` | |
77 | ||
78 | Clear bit in (integer) word. | |
79 | ||
80 | - `NELEMS(array)` | |
81 | ||
82 | Returns the number of elements in an array. From the great book, The | |
83 | Practice of Programming, by Kernighan and Pike. | |
84 | ||
85 | ||
86 | Generic Functions | |
87 | ----------------- | |
88 | ||
89 | - `chomp(str)` | |
90 | ||
91 | Perl like chomp function, chop off last char if newline. | |
92 | ||
93 | - `copyfile(src, dst, len, opt)` | |
94 | ||
95 | Like the shell `cp(1)` and `dd(1),`, can also copy symlinks and | |
96 | preserve the mtime of the source file. The opt argument can be | |
97 | a mask of: | |
98 | ||
99 | - `LITE_FOPT_COPYFILE_SYM (0x01)` | |
100 | - `LITE_FOPT_KEEP_MTIME (0x02)` | |
101 | ||
102 | In releases prior to v2.0 the opt argument was called `symlink`. | |
103 | The APIs are 100% compatible if the value `1` was used to enable | |
104 | the symlink option. | |
105 | ||
106 | - `dir(dir, ext, filter, list, strip)` | |
107 | ||
108 | Wrapper for `scandir()` with optional filter. Returns a list of | |
109 | names: files and directories that must be freed after use. See | |
110 | the unit test for an example, or take a look at `glob(3)`, it's | |
111 | probably what you want anyway. | |
112 | ||
113 | - `fcopyfile(src, dst)` | |
114 | ||
115 | Like `copyfile()` but uses already open `FILE *` pointers. Copies | |
116 | from current file positions to current file positions until EOF. | |
117 | ||
118 | - `fexist(file)` | |
119 | ||
120 | Check for the existence of a file, returns True(1) or False(0). | |
121 | ||
122 | - `fisdir(path)` | |
123 | ||
124 | Check for the existence of a directory, returns True(1) or False(0). | |
125 | ||
126 | - `fopenf(mode, fmt, ...)` | |
127 | ||
128 | Like `fopen()`, but takes a formatted string as argument. This | |
129 | greatly simplifies operations that usually consist of composing a | |
130 | filename from parts into a dynamic buffer before actually opening | |
131 | the file. | |
132 | ||
133 | > **Notice:** the swapped order of `pathname` and `mode`! | |
134 | ||
135 | - `fremove(fmt, ...)` | |
136 | ||
137 | Like `remove()`, but takes a formatted string as argument. This | |
138 | greatly simplifies operations that usually consist of composing a | |
139 | filename from parts into a dynamic buffer before actually removing | |
140 | the file. | |
141 | ||
142 | - `fsendfile(src, dst, len)` | |
143 | ||
144 | Copy data between file streams, very similar to `fcopyfile()`, but | |
145 | `dst` is allowed to be `NULL` to be able to read and discard `len` | |
146 | bytes from `src`. | |
147 | ||
148 | - `ifconfig(ifname, addr, mask, up)` | |
149 | ||
150 | Basic ifconfig like operations on an interface. Only supports IPv4 | |
151 | addresses. Note that mask is not CIDR notation. | |
152 | ||
153 | - `lfopen(file, sep)`, `lfclose(lf)` | |
154 | ||
155 | LITE file API for parsing UNIX style configuration files like | |
156 | `/etc/protocols` and `/etc/services`. | |
157 | ||
158 | - `lftok(lf)` | |
159 | ||
160 | Read tokens, delimited by `sep`, from file opened with `lfopen()`. | |
161 | ||
162 | - `lfgetkey(lf, key)` | |
163 | ||
164 | Find `key` in file opened with `lfopen()`, return value/argument. | |
165 | ||
166 | - `lfgetint(lf, key)` | |
167 | ||
168 | Wrapper for `lfgetkey()`, returns positive integer value to `key`, | |
169 | or `-1` if `key` is not found. | |
170 | ||
171 | - `fgetint(file, sep, key)` | |
172 | ||
173 | Wrapper for `lfopen()`, `lfgetint()`, and `lfclose()`. Useful for | |
174 | when only reading a single `key` from a file. | |
175 | ||
176 | - `makepath(dir)` | |
177 | ||
178 | Create all components of the specified directory. | |
179 | ||
180 | - `mkpath(dir, mode)` | |
181 | ||
182 | Like `makepath()`, but also takes a `mode_t` permission mode argument. | |
183 | ||
184 | - `fmkpath(mode, fmt, ...)` | |
185 | ||
186 | Like `mkpath()`, but takes a formatted string as argument. | |
187 | ||
188 | > **Notice:** the swapped order of `pathname` and `mode`! | |
189 | ||
190 | - `movefile(src, dst)` | |
191 | ||
192 | Like `copyfile()`, but renames `src` to `dst`, or recreates symlink | |
193 | with the `dst` name. On successful operation the source is removed | |
194 | and the function returns POSIX OK (0). | |
195 | ||
196 | - `pidfile(name)` | |
197 | ||
198 | Create a daemon PID file using either the `name` as a full path, if | |
199 | `name` starts with `/`, or in `_PATH_VARRUN` using `name` as the | |
200 | basename of the application. If `name` is `NULL`, then `__progname` | |
201 | is used as the basename. The resulting file name is available to the | |
202 | user as a read-only pointer: | |
203 | ||
204 | extern char *__pidfile_name; | |
205 | ||
206 | Use this function to create a PID file for your daemon when it is | |
207 | ready to receive signals. A client application may poll for the | |
208 | existence of this file, so make sure to have your signal handlers | |
209 | properly setup before calling this function. | |
210 | ||
211 | The PID file is removed when the program exits, using an `atexit()` | |
212 | handler. However, depending on how the program terminates the file | |
213 | may still exist even though the program is no longer running. | |
214 | ||
215 | Calling this function multiple times updates the mtime of the file. | |
216 | Only one `atexit()` handler is created, regardless of the amount of | |
217 | times the function is called. If the file is removed, subsequent | |
218 | calls to this function will recreate the file. | |
219 | ||
220 | See below for a link to OpenBSD man page. | |
221 | ||
222 | - `pidfile_read(pidfile)` | |
223 | ||
224 | Read PID from pid file created by `pidfile()`. | |
225 | ||
226 | - `pidfile_signal(pidfile, signal)` | |
227 | ||
228 | Send signal to PID found in pid file created by `pidfile()`. | |
229 | ||
230 | - `progress(percent, max_width)` | |
231 | ||
232 | Simple ASCII progress bar with a spinner. Start it with `percent=0` | |
233 | and set the `max_width=chars` to indicate width of the progress bar. | |
234 | Called multiple times with the same percentage value cause spinner to | |
235 | spin. | |
236 | ||
237 | - `rsync(src, dst, opt, *filter())` | |
238 | ||
239 | Very simple `rsync()` to copy files and directories recursively. It | |
240 | supports pruning files from the destination tree that do not exist in | |
241 | the source tree and preserving the mtime of the source files. The opt | |
242 | argument can be a mask of: | |
243 | ||
244 | - `LITE_FOPT_RSYNC_DELETE (0x01)` | |
245 | - `LITE_FOPT_KEEP_MTIME (0x02)` | |
246 | ||
247 | In releases prior to v2.0 the argument controlling pruning was called | |
248 | `delete`, it is now called `opt`. The APIs are 100% compatible if the | |
249 | value `1` was used. | |
250 | ||
251 | - `strmatch(str, list)`, `strnmatch(str, list, len)` | |
252 | ||
253 | Find matching string in an array of strings. Returns index in array on | |
254 | match, or `-1` on error or not found. `strnmatch()` takes an extra arg | |
255 | to compare only `len` number of characters from `str`. | |
256 | ||
257 | - `strtrim(str)` | |
258 | ||
259 | Trims a string from any leading and trailing white-space, returns the | |
260 | trimmed result in the same buffer. | |
261 | ||
262 | - `systemf(fmt, ...)` | |
263 | ||
264 | Like `system()`, but takes a formatted string as argument. This | |
265 | greatly simplifies operations that usually consist of composing a | |
266 | command from parts into a dynamic buffer before calling it. | |
267 | ||
268 | - `telnet_open(addr, port), telnet_close(ctx), telnet_expect(ctx, script, output)` | |
269 | ||
270 | Poor mans telnet expect in C. Opens connection to a Telnet service; | |
271 | FTP, Telnet, similar, and run an expect-like script. | |
272 | ||
273 | - `telnet_session(addr, port, script output)` | |
274 | ||
275 | Wrapper for the above three in one API. | |
276 | ||
277 | - `tempfile()` | |
278 | ||
279 | Secure replacement for `tmpfile()`. Creates an invisible temporary | |
280 | file in `/tmp` that is removed when the returned `FILE` pointer is | |
281 | closed. | |
282 | ||
283 | **Note:** Requires Linux v3.11, or later, will fall back to the old | |
284 | and unsafe `tmpfile()` on older systems. | |
285 | ||
286 | - `truncatef(length, fmt, ...)` | |
287 | ||
288 | Like `truncate()`, but takes a formatted string as argument. This | |
289 | simplifies some operations when the filename otherwise have to be | |
290 | composed from parts into a separate array before calling the real | |
291 | function. | |
292 | ||
293 | - `which(cmd)`, `whichp(cmd)` | |
294 | ||
295 | C implementation of UNIX which(1). Returns a malloc'ed string with the | |
296 | full path to `cmd` on success, otherwise `NULL`. | |
297 | ||
298 | `whichp()` is a predicate function, returns `TRUE` or `FALSE`. | |
299 | ||
300 | **Note:** `which("/bin/ps aux")` will return `/bin/ps`, or `TRUE`, | |
301 | provided of course `/bin/ps` exists. | |
302 | ||
303 | - `yorn(fmt, ...)` | |
304 | ||
305 | Pose a question to user, appended with `(y/N)?`, returns `TRUE` for | |
306 | yes (both `y` and `Y` are handled) and `FALSE` for everything else. | |
307 | ||
308 | ||
309 | GNU Functions | |
310 | ------------- | |
311 | ||
312 | The following are useful GNU functions, that do not exist on *BSD, and | |
313 | some other platforms. | |
314 | ||
315 | - `strdupa(str)` | |
316 | ||
317 | http://man7.org/linux/man-pages/man3/strdupa.3.html | |
318 | ||
319 | - `strndupa(str)` | |
320 | ||
321 | http://man7.org/linux/man-pages/man3/strndupa.3.html | |
322 | ||
323 | - `strnlen(str, lim)` | |
324 | ||
325 | http://man7.org/linux/man-pages/man3/strnlen.3.html | |
326 | ||
327 | ||
328 | OpenBSD/NetBSD/FreeBSD Functions | |
329 | -------------------------------- | |
330 | ||
331 | The following are popular functions and highly useful macros from the | |
332 | *BSD world of UNIX that are sadly missing on Linux. | |
333 | ||
334 | - `fparseln(fp, *len, *lineno, delim, flags)` | |
335 | ||
336 | http://man.openbsd.org/OpenBSD-current/man3/fparseln.3 | |
337 | ||
338 | - `pidfile(basename)` | |
339 | ||
340 | http://www.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man3/pidfile.3 | |
341 | ||
342 | **Note:** the version of `pidfile()` in -lite has been extended to | |
343 | handle it being called multiple times, i.e. to not create multiple | |
344 | `atexit()` handlers, and also to export a few internal paths: | |
345 | ||
346 | - `__pidfile_path`: prefix path, default `_PATH_VARRUN`. Notice the | |
347 | trailing slash requirement if you want to override it! | |
348 | - `__pidfile_name`: full path to PID file , similar to `__progname`. | |
349 | See previous section for details. | |
350 | ||
351 | - `reallocarray(ptr, nmemb, size)` | |
352 | ||
353 | http://man.openbsd.org/OpenBSD-current/man3/reallocarray.3 | |
354 | ||
355 | - `strlcpy(dst, src, len)` | |
356 | ||
357 | http://www.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man3/strlcpy.3 | |
358 | ||
359 | - `strlcat(dst, src, len)` | |
360 | ||
361 | http://www.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man3/strlcat.3 | |
362 | ||
363 | - `strtonum()` | |
364 | ||
365 | http://www.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man3/strtonum.3 | |
366 | ||
367 | - `sys/queue.h` API | |
368 | ||
369 | http://www.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man3/LIST_EMPTY.3 | |
370 | ||
371 | - `sys/tree.h` API | |
372 | ||
373 | Niels Provos' famous splay and red-black tree implementation. | |
374 | ||
375 | http://www.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man3/SPLAY_FOREACH.3 |
828 | 828 | # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING |
829 | 829 | # Note: If this tag is empty the current directory is searched. |
830 | 830 | |
831 | INPUT = @top_srcdir@/src/ @top_srcdir@/README.md | |
831 | INPUT = @top_srcdir@/src/ @top_srcdir@/README.md @top_srcdir@/doc/API.md | |
832 | 832 | |
833 | 833 | # This tag can be used to specify the character encoding of the source files |
834 | 834 | # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses |