annotate libbuf.3 @ 19:cf6a2b8642c1

misc: added tag 0.2.0 for changeset 7f5b3f035bef
author David Demelier <markand@malikania.fr>
date Wed, 16 Dec 2020 16:20:43 +0100
parents 3665a56a00aa
children 939fe74cd80a
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
0
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
1 .\"
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
2 .\" libbuf.3 -- simple string buffer for C
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
3 .\"
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
4 .\" Copyright (c) 2019-2020 David Demelier <markand@malikania.fr>
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
5 .\"
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
6 .\" Permission to use, copy, modify, and/or distribute this software for any
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
7 .\" purpose with or without fee is hereby granted, provided that the above
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
8 .\" copyright notice and this permission notice appear in all copies.
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
9 .\"
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
11 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
12 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
13 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
14 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
15 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
16 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
17 .\"
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
18 .Dd October 29, 2019-2020
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
19 .Dt LIBBUF 3
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
20 .Os
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
21 .\" NAME
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
22 .Sh NAME
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
23 .Nm libbuf
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
24 .Nd minimal dynamic string library
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
25 .\" LIBRARY
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
26 .Sh LIBRARY
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
27 libbuf (libbuf, -lbuf)
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
28 .\" SYNOPSIS
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
29 .Sh SYNOPSIS
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
30 .In buf.h
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
31 .Ft void
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
32 .Fn buf_clear "struct buf *b"
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
33 .Ft bool
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
34 .Fn buf_dup "struct buf *b" "const struct buf *src"
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
35 .Ft void
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
36 .Fn buf_erase "struct buf *b" "size_t pos" "size_t count"
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
37 .Ft void
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
38 .Fn buf_finish "struct buf *b"
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
39 .Ft bool
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
40 .Fn buf_init "struct buf *b"
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
41 .Ft bool
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
42 .Fn buf_printf "struct buf *b" "const char *fmt" "..."
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
43 .Ft bool
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
44 .Fn buf_putc "struct buf *b" "char c"
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
45 .Ft bool
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
46 .Fn buf_puts "struct buf *b" "const char *s"
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
47 .Ft bool
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
48 .Fn buf_reserve "struct buf *b" "size_t desired"
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
49 .Ft bool
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
50 .Fn buf_resize "struct buf *b" "size_t desired" "char c"
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
51 .Ft bool
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
52 .Fn buf_shrink "struct buf *b"
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
53 .Ft bool
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
54 .Fn buf_sub "struct buf *b" "const struct buf *src" "size_t pos" "size_t count"
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
55 .Ft bool
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
56 .Fn buf_vprintf "struct buf *b" "const char *fmt" "va_list ap"
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
57 .\" DESCRIPTION
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
58 .Sh DESCRIPTION
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
59 The
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
60 .Nm
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
61 library is a general purpose string library for C.
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
62 .Pp
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
63 It automatically expands storage as required.
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
64 It will first try to allocate twice as the current storage space until enough
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
65 room is available or in case it would exceed maximum storage it will grow with
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
66 minimal required storage.
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
67 .Pp
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
68 Every function expects as first argument a buffer to work with which can never
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
69 be NULL.
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
70 .Pp
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
71 The
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
72 .Vt "struct buf"
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
73 is a publicly exposed structure with the following fields:
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
74 .Bl -tag -width "capacity"
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
75 .It Va data
2
3665a56a00aa man: data field isn't const
David Demelier <markand@malikania.fr>
parents: 0
diff changeset
76 .Va (char *)
0
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
77 The current NUL-terminated C string, maybe NULL if the buffer isn't initialized.
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
78 .It Va length
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
79 .Va (size_t)
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
80 The data length.
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
81 .It Va capacity
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
82 .Va (size_t)
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
83 The real capacity available for writing characters (not including NUL). A
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
84 capacity of 5 means you can write 5 characters plus the NUL terminator without
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
85 reallocating.
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
86 .El
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
87 .\" SEE ALSO
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
88 .Sh SEE ALSO
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
89 .Xr buf_clear 3 ,
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
90 .Xr buf_dup 3 ,
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
91 .Xr buf_erase 3 ,
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
92 .Xr buf_finish 3 ,
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
93 .Xr buf_init 3 ,
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
94 .Xr buf_printf 3 ,
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
95 .Xr buf_putc 3 ,
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
96 .Xr buf_puts 3 ,
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
97 .Xr buf_reserve 3 ,
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
98 .Xr buf_resize 3 ,
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
99 .Xr buf_shrink 3 ,
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
100 .Xr buf_sub 3 ,
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
101 .Xr buf_vprintf 3
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
102 .\" AUTHORS
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
103 .Sh AUTHORS
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
104 The
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
105 .Nm
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
106 library was written by
b1991ee4451d misc: initial import
David Demelier <markand@malikania.fr>
parents:
diff changeset
107 .An David Demelier <markand@malikania.fr>