b98920a8cadf95402ed12a5b55656b5799bd05a4
[OpenSRF.git] / include / opensrf / utils.h
1 /*
2 Copyright (C) 2005  Georgia Public Library Service 
3 Bill Erickson <highfalutin@gmail.com>
4 Mike Rylander <mrylander@gmail.com>
5
6 This program is free software; you can redistribute it and/or
7 modify it under the terms of the GNU General Public License
8 as published by the Free Software Foundation; either version 2
9 of the License, or (at your option) any later version.
10
11 This program is distributed in the hope that it will be useful,
12 but WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14 GNU General Public License for more details.
15 */
16
17 /**
18         @file utils.h
19         
20         @brief Prototypes for various low-level utility functions, and related macros.
21         
22         Many of these facilities concern the growing_buffer structure,
23         a sort of poor man's string class that allocates more space for
24         itself as needed.
25 */
26
27 #ifndef UTILS_H
28 #define UTILS_H
29
30 #include <stdio.h>
31 #include <stdarg.h>
32 #include <fcntl.h>
33 #include <unistd.h>
34 #include <sys/time.h>
35 #include <sys/stat.h>
36 #include <fcntl.h>
37 #include <sys/types.h>
38 #include <stdlib.h>
39 #include <string.h>
40 //#include <sys/timeb.h>
41
42 #ifdef __cplusplus
43 extern "C" {
44 #endif
45
46 #include "md5.h"
47 /**
48         @brief Macro version of safe_malloc()
49         @param ptr Pointer to be updated to point to newly allocated memory
50         @param size How many bytes to allocate
51 */
52 #define OSRF_MALLOC(ptr, size) \
53         do {\
54                         size_t _size = size; \
55                         void* p = malloc( _size ); \
56                         if( p == NULL ) { \
57                                 perror("OSRF_MALLOC(): Out of Memory" ); \
58                                 exit(99); \
59                         } \
60                         memset( p, 0, _size ); \
61                         (ptr) = p; \
62                 } while(0)
63
64 #ifdef NDEBUG
65 #define osrf_clearbuf( s, n ) memset( s, 0, n )
66 #else
67 /**
68          @brief Fills a buffer with binary zeros (normal mode) or exclamation points (debugging mode)
69          @param s Pointer to buffer
70          @param n Length of buffer
71
72          This macro is used to help ferret out code that inappropriately assumes that a newly
73          allocated buffer is filled with binary zeros.  No code should rely on it to do
74          anything in particular.  Someday it may turn into a no-op.
75  */
76 #define osrf_clearbuf( s, n ) \
77         do { \
78                 char * clearbuf_temp_s = (s); \
79                 size_t clearbuf_temp_n = (n); \
80                 memset( clearbuf_temp_s, '!', clearbuf_temp_n ); \
81                 clearbuf_temp_s[ clearbuf_temp_n - 1 ] = '\0'; \
82         } while( 0 )
83 #endif
84
85 /**
86         @brief Macro version of buffer_add()
87         @param gb Pointer to a growing_buffer
88         @param data Pointer to the string to be appended
89 */
90
91 #define OSRF_BUFFER_ADD(gb, data) \
92         do {\
93                 int _tl; \
94                 growing_buffer* _gb = gb; \
95                 const char* _data = data; \
96                 if(_gb && _data) {\
97                         _tl = strlen(_data) + _gb->n_used;\
98                         if( _tl < _gb->size ) {\
99                                 strcpy( _gb->buf + _gb->n_used, _data ); \
100                                 _gb->n_used = _tl; \
101                         } else { buffer_add(_gb, _data); }\
102                 }\
103         } while(0)
104
105 /**
106         @brief Macro version of buffer_add_n()
107         @param gb Pointer to a growing_buffer
108         @param data Pointer to the bytes to be appended
109         @param n How many characters to append
110 */
111 #define OSRF_BUFFER_ADD_N(gb, data, n) \
112         do {\
113                 growing_buffer* gb__ = gb; \
114                 const char* data__ = data; \
115                 size_t n__ = n; \
116                 if(gb__ && data__) {\
117                         int tl__ = n__ + gb__->n_used;\
118                         if( tl__ < gb__->size ) {\
119                                 memcpy( gb__->buf + gb__->n_used, data__, n__ ); \
120                                 gb__->buf[tl__] = '\0'; \
121                                 gb__->n_used = tl__; \
122 } else { buffer_add_n(gb__, data__, n__); }\
123 }\
124 } while(0)
125
126 /**
127         @brief Macro version of buffer_add_char()
128         @param gb Pointer to a growing buffer
129         @param c Character to be appended
130 */
131 #define OSRF_BUFFER_ADD_CHAR(gb, c)\
132         do {\
133                 growing_buffer* _gb = gb;\
134                 char _c = c;\
135                 if(_gb) {\
136                         if(_gb->n_used < _gb->size - 1) {\
137                                 _gb->buf[_gb->n_used++] = _c;\
138                                 _gb->buf[_gb->n_used]   = '\0';\
139                         }\
140                         else\
141                                 buffer_add_char(_gb, _c);\
142                 }\
143         }while(0)
144
145 /**
146         @brief Macro version of buffer_reset()
147         @param gb Pointer to the growing_buffer to be reset
148 */
149 #define OSRF_BUFFER_RESET(gb) \
150         do {\
151                 growing_buffer* _gb = gb;\
152         memset(_gb->buf, 0, _gb->size);\
153         _gb->n_used = 0;\
154         }while(0)
155
156 /**
157         @brief Resolves to a const pointer to the string inside a growing_buffer
158         @param x Pointer to a growing_buffier
159 */
160 #define OSRF_BUFFER_C_STR( x ) ((const char *) (x)->buf)
161
162
163 /**
164         @brief Turn a printf-style format string and a va_list into a string.
165         @param x A printf-style format string.
166
167         This macro can work only in a variadic function.
168
169         The resulting string is constructed in a local buffer, whose address is
170         given by the pointer VA_BUF,  This buffer is NOT allocated dynamically,
171         so don't try to free it.
172 */
173 #define VA_LIST_TO_STRING(x) \
174         unsigned long __len = 0;\
175         va_list args; \
176         va_list a_copy;\
177         va_copy(a_copy, args); \
178         va_start(args, x); \
179         __len = vsnprintf(NULL, 0, x, args); \
180         va_end(args); \
181         __len += 2; \
182         char _b[__len]; \
183         bzero(_b, __len); \
184         va_start(a_copy, x); \
185         vsnprintf(_b, __len - 1, x, a_copy); \
186         va_end(a_copy); \
187         char* VA_BUF = _b; \
188
189 /**
190         @brief Format a long into a string.
191         @param l A long
192
193         The long is formatted into a local buffer whose address is given by the pointer
194         LONG_TO_STRING.  This buffer is NOT allocated dynamically, so don't try to free it.
195 */
196 #define LONG_TO_STRING(l) \
197         unsigned int __len = snprintf(NULL, 0, "%ld", l) + 2;\
198         char __b[__len]; \
199         bzero(__b, __len); \
200         snprintf(__b, __len - 1, "%ld", l); \
201         char* LONGSTR = __b;
202
203 /**
204         @brief Format a double into a string.
205         @param l A double
206
207         The double is formatted into a local buffer whose address is given by the pointer
208         LONG_TO_STRING.  This buffer is NOT allocated dynamically, so don't try to free it.
209  */
210 #define DOUBLE_TO_STRING(l) \
211         unsigned int __len = snprintf(NULL, 0, "%f", l) + 2; \
212         char __b[__len]; \
213         bzero(__b, __len); \
214         snprintf(__b, __len - 1, "%f", l); \
215         char* DOUBLESTR = __b;
216
217 /**
218         @brief Format a long double into a string.
219         @param l A long double
220
221         The long double is formatted into a local buffer whose address is given by the pointer
222         LONG_TO_STRING.  This buffer is NOT allocated dynamically, so don't try to free it.
223  */
224 #define LONG_DOUBLE_TO_STRING(l) \
225         unsigned int __len = snprintf(NULL, 0, "%Lf", l) + 2; \
226         char __b[__len]; \
227         bzero(__b, __len); \
228         snprintf(__b, __len - 1, "%Lf", l); \
229         char* LONGDOUBLESTR = __b;
230
231
232 /**
233         @brief Format an int into a string.
234         @param l An int
235
236         The int is formatted into a local buffer whose address is given by the pointer
237         LONG_TO_STRING.  This buffer is NOT allocated dynamically, so don't try to free it.
238  */
239 #define INT_TO_STRING(l) \
240         unsigned int __len = snprintf(NULL, 0, "%d", l) + 2; \
241         char __b[__len]; \
242         bzero(__b, __len); \
243         snprintf(__b, __len - 1, "%d", l); \
244         char* INTSTR = __b;
245
246
247 /*
248 #define MD5SUM(s) \
249         struct md5_ctx ctx; \
250         unsigned char digest[16];\
251         MD5_start (&ctx);\
252         int i;\
253         for ( i=0 ; i != strlen(text) ; i++ ) MD5_feed (&ctx, text[i]);\
254         MD5_stop (&ctx, digest);\
255         char buf[16];\
256         memset(buf,0,16);\
257         char final[256];\
258         memset(final,0,256);\
259         for ( i=0 ; i<16 ; i++ ) {\
260                 sprintf(buf, "%02x", digest[i]);\
261                 strcat( final, buf );\
262         }\
263         char* MD5STR = final;
264         */
265
266
267         
268
269
270 /**
271         @brief The maximum buffer size for a growing_buffer
272 */
273 #define BUFFER_MAX_SIZE 10485760 
274
275 /* these are evil and should be condemned 
276         ! Only use these if you are done with argv[].
277         call init_proc_title() first, then call
278         set_proc_title. 
279         the title is only allowed to be as big as the
280         initial process name of the process (full size of argv[]).
281         truncation may occur.
282  */
283 int init_proc_title( int argc, char* argv[] );
284 int set_proc_title( const char* format, ... );
285
286
287 int daemonize( void );
288
289 void* safe_malloc(int size);
290 void* safe_calloc(int size);
291
292 // ---------------------------------------------------------------------------------
293 // Generic growing buffer. Add data all you want
294 // ---------------------------------------------------------------------------------
295 /**
296         @brief A poor man's string class in C.
297
298         A growing_buffer stores a character string.  Related functions append data
299         and otherwise manage the string, allocating more memory automatically as needed
300         when the string gets too big for its buffer.
301
302         A growing_buffer is designed for text, not binary data.  In particular: if you
303         try to store embedded nuls in one, something bad will almost certainly happen.
304 */
305 struct growing_buffer_struct {
306         /** @brief Pointer to the internal buffer */
307         char *buf;
308         /** @brief Length of the stored string */
309         int n_used;
310         /** @brief Size of the internal buffer */
311         int size;
312 };
313 typedef struct growing_buffer_struct growing_buffer;
314
315 /**
316         @brief The length of the string stored by a growing_buffer.
317         @param x A pointer to the growing buffer.
318 */
319 #define buffer_length(x) (x)->n_used
320
321 growing_buffer* buffer_init( int initial_num_bytes);
322
323 // XXX This isn't defined in utils.c!! removing for now...
324 //int buffer_addchar(growing_buffer* gb, char c);
325
326 int buffer_add(growing_buffer* gb, const char* c);
327 int buffer_add_n(growing_buffer* gb, const char* data, size_t n);
328 int buffer_fadd(growing_buffer* gb, const char* format, ... );
329 int buffer_reset( growing_buffer* gb);
330 char* buffer_data( const growing_buffer* gb);
331 char* buffer_release( growing_buffer* gb );
332 int buffer_free( growing_buffer* gb );
333 int buffer_add_char(growing_buffer* gb, char c);
334 char buffer_chomp(growing_buffer* gb); // removes the last character from the buffer
335
336 /* returns the size needed to fill in the vsnprintf buffer.  
337         * ! this calls va_end on the va_list argument*
338         */
339 long va_list_size(const char* format, va_list);
340
341 /* turns a va list into a string, caller must free the 
342         allocated char */
343 char* va_list_to_string(const char* format, ...);
344
345
346 /* string escape utility method.  escapes unicode embedded characters.
347         escapes the usual \n, \t, etc. 
348         for example, if you provide a string like so:
349
350         hello,
351                 you
352
353         you would get back:
354         hello,\n\tyou
355  
356  */
357 char* uescape( const char* string, int size, int full_escape );
358
359 /* utility methods */
360 int set_fl( int fd, int flags );
361 int clr_fl( int fd, int flags );
362
363
364
365 // Utility method
366 double get_timestamp_millis( void );
367
368
369 /* returns true if the whole string is a number */
370 int stringisnum(const char* s);
371
372
373 /* 
374   Calculates the md5 of the text provided.
375   The returned string must be freed by the caller.
376   */
377 char* md5sum( const char* text, ... );
378
379
380 /*
381   Checks the validity of the file descriptor
382   returns -1 if the file descriptor is invalid
383   returns 0 if the descriptor is OK
384   */
385 int osrfUtilsCheckFileDescriptor( int fd );
386
387 #ifdef __cplusplus
388 }
389 #endif
390
391 #endif