1 /**
2 * Copyright (C) Mellanox Technologies Ltd. 2001-2017. ALL RIGHTS RESERVED.
3 *
4 * See file LICENSE for terms.
5 */
6
7 #ifndef UCS_STRING_H_
8 #define UCS_STRING_H_
9
10 #include "compiler_def.h"
11 #include <ucs/type/status.h>
12 #include <ucs/sys/math.h>
13
14 #include <stddef.h>
15 #include <stdint.h>
16 #include <string.h>
17 #include <sys/socket.h>
18
19 BEGIN_C_DECLS
20
21 /** @file string.h */
22
23 /* value which specifies "infinity" for a numeric variable */
24 #define UCS_NUMERIC_INF_STR "inf"
25
26 /* value which specifies "auto" for a variable */
27 #define UCS_VALUE_AUTO_STR "auto"
28
29 /* the numeric value of "infinity" */
30 #define UCS_MEMUNITS_INF ((size_t)-1)
31 #define UCS_ULUNITS_INF ((unsigned long)-1)
32
33 /* value which specifies "auto" for a numeric variable */
34 #define UCS_MEMUNITS_AUTO ((size_t)-2)
35 #define UCS_ULUNITS_AUTO ((unsigned long)-2)
36 #define UCS_HEXUNITS_AUTO ((uint16_t)-2)
37
38
39 /**
40 * Expand a partial path to full path.
41 *
42 * @param path Path to expand.
43 * @param fullpath Filled with full path.
44 * @param max Room in "fullpath"
45 */
46 void ucs_expand_path(const char *path, char *fullpath, size_t max);
47
48
49 /**
50 * Fill a filename template. The following values in the string are replaced:
51 * %p - replaced by process id
52 * %h - replaced by host name
53 *
54 * @param tmpl File name template (possibly containing formatting sequences)
55 * @param buf Filled with resulting file name
56 * @param max Maximal size of destination buffer.
57 */
58 void ucs_fill_filename_template(const char *tmpl, char *buf, size_t max);
59
60
61 /**
62 * Format a string to a buffer of given size, and fill the rest of the buffer
63 * with '\0'. Also, guarantee that the last char in the buffer is '\0'.
64 *
65 * @param buf Buffer to format the string to.
66 * @param size Buffer size.
67 * @param fmt Format string.
68 */
69 void ucs_snprintf_zero(char *buf, size_t size, const char *fmt, ...)
70 UCS_F_PRINTF(3, 4);
71
72
73 /**
74 * Same as strncpy(), but guarantee that the last char in the buffer is '\0'.
75 */
76 void ucs_strncpy_zero(char *dest, const char *src, size_t max);
77
78
79 /**
80 * Return a number filled with the first characters of the string.
81 */
82 uint64_t ucs_string_to_id(const char *str);
83
84
85 /**
86 * Convert a memory units value to a string which is abbreviated if possible.
87 * For example:
88 * 1024 -> 1kb
89 *
90 * @param value Value to convert.
91 * @param buf Buffer to place the string.
92 * @param max Maximal length of the buffer.
93 *
94 * @return Pointer to 'buf', which holds the resulting string.
95 */
96 char *ucs_memunits_to_str(size_t value, char *buf, size_t max);
97
98
99 /**
100 * Convert a string holding memory units to a numeric value.
101 *
102 * @param buf String to convert
103 * @param dest Numeric value of the string
104 *
105 * @return UCS_OK if successful, or error code otherwise.
106 */
107 ucs_status_t ucs_str_to_memunits(const char *buf, void *dest);
108
109
110 /**
111 * Return the numeric value of the memunits prefix.
112 * For example:
113 * 'M' -> 1048576
114 */
115 size_t ucs_string_quantity_prefix_value(char prefix);
116
117
118 /**
119 * Format a string to a buffer of given size, and guarantee that the last char
120 * in the buffer is '\0'.
121 *
122 * @param buf Buffer to format the string to.
123 * @param size Buffer size.
124 * @param fmt Format string.
125 */
126 void ucs_snprintf_safe(char *buf, size_t size, const char *fmt, ...)
127 UCS_F_PRINTF(3, 4);
128
129
130 /**
131 * Copy string limited by len bytes. Destination string is always ended by '\0'
132 *
133 * @param dst Destination buffer
134 * @param src Source string
135 * @param len Maximum string length to copy
136 *
137 * @return address of destination buffer
138 */
139 char* ucs_strncpy_safe(char *dst, const char *src, size_t len);
140
141
142 /**
143 * Remove whitespace characters in the beginning and end of the string, as
144 * detected by isspace(3). Returns a pointer to the new string (which may be a
145 * substring of 'str'). The original string 'str' may be modified in-place.
146 *
147 * @param str String to remove whitespaces from.
148 * @return Pointer to the new string, with leading/trailing whitespaces removed.
149 */
150 char *ucs_strtrim(char *str);
151
152
153 /**
154 * Get pointer to file name in path, same as basename but do not
155 * modify source string.
156 *
157 * @param path Path to parse.
158 *
159 * @return file name
160 */
ucs_basename(const char * path)161 static UCS_F_ALWAYS_INLINE const char* ucs_basename(const char *path)
162 {
163 const char *name = strrchr(path, '/');
164
165 return (name == NULL) ? path : name + 1;
166 }
167
168
169 /**
170 * Dump binary array into string in hex format. Destination string is
171 * always ended by '\0'.
172 *
173 * @param data Source array to dump.
174 * @param length Length of source array in bytes.
175 * @param buf Destination string.
176 * @param max Max length of destination string including terminating
177 * '\0' byte.
178 * @param per_line Number of bytes in source array to print per line
179 * or SIZE_MAX for single line.
180 *
181 * @return address of destination buffer
182 */
183 const char *ucs_str_dump_hex(const void* data, size_t length, char *buf,
184 size_t max, size_t per_line);
185
186
187 /**
188 * Convert the given flags to a string that represents them.
189 *
190 * @param str String to hold the flags string values.
191 * @param max Size of the string.
192 * @param flags Flags to be converted.
193 * @param str_table Conversion table - from flag value to a string.
194 *
195 * @return String that holds the representation of the given flags.
196 */
197 const char* ucs_flags_str(char *str, size_t max,
198 uint64_t flags, const char **str_table);
199
200
201 /**
202 * Get estimated number of segments different in the two paths. Segments are
203 * separated by `/`.
204 *
205 * @param path1 String pointing to first path
206 * @param path2 String pointing to second path
207 *
208 * @return if either of the paths are invalid, UINT_MAX; if paths are the same 0
209 * is returned; otherwise in between
210 */
211 ssize_t ucs_path_calc_distance(const char *path1, const char *path2);
212
213
214 /** Quantifier suffixes for memory units ("K", "M", "G", etc) */
215 extern const char *ucs_memunits_suffixes[];
216
217
218 END_C_DECLS
219
220 #endif
221