1/*
2 * CDDL HEADER START
3 *
4 * The contents of this file are subject to the terms of the
5 * Common Development and Distribution License, Version 1.0 only
6 * (the "License").  You may not use this file except in compliance
7 * with the License.
8 *
9 * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
10 * or http://www.opensolaris.org/os/licensing.
11 * See the License for the specific language governing permissions
12 * and limitations under the License.
13 *
14 * When distributing Covered Code, include this CDDL HEADER in each
15 * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
16 * If applicable, add the following below this CDDL HEADER, with the
17 * fields enclosed by brackets "[]" replaced with your own identifying
18 * information: Portions Copyright [yyyy] [name of copyright owner]
19 *
20 * CDDL HEADER END
21 */
22/*
23 * Copyright 2003 Sun Microsystems, Inc.  All rights reserved.
24 * Use is subject to license terms.
25 */
26
27#ifndef _VOLUME_STRING_H
28#define	_VOLUME_STRING_H
29
30#pragma ident	"%Z%%M%	%I%	%E% SMI"
31
32#include <sys/types.h>
33
34#ifdef __cplusplus
35extern "C" {
36#endif
37
38/*
39 * The length of the string when the longest long long is converted to
40 * a string
41 */
42#define	LONG_LONG_STR_SIZE	128
43
44#define	BYTES_PER_BLOCK 512
45#define	BYTES_PER_KILOBYTE 1024
46#define	BYTES_PER_MEGABYTE 1024 * 1024
47#define	BYTES_PER_GIGABYTE 1024 * 1024 * 1024
48#define	BYTES_PER_TERABYTE (uint64_t)1024 * 1024 * 1024 * 1024
49
50/*
51 * Describes units when converting from bytes to string and back.
52 */
53typedef struct {
54    char *unit_str;
55    uint64_t bytes_per_unit;
56} units_t;
57
58/* All-inclusive valid size units */
59extern units_t universal_units[];
60
61/*
62 * Concatenates a list of strings.  The result must be free()d.
63 *
64 * @param       numargs
65 *              The number of strings to concatenate.
66 *
67 * @param       ...
68 *              The strings (type char *) to concatenate.
69 *
70 * @return      the concatenated string
71 *              if succesful
72 *
73 * @return      NULL
74 *              if memory could not be allocated
75 */
76extern char *stralloccat(int numargs, ...);
77
78/*
79 * Convert the given string to a uint16_t, verifying that the value
80 * does not exceed the lower or upper bounds of a uint16_t.
81 *
82 * @param       str
83 *              the string to convert
84 *
85 * @param       num
86 *              the addr of the uint16_t
87 *
88 * @return      0
89 *              if the given string was converted to a uint16_t
90 *
91 * @return      -1
92 *              if the string could could not be converted to a number
93 *
94 * @return      -2
95 *              if the converted number exceeds the lower or upper
96 *              bounds of a uint16_t
97 */
98extern int str_to_uint16(char *str, uint16_t *num);
99
100/*
101 * Converts the given long long into a string.  This string must be
102 * freed.
103 *
104 * @param       num
105 *              the long long to convert
106 *
107 * @param       str
108 *              the addr of the string
109 *
110 * @return      0
111 *              if successful
112 *
113 * @return      ENOMEM
114 *              if the physical limits of the system are exceeded by
115 *              size bytes of memory which cannot be allocated
116 *
117 * @return      EAGAIN
118 *              if there is not enough memory available to allocate
119 *              size bytes of memory
120 */
121extern int ll_to_str(long long num, char **str);
122
123/*
124 * Convert a size specification to bytes.
125 *
126 * @param       str
127 *              a size specification strings of the form
128 *              <value><units>, where valid <units> are specified by
129 *              the units argument and <value> is the (floating-point)
130 *              multiplier of the units
131 *
132 * @param       bytes
133 *              RETURN: the result of converting the given size string
134 *              to bytes
135 *
136 * @return      0
137 *              if successful
138 *
139 * @return      non-zero
140 *              if an error occurred.  Use get_error_string() to
141 *              retrieve the associated error message.
142 */
143extern int sizestr_to_bytes(char *str, uint64_t *bytes, units_t units[]);
144
145/*
146 * Convert bytes to a size specification string.
147 *
148 * @param       bytes
149 *              the number of bytes
150 *
151 * @param       str
152 *              RETURN: a size specification strings of the form
153 *              <value><units>, where valid <units> are specified by
154 *              the units argument and <value> is the (floating-point)
155 *              multiplier of the units.  This string must be freed.
156 *
157 * @return      0
158 *              if successful
159 *
160 * @return      non-zero
161 *              if an error occurred.  Use get_error_string() to
162 *              retrieve the associated error message.
163 */
164extern int bytes_to_sizestr(
165	uint64_t bytes, char **str, units_t units[], boolean_t round);
166
167/*
168 * Appends a copy of the given string to the given string array,
169 * ensuring that the last element in the array is NULL.  This array
170 * must be freed via free_string_array.
171 *
172 * Note when an error occurs and NULL is returned, array is not freed.
173 * Subsequently callers should save a pointer to the original array
174 * until success is verified.
175 *
176 * @param       array
177 *              the array to append to, or NULL to create a new array
178 *
179 * @param       str
180 *              the string to copy and add to the array
181 *
182 * @return      a pointer to the realloc'd (and possibly moved) array
183 *              if succesful
184 *
185 * @return      NULL
186 *              if unsuccesful
187 */
188extern char ** append_to_string_array(char **array, char *str);
189
190/*
191 * Frees each element of the given string array, then frees the array
192 * itself.
193 *
194 * @param       array
195 *              a NULL-terminated string array
196 */
197extern void free_string_array(char **array);
198
199#ifdef __cplusplus
200}
201#endif
202
203#endif /* _VOLUME_STRING_H */
204