Mercurial > irccd

annotate man/libirccd-util.3 @ 1181:309dab921cfb

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
misc: merge from stable-4
author David Demelier <markand@malikania.fr>
date Wed, 18 Jan 2023 20:35:35 +0100
parents c165e975f144
children 1845a0509a93
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
1013
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
1 .\"
1136
f06e9761cc90 misc: update copyright years
David Demelier <markand@malikania.fr>
parents: 1065
diff changeset
2 .\" Copyright (c) 2013-2022 David Demelier <markand@malikania.fr>
1013
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
3 .\"
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
4 .\" Permission to use, copy, modify, and/or distribute this software for any
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
5 .\" purpose with or without fee is hereby granted, provided that the above
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
6 .\" copyright notice and this permission notice appear in all copies.
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
7 .\"
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
8 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
9 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
10 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
11 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
12 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
13 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
14 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
15 .\"
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
16 .Dd @IRCCD_MAN_DATE@
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
17 .Dt LIBIRCCD-UTIL 3
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
18 .Os
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
19 .\" NAME
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
20 .Sh NAME
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
21 .Nm libirccd-util
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
22 .Nd various utilities
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
23 .\" SYNOPSIS
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
24 .Sh SYNOPSIS
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
25 .In irccd/util.h
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
26 .Fd #define IRC_UTIL_SIZE(array)
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
27 .Ft void *
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
28 .Fn irc_util_malloc "size_t size"
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
29 .Ft void *
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
30 .Fn irc_util_calloc "size_t n, size_t width"
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
31 .Ft void *
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
32 .Fn irc_util_realloc "void *ptr, size_t size"
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
33 .Ft void *
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
34 .Fn irc_util_reallocarray "void *ptr, size_t n, size_t width"
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
35 .Ft char *
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
36 .Fn irc_util_strdup "const char *src"
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
37 .Ft char *
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
38 .Fn irc_util_strndup "const char *src, size_t len"
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
39 .Ft void *
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
40 .Fn irc_util_memdup "const void *ptr, size_t size"
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
41 .Ft char *
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
42 .Fn irc_util_basename "const char *path"
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
43 .Ft char *
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
44 .Fn irc_util_dirname "const char *path"
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
45 .Ft size_t
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
46 .Fn irc_util_split "char *str, const char **args, size_t max, char delimiter"
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
47 .Ft char *
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
48 .Fn irc_util_printf "char *str, size_t strsz, const char *fmt, ..."
1065
d8db515adbd4 misc: remove usage of BSD errx?() functions
David Demelier <markand@malikania.fr>
parents: 1013
diff changeset
49 .Ft noreturn void
d8db515adbd4 misc: remove usage of BSD errx?() functions
David Demelier <markand@malikania.fr>
parents: 1013
diff changeset
50 .Fn irc_util_die "const char *fmt, ..."
1013
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
51 .\" DESCRIPTION
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
52 .Sh DESCRIPTION
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
53 This header provides several function for memory management and basic string
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
54 handling.
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
55 .Pp
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
56 Every memory allocation function exits on error and are usually recommended for
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
57 small piece of data that should never fail and where the out of memory
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
58 consequence is unrecoverable. They are not recommended for reading large piece
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
59 of data where the standard C functions are preferred in this place.
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
60 .Pp
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
61 The
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
62 .Fn IRC_UTIL_SIZE
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
63 macro expands the compile time size of the argument
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
64 .Fa array
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
65 which must be constant array.
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
66 .Pp
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
67 The
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
68 .Fn irc_util_malloc ,
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
69 .Fn irc_util_calloc ,
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
70 .Fn irc_util_realloc ,
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
71 are exactly the same as the standard C functions except they write an error
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
72 message if allocation fails.
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
73 .Pp
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
74 The
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
75 .Fn irc_util_reallocarray
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
76 function is similar to the OpenBSD
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
77 .Fn reallocarray
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
78 function which should reallocate the pointer
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
79 .Fa ptr
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
80 of
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
81 .Fa n
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
82 elements of given
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
83 .Fa width
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
84 size each. It always returns the new region otherwise writes an error message
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
85 and exits.
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
86 .Pp
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
87 The
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
88 .Fn irc_util_strdup ,
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
89 .Fn irc_util_strndup
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
90 are similar to the POSIX functions but also write an error message if fails to
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
91 allocate the required size.
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
92 .Pp
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
93 The
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
94 .Fn irc_util_memdup
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
95 function allocate
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
96 .Fa size
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
97 bytes and copy the verbatim
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
98 .Fa ptr
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
99 into a new region returned.
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
100 .Pp
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
101 The
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
102 .Fn irc_util_basename
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
103 and
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
104 .Fn irc_util_dirname
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
105 are similar to the POSIX function of the same names but they don't modify the
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
106 original
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
107 .Fa path
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
108 argument and returns an independent string instead. The returned string is
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
109 static to each function and will be overwritten by subsequent calls.
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
110 .Pp
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
111 The
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
112 .Fn irc_util_split
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
113 function tokenize the
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
114 .Fa str
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
115 string input and store them into the array of string
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
116 .Fa args
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
117 according to the
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
118 .Fa delimiter .
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
119 The array
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
120 .Fa args
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
121 must be at least
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
122 .Fa max
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
123 long to store every tokens. The original
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
124 .Fa str
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
125 argument will be modified by this function to avoid dynamic allocation and as
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
126 such never fails. If the number of tokens parsed was greater than
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
127 .Fa max
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
128 then the last value is left
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
129 .Dq uncut
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
130 otherwise if the number of tokens is smaller than
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
131 .Fa max
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
132 then the
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
133 .Fa args
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
134 values will not be initialized. The user must make sure to initialize the array
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
135 itself or to check the return value of this function.
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
136 .Pp
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
137 Example,
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
138 .Fa max
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
139 argument is smaller than available tokens.
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
140 .Bd -literal
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
141 char str[] = "hello world what's up?";
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
142 const char *args[3] = {0};
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
143
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
144 /* Will return 3. */
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
145 irc_util_split(str, args, 3, ' ');
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
146 /* args[0] == "hello" */
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
147 /* args[1] == "world" */
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
148 /* args[2] == "what's up?" */
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
149 .Ed
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
150 .Pp
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
151 Now, the same example while requesting more token than available.
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
152 .Bd -literal
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
153 char str[] = "hello world what's up?";
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
154 const char *args[16] = {0};
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
155
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
156 /* Will return 4. */
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
157 irc_util_split(str, args, 16, ' ');
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
158 /* args[0] == "hello" */
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
159 /* args[1] == "world" */
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
160 /* args[2] == "what's" */
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
161 /* args[3] == "up?" */
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
162 .Ed
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
163 .Pp
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
164 In the above case, arguments from 4 to 15 are set to NULL because we explicitly
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
165 did before calling
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
166 .Fn irc_util_split .
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
167 .Pp
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
168 The
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
169 .Fn irc_util_printf
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
170 is similar to standard C
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
171 .Xr snprintf 3
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
172 signature except that it returns the
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
173 .Fa str
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
174 argument for convenience.
1065
d8db515adbd4 misc: remove usage of BSD errx?() functions
David Demelier <markand@malikania.fr>
parents: 1013
diff changeset
175 .Pp
d8db515adbd4 misc: remove usage of BSD errx?() functions
David Demelier <markand@malikania.fr>
parents: 1013
diff changeset
176 The
d8db515adbd4 misc: remove usage of BSD errx?() functions
David Demelier <markand@malikania.fr>
parents: 1013
diff changeset
177 .Fn irc_util_die
d8db515adbd4 misc: remove usage of BSD errx?() functions
David Demelier <markand@malikania.fr>
parents: 1013
diff changeset
178 function is a function that writes a message format using the same signature as
d8db515adbd4 misc: remove usage of BSD errx?() functions
David Demelier <markand@malikania.fr>
parents: 1013
diff changeset
179 .Xr printf 3
d8db515adbd4 misc: remove usage of BSD errx?() functions
David Demelier <markand@malikania.fr>
parents: 1013
diff changeset
180 and exits with code 1. It is meant to be used when the program is unable to
d8db515adbd4 misc: remove usage of BSD errx?() functions
David Demelier <markand@malikania.fr>
parents: 1013
diff changeset
181 recover from a fatal error and should be avoided in library code.
1013
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
182 .\" RETURN VALUES
1065
d8db515adbd4 misc: remove usage of BSD errx?() functions
David Demelier <markand@malikania.fr>
parents: 1013
diff changeset
183 .Sh RETURN VALUES
1013
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
184 All memory functions
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
185 .Fn irc_util_malloc ,
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
186 .Fn irc_util_calloc ,
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
187 .Fn irc_util_realloc ,
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
188 .Fn irc_util_reallocarray ,
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
189 .Fn irc_util_strdup ,
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
190 .Fn irc_util_strndup
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
191 and
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
192 .Fn irc_util_memdup
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
193 never return NULL.
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
194 .\" SEE ALSO
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
195 .Sh SEE ALSO
efeb73a9918b man: add C API for what is mostly stabilized
David Demelier <markand@malikania.fr>
parents:
diff changeset
196 .Xr libirccd 3
1137
c165e975f144 man: improvements
David Demelier <markand@malikania.fr>
parents: 1136
diff changeset
197 .\" AUTHORS
c165e975f144 man: improvements
David Demelier <markand@malikania.fr>
parents: 1136
diff changeset
198 .Sh AUTHORS
c165e975f144 man: improvements
David Demelier <markand@malikania.fr>
parents: 1136
diff changeset
199 The
c165e975f144 man: improvements
David Demelier <markand@malikania.fr>
parents: 1136
diff changeset
200 .Nm irccd
c165e975f144 man: improvements
David Demelier <markand@malikania.fr>
parents: 1136
diff changeset
201 daemon was written by
c165e975f144 man: improvements
David Demelier <markand@malikania.fr>
parents: 1136
diff changeset
202 .An David Demelier Aq Mt markand@malikania.fr .