BIND: update vendor tree to 9.5.2-P2
[dragonfly.git] / contrib / bind / lib / isc / include / isc / string.h
CommitLineData
bbbf71a3
JL
1/*
2 * Copyright (C) 2004-2007 Internet Systems Consortium, Inc. ("ISC")
3 * Copyright (C) 2000, 2001, 2003 Internet Software Consortium.
4 *
5 * Permission to use, copy, modify, and/or distribute this software for any
6 * purpose with or without fee is hereby granted, provided that the above
7 * copyright notice and this permission notice appear in all copies.
8 *
9 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
10 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
11 * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
12 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
13 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
14 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
15 * PERFORMANCE OF THIS SOFTWARE.
16 */
17
18/* $Id: string.h,v 1.23 2007/09/13 04:48:16 each Exp $ */
19
20#ifndef ISC_STRING_H
21#define ISC_STRING_H 1
22
23/*! \file isc/string.h */
24
25#include <isc/formatcheck.h>
26#include <isc/int.h>
27#include <isc/lang.h>
28#include <isc/platform.h>
29#include <isc/types.h>
30
31#include <string.h>
32
33#ifdef ISC_PLATFORM_HAVESTRINGSH
34#include <strings.h>
35#endif
36
37#define ISC_STRING_MAGIC 0x5e
38
39ISC_LANG_BEGINDECLS
40
41isc_uint64_t
42isc_string_touint64(char *source, char **endp, int base);
43/*%<
44 * Convert the string pointed to by 'source' to isc_uint64_t.
45 *
46 * On successful conversion 'endp' points to the first character
47 * after conversion is complete.
48 *
49 * 'base': 0 or 2..36
50 *
51 * If base is 0 the base is computed from the string type.
52 *
53 * On error 'endp' points to 'source'.
54 */
55
56isc_result_t
57isc_string_copy(char *target, size_t size, const char *source);
58/*
59 * Copy the string pointed to by 'source' to 'target' which is a
60 * pointer to a string of at least 'size' bytes.
61 *
62 * Requires:
63 * 'target' is a pointer to a char[] of at least 'size' bytes.
64 * 'size' an integer > 0.
65 * 'source' == NULL or points to a NUL terminated string.
66 *
67 * Ensures:
68 * If result == ISC_R_SUCCESS
69 * 'target' will be a NUL terminated string of no more
70 * than 'size' bytes (including NUL).
71 *
72 * If result == ISC_R_NOSPACE
73 * 'target' is undefined.
74 *
75 * Returns:
76 * ISC_R_SUCCESS -- 'source' was successfully copied to 'target'.
77 * ISC_R_NOSPACE -- 'source' could not be copied since 'target'
78 * is too small.
79 */
80
81void
82isc_string_copy_truncate(char *target, size_t size, const char *source);
83/*
84 * Copy the string pointed to by 'source' to 'target' which is a
85 * pointer to a string of at least 'size' bytes.
86 *
87 * Requires:
88 * 'target' is a pointer to a char[] of at least 'size' bytes.
89 * 'size' an integer > 0.
90 * 'source' == NULL or points to a NUL terminated string.
91 *
92 * Ensures:
93 * 'target' will be a NUL terminated string of no more
94 * than 'size' bytes (including NUL).
95 */
96
97isc_result_t
98isc_string_append(char *target, size_t size, const char *source);
99/*
100 * Append the string pointed to by 'source' to 'target' which is a
101 * pointer to a NUL terminated string of at least 'size' bytes.
102 *
103 * Requires:
104 * 'target' is a pointer to a NUL terminated char[] of at
105 * least 'size' bytes.
106 * 'size' an integer > 0.
107 * 'source' == NULL or points to a NUL terminated string.
108 *
109 * Ensures:
110 * If result == ISC_R_SUCCESS
111 * 'target' will be a NUL terminated string of no more
112 * than 'size' bytes (including NUL).
113 *
114 * If result == ISC_R_NOSPACE
115 * 'target' is undefined.
116 *
117 * Returns:
118 * ISC_R_SUCCESS -- 'source' was successfully appended to 'target'.
119 * ISC_R_NOSPACE -- 'source' could not be appended since 'target'
120 * is too small.
121 */
122
123void
124isc_string_append_truncate(char *target, size_t size, const char *source);
125/*
126 * Append the string pointed to by 'source' to 'target' which is a
127 * pointer to a NUL terminated string of at least 'size' bytes.
128 *
129 * Requires:
130 * 'target' is a pointer to a NUL terminated char[] of at
131 * least 'size' bytes.
132 * 'size' an integer > 0.
133 * 'source' == NULL or points to a NUL terminated string.
134 *
135 * Ensures:
136 * 'target' will be a NUL terminated string of no more
137 * than 'size' bytes (including NUL).
138 */
139
140isc_result_t
141isc_string_printf(char *target, size_t size, const char *format, ...)
142 ISC_FORMAT_PRINTF(3, 4);
143/*
144 * Print 'format' to 'target' which is a pointer to a string of at least
145 * 'size' bytes.
146 *
147 * Requires:
148 * 'target' is a pointer to a char[] of at least 'size' bytes.
149 * 'size' an integer > 0.
150 * 'format' == NULL or points to a NUL terminated string.
151 *
152 * Ensures:
153 * If result == ISC_R_SUCCESS
154 * 'target' will be a NUL terminated string of no more
155 * than 'size' bytes (including NUL).
156 *
157 * If result == ISC_R_NOSPACE
158 * 'target' is undefined.
159 *
160 * Returns:
161 * ISC_R_SUCCESS -- 'format' was successfully printed to 'target'.
162 * ISC_R_NOSPACE -- 'format' could not be printed to 'target' since it
163 * is too small.
164 */
165
166void
167isc_string_printf_truncate(char *target, size_t size, const char *format, ...)
168 ISC_FORMAT_PRINTF(3, 4);
169/*
170 * Print 'format' to 'target' which is a pointer to a string of at least
171 * 'size' bytes.
172 *
173 * Requires:
174 * 'target' is a pointer to a char[] of at least 'size' bytes.
175 * 'size' an integer > 0.
176 * 'format' == NULL or points to a NUL terminated string.
177 *
178 * Ensures:
179 * 'target' will be a NUL terminated string of no more
180 * than 'size' bytes (including NUL).
181 */
182
183
184char *
185isc_string_regiondup(isc_mem_t *mctx, const isc_region_t *source);
186/*
187 * Copy the region pointed to by r to a NUL terminated string
188 * allocated from the memory context pointed to by mctx.
189 *
190 * The result should be deallocated using isc_mem_free()
191 *
192 * Requires:
193 * 'mctx' is a point to a valid memory context.
194 * 'source' is a pointer to a valid region.
195 *
196 * Returns:
197 * a pointer to a NUL terminated string or
198 * NULL if memory for the copy could not be allocated
199 *
200 */
201
202char *
203isc_string_separate(char **stringp, const char *delim);
204
205#ifdef ISC_PLATFORM_NEEDSTRSEP
206#define strsep isc_string_separate
207#endif
208
209#ifdef ISC_PLATFORM_NEEDMEMMOVE
210#define memmove(a,b,c) bcopy(b,a,c)
211#endif
212
213size_t
214isc_string_strlcpy(char *dst, const char *src, size_t size);
215
216
217#ifdef ISC_PLATFORM_NEEDSTRLCPY
218#define strlcpy isc_string_strlcpy
219#endif
220
221
222size_t
223isc_string_strlcat(char *dst, const char *src, size_t size);
224
225#ifdef ISC_PLATFORM_NEEDSTRLCAT
226#define strlcat isc_string_strlcat
227#endif
228
229ISC_LANG_ENDDECLS
230
231#endif /* ISC_STRING_H */