Annotation of embedaddon/pimd/libite/README.md, revision 1.1.1.1
1.1 misho 1: -lite | Frog DNA, basically
2: ===========================
3: [![Travis Status][]][Travis]
4:
5: Libite is a lightweight library of *frog DNA*. It can be used to fill
6: the gaps in any dinosaur project. It holds useful functions and macros
7: developed by both [Finit][1] and the [OpenBSD][2] project. Most notably
8: the string functions: [strlcpy(3)][3], [strlcat(3)][3] and the highly
9: useful *BSD [sys/queue.h][4] and [sys/tree.h][7] API's.
10:
11: Libite is the frog DNA missing in GNU libc. However, -lite does not aim
12: to become another [GLIB][5]! One noticeable gap in GLIBC is the missing
13: `_SAFE` macros in tje BSD `sys/queue.h` API — highly recommended
14: when traversing lists to delete/free nodes.
15:
16: The code is open sourced under a mix of the [MIT/X11 license][MIT], the
17: [ISC license][ISC] used by OpenBSD, and [BSD licenses][BSD], all of them
18: are extremely liberal and can be used freely in proprietary software if
19: needed.
20:
21: For an introduction to why Libite happened, and how you can use it, see
22: [this blog post][6].
23:
24:
25: Using -lite
26: -----------
27:
28: Libite is by default installed as a library and a set of include files.
29: To prevent clashing with include files of the same name -lite employs a
30: include file namespace `lite/`, which is recommended to use in your
31: applications:
32:
33: #include <lite/lite.h>
34: #include <lite/conio.h>
35: #include <lite/queue.h>
36: #include <lite/tree.h>
37:
38: The output from the `pkg-config` tool holds no surprises:
39:
40: $ pkg-config --libs --static --cflags libite
41: -I/usr/local/include -L/usr/local/lib -lite @LTLIBINTL@
42:
43:
44: Helper Macros
45: -------------
46:
47: - `atonum(str)`
48:
49: Convert string to natural number, works for 32-bit non-negative
50: integers. Returns -1 on error. (Uses `strtonum()` internally.)
51:
52: - `blkdev(dev)`
53:
54: Create block device
55:
56: - `chardev(dev)`
57:
58: Create character device
59:
60: - `erase(path)`
61:
62: Erase file/directory with `remove()`. Errors on stderr
63:
64: - `makedir(path)`
65:
66: Create directory, like `mkdir()`. Errors on stderr
67:
68: - `makefifo(path)`
69:
70: Create a FIFO, like `mkfifo()`. Errors on stderr
71:
72: - `min(a,b)`/`max(a,b)`
73:
74: These macros take care to avoid double evaluation.
75:
76: - `touch(path)`
77:
78: Create a file, or update mtime. Errors on stderr
79:
80: - `S_ISEXEC(mode_t m)`
81:
82: Mysteriously missing from GLIBC
83:
84: - `ISCLR(word,bit)`
85:
86: Is bit in (integer) word cleared?
87:
88: - `ISSET(word,bit)`
89:
90: Is bit in (integer) word set?
91:
92: - `ISOTHER(word,bit)`
93:
94: Is any other bits, except bit, in (integer) word set?
95:
96: - `SETBIT(word,bit)`
97:
98: Set bit in (integer) word.
99:
100: - `CLRBIT(word,bit)`
101:
102: Clear bit in (integer) word.
103:
104: - `NELEMS(array)`
105:
106: Returns the number of elements in an array. From the great book, The
107: Practice of Programming, by Kernighan and Pike.
108:
109: - `UNUSED(var)`
110:
111: Shorter and more readable version of `var __attribute__ ((unused))`
112:
113:
114: Generic Functions
115: -----------------
116:
117: - `chomp(str)`
118:
119: Perl like chomp function, chop off last char if newline.
120:
121: - `copyfile(src, dst, len, symlink)`
122:
123: Like the shell `cp(1)` and `dd(1),` can also create symlinks.
124:
125: - `dir(dir, ext, filter, list, strip)`
126:
127: Wrapper for `scandir()` with optional filter. Returns a list of
128: names: files and directories that must be freed after use. See
129: the unit test at the bottom for an example.
130:
131: - `fcopyfile(src, dst)`
132:
133: Like `copyfile()` but uses already open `FILE *` pointers. Copies
134: from current file positions to current file positions until EOF.
135:
136: - `fexist(file)`
137:
138: Check for the existance of a file, returns True(1) or False(0).
139:
140: - `fisdir(path)`
141:
142: Check for the existance of a directory, returns True(1) or False(0).
143:
144: - `fmode(file)`
145:
146: Returns the `mode_t` bits of a file or directory.
147:
148: - `fsendfile(src, dst, len)`
149:
150: Copy data between file streams, very similar to `fcopyfile()`, but
151: `dst` is allowed to be `NULL` to be able to read and discard `len`
152: bytes from `src`.
153:
154: - `ifconfig(ifname, addr, mask, up)`
155:
156: Basic ifconfig like operations on an interface. Only supports IPv4
157: adresses. Note that mask is not CIDR notation.
158:
159: - `lfopen(file, sep)`, `lfclose(lf)`
160:
161: API for parsing UNIX style configuration files like `/etc/protocols`
162: and `/etc/services`.
163:
164: - `lftok(lf)`
165:
166: Read tokens, delimeted by `sep`, from file opened with `lfopen()`.
167:
168: - `lfgetkey(lf, key)`
169:
170: Find `key` in file opened with `lfopen()`, return value/argument.
171:
172: - `lfgetint(lf, key)`
173:
174: Wrapper for `lfgetkey()`, returns positive integer value to `key`,
175: or `-1` if `key` is not found.
176:
177: - `fgetint(file, sep, key)`
178:
179: Wrapper for `lfopen()`, `lfgetint()`, and `lfclose()`. Useful for
180: when only reading a single `key` from a file.
181:
182: - `makepath(dir)`
183:
184: Create all components of the specified directory.
185:
186: - `mkpath(dir, mode)`
187:
188: Like `makepath()`, but also takes a `mode_t` permission mode argument.
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(basename)`
197:
198: Create a daemon PID file in `_PATH_VARRUN` using either `basename` or,
199: if `basename` is `NULL`, `__progname`. The resulting file name is
200: available to the user as a read-only pointer:
201:
202: extern char *__pidfile_name;
203:
204: Use this function to create a PID file for your daemon when it is
205: ready to receive signals. A client application may poll for the
206: existence of this file, so make sure to have your signal handlers
207: properly setup before calling this function.
208:
209: The pidfile is removed when the program exits, using an `atexit()`
210: handler. However, depending on how the program terminates the file
211: may still exist even though the program is no longer running. This
212: is only a problem for clients.
213:
214: Calling this function multiple times updates the mtime of the file.
215: Only one `atexit()` handler is created, regardless of the amount of
216: times the function is called.
217:
218: See below for link to OpenBSD man page.
219:
220: - `pidfile_read(pidfile)`
221:
222: Read PID from pid file created by `pidfile()`.
223:
224: - `pidfile_signal(pidfile, signal)`
225:
226: Send signal to PID found in pid file created by `pidfile()`.
227:
228: - `progress(percent, max_width)`
229:
230: Simple ASCII progress bar with a spinner. Start it with `percent=0`
231: and set the `max_width=chars` to indicate width of the progress bar.
232: Called multiple times with the same percentage value cause spinner to
233: spin.
234:
235: - `rsync(src, dst, delete, *filter())`
236:
237: Very simple `rsync()` to copy files files and directories
238: recursively.
239:
240: - `tempfile()`
241:
242: Secure replacement for `tmpfile()`. Creates an invisible temporary
243: file in `/tmp` that is removed when the returned `FILE` pointer is
244: closed.
245:
246: **Note:** Requires Linux v3.11, or later, will fall back to the old
247: and unsafe `tmpfile()` on older systems.
248:
249: - `tree(path, show_perms)`
250:
251: Very simple `/bin/tree` replacement. Draw ASCII tree of `path`, with
252: optional listing of file and directory permissions if `show_perms` is
253: set. The `path` argument should be a directory.
254:
255:
256: OpenBSD Functions
257: -----------------
258:
259: The following are popular OpenBSD functions and highly useful macros.
260:
261: - `pidfile(basename)`
262:
263: http://www.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man3/pidfile.3
264:
265: **Note:** this version of `pidfile()` has been extended to handle it
266: being called multiple times, and also to export the path to the PID
267: file `__pidfile_name`, similar to `__progname`. See previous section
268: for details.
269:
270: - `strlcpy(dst, src, len)`
271:
272: http://www.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man3/strlcpy.3
273:
274: - `strlcat(dst, src, len)`
275:
276: http://www.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man3/strlcat.3
277:
278: - `strtonum()`
279:
280: http://www.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man3/strtonum.3
281:
282: - `sys/queue.h` API
283:
284: http://www.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man3/LIST_EMPTY.3
285:
286: - `sys/tree.h` API
287:
288: Niels Provos' famous splay and red-black tree implementation.
289:
290: http://www.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man3/SPLAY_FOREACH.3
291:
292:
293: Build & Install
294: ---------------
295:
296: The library is built for and developed on GNU/Linux systems as a light
297: weight utility library. Libite (LITE) employs the de facto standard GNU
298: configure and build system:
299:
300: ./configure
301: make all
302: make install
303:
304:
305: TODO
306: ----
307:
308: - Improve documentation, possibly use kdoc or gdoc2 to generate docs from API.
309: - Continuously, update OpenBSD functions/macros.
310:
311: [1]: https://github.com/troglobit/finit
312: [2]: http://www.openbsd.org/
313: [3]: http://www.openbsd.org/cgi-bin/man.cgi?query=strlcpy
314: [4]: http://www.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man3/LIST_EMPTY.3
315: [5]: https://developer.gnome.org/glib/
316: [6]: http://troglobit.com/blog/2015/07/02/howto-using-lite-with-a-git-based-application/
317: [7]: http://www.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man3/SPLAY_FOREACH.3
318: [MIT]: https://en.wikipedia.org/wiki/MIT_License
319: [ISC]: https://en.wikipedia.org/wiki/ISC_license
320: [BSD]: https://en.wikipedia.org/wiki/BSD_licenses
321: [Travis]: https://travis-ci.org/troglobit/libite
322: [Travis Status]: https://travis-ci.org/troglobit/libite.png?branch=master
323:
324: <!--
325: -- Local Variables:
326: -- mode: markdown
327: -- End:
328: -->
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to README.md CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / pimd / libite