← Back to branch summary

~ubuntu-branches/ubuntu/breezy/vanessa-logger/breezy

« back to all changes in this revision

Viewing changes to libvanessa_logger/vanessa_logger.h

  • Committer: Bazaar Package Importer
  • Author(s): Simon Horman
  • Date: 2004-08-29 18:48:47 UTC
  • mfrom: (0.1.1 upstream) (1.1.1 warty)
  • Revision ID: james.westby@ubuntu.com-20040829184847-cxmqtjoqlv3kpe8j
Tags: 0.0.7-1
http://bugs.debian.org/262743
Fixed gcc-3.4 build problem. (closes: Bug#262743)

Show diffs side-by-side

added added

removed removed

Lines of Context:
libvanessa_logger/vanessa_logger.h
1
1
/***********************************************************************
2
2
 * vanessa_logger.h                                       September 2000
3
 
 * Horms                                              horms@vergenet.net
 
3
 * Horms                                              horms@verge.net.au
4
4
 *
5
5
 * vanessa_logger
6
6
 * Generic logging layer
7
 
 * Copyright (C) 2000  Horms
 
7
 * Copyright (C) 2000-2004  Horms
8
8
 * 
9
9
 * This library is free software; you can redistribute it and/or
10
10
 * modify it under the terms of the GNU Lesser General Public License
26
26
#include <stdio.h>
27
27
#include <stdarg.h>
28
28
#include <syslog.h>
 
29
#include <string.h>
 
30
#include <errno.h>
29
31
 
30
32
#ifndef VANESSA_LOGGER_FLIM
31
33
#define VANESSA_LOGGER_FLIM
32
34
 
33
35
typedef void vanessa_logger_t;
34
36
 
 
37
typedef void (*vanessa_logger_log_function_va_t) 
 
38
                (int priority, const char *fmt, va_list ap);
 
39
 
 
40
/*
 
41
 * NB: There was a fundamental design error in the original
 
42
 * implementation of logging to functions such that it cannot work
 
43
 * wit vanessa_loggers internal framework. Thus
 
44
 * vanessa_logger_log_function_t has been replaced by
 
45
 * vanessa_logger_log_function_va_t. Please do not use
 
46
 * vanessa_logger_log_function_t.
 
47
 *
 
48
 * I apologies that this breaks backwards compatibility, but
 
49
 * there is no way to make the original protoype work.
 
50
 * 
 
51
 * Perhaps there was something in the air on the train in Northern Germany
 
52
 * when I wrote this code. Perhaps I was just tired. But in any case
 
53
 * it was wrong.
 
54
 *
 
55
 * Horms, December 2002
 
56
 *
 
57
 * typedef int (*vanessa_logger_log_function_t) 
 
58
 *              (int priority, const char *fmt, ...);
 
59
 */
 
60
 
 
61
typedef unsigned int vanessa_logger_flag_t;
 
62
 
 
63
 
 
64
/**********************************************************************
 
65
 * Flags for filehandle or filename loggers
 
66
 **********************************************************************/
 
67
 
 
68
#define VANESSA_LOGGER_F_NONE         0x0  /* Default behaviour */
 
69
#define VANESSA_LOGGER_F_NO_IDENT_PID 0x1  /* Don't show ident and pid */
 
70
#define VANESSA_LOGGER_F_TIMESTAMP    0x2  /* Log the date and time */
 
71
#define VANESSA_LOGGER_F_CONS         0x4  /* Log to the console if there
 
72
                                              is an error while writing 
 
73
                                              to the filehandle or filename */
 
74
#define VANESSA_LOGGER_F_PERROR       0x8  /* Print to stderr as well */
35
75
 
36
76
/**********************************************************************
37
77
 * vanessa_logger_openlog_syslog
48
88
 *         NULL on error
49
89
 **********************************************************************/
50
90
 
51
 
vanessa_logger_t *vanessa_logger_openlog_syslog(
52
 
  const int facility,
53
 
  const char *ident,
54
 
  const int max_priority,
55
 
  const int option
56
 
);
 
91
vanessa_logger_t *
 
92
vanessa_logger_openlog_syslog(const int facility, const char *ident,
 
93
                const int max_priority, const int option);
57
94
 
58
95
 
59
96
/**********************************************************************
71
108
 *         NULL on error
72
109
 **********************************************************************/
73
110
 
74
 
vanessa_logger_t *vanessa_logger_openlog_syslog_byname(
75
 
  const char *facility_name,
76
 
  const char *ident,
77
 
  const int max_priority,
78
 
  const int option
79
 
);
 
111
vanessa_logger_t *
 
112
vanessa_logger_openlog_syslog_byname(const char *facility_name,
 
113
                const char *ident, const int max_priority, const int option);
80
114
 
81
115
 
82
116
/**********************************************************************
87
121
 *      max_priority: Maximum priority number to log
88
122
 *                    Priorities are integers, the levels listed
89
123
 *                    in syslog(3) should be used for a syslog logger
90
 
 *      option: ignored
 
124
 *      flag: flags for logger
 
125
 *            See "Flags for filehandle or filename loggers"
 
126
 *            in vanessa_logger.h for valid flags
91
127
 * post: Logger is opened
92
128
 * return: pointer to logger
93
129
 *         NULL on error
94
130
 **********************************************************************/
95
131
 
96
 
vanessa_logger_t *vanessa_logger_openlog_filehandle(
97
 
  FILE *filehandle,
98
 
  const char *ident,
99
 
  const int max_priority,
100
 
  const int option
101
 
);
 
132
vanessa_logger_t *
 
133
vanessa_logger_openlog_filehandle(FILE * filehandle, const char *ident,
 
134
                const int max_priority, const int flag);
102
135
 
103
136
 
104
137
/**********************************************************************
110
143
 *      max_priority: Maximum priority number to log
111
144
 *                    Priorities are integers, the levels listed
112
145
 *                    in syslog(3) should be used for a syslog logger
 
146
 *      flag: flags for logger
 
147
 *            See "Flags for filehandle or filename loggers"
 
148
 *            in vanessa_logger.h for valid flags
 
149
 * post: Logger is opened
 
150
 * return: pointer to logger
 
151
 *         NULL on error
 
152
 **********************************************************************/
 
153
 
 
154
vanessa_logger_t *
 
155
vanessa_logger_openlog_filename(const char *filename, const char *ident,
 
156
                const int max_priority, const int flag);
 
157
 
 
158
 
 
159
/**********************************************************************
 
160
 * vanessa_logger_openlog_function
 
161
 * Exported function to open a logger that will log to a given function
 
162
 * pre: function: function to use for logging
 
163
 *      ident: Identity to prepend to each log
 
164
 *      max_priority: Maximum priority number to log
 
165
 *                    Priorities are integers, the levels listed
 
166
 *                    in syslog(3) should be used for a syslog logger
113
167
 *      option: ignored
114
168
 * post: Logger is opened
115
169
 * return: pointer to logger
116
170
 *         NULL on error
117
171
 **********************************************************************/
118
172
 
119
 
vanessa_logger_t *vanessa_logger_openlog_filename(
120
 
  char *filename,
121
 
  const char *ident,
122
 
  const int max_priority,
123
 
  const int option
124
 
);
 
173
vanessa_logger_t *
 
174
vanessa_logger_openlog_function(vanessa_logger_log_function_va_t log_function, 
 
175
                const char *ident, const int max_priority, const int option);
125
176
 
126
177
 
127
178
/**********************************************************************
132
183
 * return: none
133
184
 **********************************************************************/
134
185
 
135
 
void vanessa_logger_closelog(vanessa_logger_t *vl);
 
186
void 
 
187
vanessa_logger_closelog(vanessa_logger_t * vl);
136
188
 
137
189
 
138
190
/**********************************************************************
148
200
 * return: none
149
201
 **********************************************************************/
150
202
 
151
 
void vanessa_logger_change_max_priority(
152
 
  vanessa_logger_t *vl,
153
 
  const int max_priority
154
 
);
 
203
void 
 
204
vanessa_logger_change_max_priority(vanessa_logger_t * vl, 
 
205
                const int max_priority);
155
206
 
156
207
 
157
208
/**********************************************************************
160
211
 * pre: vl: pointer to logger to log to
161
212
 *      priority: Priority to log with.
162
213
 *                If priority is more than max_priority as provided to
163
 
 *                vanessa_logger_openlog_filehandle, 
164
 
 *                vanessa_logger_openlog_filename or
165
 
 *                vanessa_logger_openlog_syslog. 
 
214
 *                vanessa_logger_openlog_*.
166
215
 *                Levels described in syslog(3) should be used for
167
216
 *                syslog loggers as the priority will be used when
168
217
 *                logging to syslog. These priorities may also be
181
230
 * return: none
182
231
 **********************************************************************/
183
232
 
184
 
void vanessa_logger_log(vanessa_logger_t *vl, int priority, char *fmt, ...);
 
233
void
 
234
vanessa_logger_log(vanessa_logger_t * vl, int priority, const char *fmt, ...);
185
235
 
186
236
 
187
237
/**********************************************************************
191
241
 * of a variable number of arguments.
192
242
 **********************************************************************/
193
243
 
194
 
void vanessa_logger_logv(
195
 
  vanessa_logger_t *vl, 
196
 
  int priority, 
197
 
  char *fmt, 
198
 
  va_list ap
199
 
);
 
244
void 
 
245
vanessa_logger_logv(vanessa_logger_t * vl, int priority, const char *fmt, 
 
246
                va_list ap);
 
247
 
 
248
 
 
249
/**********************************************************************
 
250
 * _vanessa_logger_log_prefix
 
251
 * Exported function used by convienience macros to prefix a message
 
252
 * with the function name that the message was generated in
 
253
 **********************************************************************/
 
254
 
 
255
void 
 
256
_vanessa_logger_log_prefix(vanessa_logger_t * vl, int priority, 
 
257
                const char *prefix, const char *fmt, ...);
200
258
 
201
259
 
202
260
/**********************************************************************
211
269
 *       on for instance receiving a SIGHUP
212
270
 **********************************************************************/
213
271
 
214
 
int vanessa_logger_reopen(vanessa_logger_t *vl);
 
272
int 
 
273
vanessa_logger_reopen(vanessa_logger_t * vl);
 
274
 
 
275
 
 
276
/**********************************************************************
 
277
 * vanessa_logger_strherror_r
 
278
 * Returns a string describing the error code present in errnum
 
279
 * according to the errors for h_errno which is set by gethostbyname(3)
 
280
 * gethostbyaddr(3) and others. Analagous to strerror_r(3).
 
281
 * pre: errnum: Error to show as a string
 
282
 *      buf: buffer to write error string to
 
283
 *      n: length of buf in bytes
 
284
 * post: on success error string is written to buf
 
285
 *       on invalud input errno is set to -EINVAL
 
286
 *       if buf is too short then errno is set to -ERANGE
 
287
 * return: 0 on success
 
288
 *         -1 on error
 
289
 **********************************************************************/
 
290
 
 
291
int
 
292
vanessa_logger_strherror_r(int errnum, char *buf, size_t n);
 
293
 
 
294
 
 
295
/**********************************************************************
 
296
 * vanessa_logger_strherror
 
297
 * Returns a string describing the error code present in errnum
 
298
 * according to the errors for h_errno which is set by gethostbyname(3)
 
299
 * gethostbyaddr(3) and others. Analagous to strerror_r(3).
 
300
 * pre: errnum: Error to show as a string
 
301
 * post: none on success
 
302
 *       on invalid input errno is set to -EINVAL
 
303
 *       if buf is too short then errno is set to -ERANGE
 
304
 * return: error string for errnum on success
 
305
 *         error string for newly set errno on error
 
306
 **********************************************************************/
 
307
 
 
308
char *
 
309
vanessa_logger_strherror(int errnum);
 
310
 
 
311
 
 
312
/**********************************************************************
 
313
 * vanessa_logger_set_flag
 
314
 * Set flags for logger
 
315
 * Should only be used on filehandle or filename loggers,
 
316
 * ignored otherewise.
 
317
 * pre: vl: logger to set flags of
 
318
 *      flag: value to set flags to
 
319
 *            See "Flags for filehandle or filename loggers"
 
320
 *            in vanessa_logger.h for valid flags
 
321
 * post: flag is set
 
322
 * return: none
 
323
 **********************************************************************/
 
324
 
 
325
void
 
326
vanessa_logger_set_flag(vanessa_logger_t * vl, vanessa_logger_flag_t flag);
 
327
 
 
328
 
 
329
/**********************************************************************
 
330
 * vanessa_logger_get_flag
 
331
 * Set flags for logger
 
332
 * Should only be used on filehandle or filename loggers,
 
333
 * will return 0 for other types of loggers.
 
334
 * See "Flags for filehandle or filename loggers"
 
335
 * in vanessa_logger.h for valid flags
 
336
 * pre: vl: logger to get flags of
 
337
 * post: none
 
338
 * return: flags for logger
 
339
 **********************************************************************/
 
340
 
 
341
vanessa_logger_flag_t
 
342
vanessa_logger_get_flag(vanessa_logger_t * vl);
 
343
 
 
344
 
 
345
/**********************************************************************
 
346
 * vanessa_logger_str_dump
 
347
 * Sanitise a buffer into ASCII
 
348
 * pre: vl: Vanessa logger to log errors to. May be NULL.
 
349
 *      buffer: buffer to sanitise
 
350
 *      size: number of bytes in buffer to sanitise
 
351
 *      flag: If VANESSA_LOGGER_STR_DUMP_HEX then a hexidecimal dump
 
352
 *            will be done. Else an octal dump will be done.
 
353
 * post: a new buffer is alocated. For each byte in buffer
 
354
 *       that is a printable ASCII character it is added to
 
355
 *       the new buffer. All other characters are represented
 
356
 *       in the new buffer as octal, in the form \xxx.
 
357
 * return: the new buffer, this should be freed by the caller
 
358
 *         NULL on error
 
359
 **********************************************************************/
 
360
 
 
361
 
 
362
#define VANESSA_LOGGER_STR_DUMP_OCT 0x0
 
363
#define VANESSA_LOGGER_STR_DUMP_HEX 0x1
 
364
 
 
365
char *
 
366
vanessa_logger_str_dump(vanessa_logger_t * vl, const unsigned char *buffer, 
 
367
                const size_t buffer_length, vanessa_logger_flag_t flag);
 
368
 
 
369
 
 
370
/**********************************************************************
 
371
 * The code below sets an internal logger and provides convenience
 
372
 * macros to use this logger. You may either use this, or keep
 
373
 * track of the logger yourself and use the vanessa_logger functions
 
374
 * above directly. The latter approach allows for more than
 
375
 * one logger to be in use at in a single programme.
 
376
 **********************************************************************/
 
377
 
 
378
 
 
379
extern vanessa_logger_t *__vanessa_logger_vl;
 
380
extern int errno;
 
381
 
 
382
/**********************************************************************
 
383
 * vanessa_logger_vl_set
 
384
 * set the logger function to use with convenience macros
 
385
 * No logging will take place using conveineince macros if logger is 
 
386
 * set to NULL (default). That is you _must_ call this function to 
 
387
 * enable logging using convenience macros.
 
388
 * pre: logger: pointer to a vanessa_logger
 
389
 * post: logger for ip_vs_nl is set to logger
 
390
 * return: none
 
391
 **********************************************************************/
 
392
 
 
393
#define vanessa_logger_set(_vl) __vanessa_logger_vl=(_vl)
 
394
 
 
395
 
 
396
/**********************************************************************
 
397
 * vanessa_logger_vl_unset
 
398
 * set logger to use with convenience macros to NULL
 
399
 * That is no logging will take place when convenience macros are called
 
400
 * pre: none
 
401
 * post: logger is NULL
 
402
 * return: none
 
403
 **********************************************************************/
 
404
 
 
405
#define vanessa_logger_unset() vanessa_logger_set(NULL)
 
406
 
 
407
 
 
408
/**********************************************************************
 
409
 * vanessa_logger_vl_get
 
410
 * retreive the logger function used by convenience macros
 
411
 * pre: none
 
412
 * post: none
 
413
 * return: logger used by convenience macros
 
414
 **********************************************************************/
 
415
 
 
416
#define vanessa_logger_get() (__vanessa_logger_vl)
 
417
 
 
418
 
 
419
/**********************************************************************
 
420
 * VANESSA_LOGGER_DEBUG et al
 
421
 * Convenience macros for using internal logger set using
 
422
 * vanessa_logger_set()
 
423
 **********************************************************************/
 
424
 
 
425
/*
 
426
 * Hooray for format string problems!
 
427
 *
 
428
 * Each of the logging macros has two versions. The UNSAFE version will
 
429
 * accept a format string. You should _NOT_ use the UNSAFE versions if the
 
430
 * first argument, the format string, is derived from user input. The safe
 
431
 * versions (versions that do not have the "_UNSAFE" suffix) do not accept
 
432
 * a format string and only accept one argument, the string to log. These
 
433
 * should be safe to use with user derived input.
 
434
 */
 
435
 
 
436
#define VANESSA_LOGGER_LOG_UNSAFE(priority, fmt, ...) \
 
437
        vanessa_logger_log(__vanessa_logger_vl, priority, fmt, __VA_ARGS__);
 
438
 
 
439
#define VANESSA_LOGGER_LOG(priority, str) \
 
440
        vanessa_logger_log(__vanessa_logger_vl, priority, "%s", str)
 
441
 
 
442
#define VANESSA_LOGGER_DEBUG_UNSAFE(fmt, ...) \
 
443
        _vanessa_logger_log_prefix(__vanessa_logger_vl, LOG_DEBUG, \
 
444
                __FUNCTION__, fmt, __VA_ARGS__);
 
445
 
 
446
#define VANESSA_LOGGER_DEBUG(str) \
 
447
        _vanessa_logger_log_prefix(__vanessa_logger_vl, LOG_DEBUG, \
 
448
                __FUNCTION__, "%s", str);
 
449
 
 
450
#define VANESSA_LOGGER_DEBUG_ERRNO(str) \
 
451
        _vanessa_logger_log_prefix(__vanessa_logger_vl, LOG_DEBUG, \
 
452
                __FUNCTION__, "%s: %s", str, strerror(errno));
 
453
 
 
454
#define VANESSA_LOGGER_DEBUG_HERRNO(str) \
 
455
        _vanessa_logger_log_prefix(__vanessa_logger_vl, LOG_DEBUG, \
 
456
                __FUNCTION__, "%s: %s", str, \
 
457
                vanessa_logger_strherror(h_errno));
 
458
 
 
459
#define VANESSA_LOGGER_DEBUG_RAW_UNSAFE(fmt, ...) \
 
460
        vanessa_logger_log(__vanessa_logger_vl, LOG_DEBUG, \
 
461
                fmt, __VA_ARGS__);
 
462
 
 
463
#define VANESSA_LOGGER_DEBUG_RAW(str) \
 
464
        vanessa_logger_log(__vanessa_logger_vl, LOG_DEBUG, "%s", str);
 
465
 
 
466
#define VANESSA_LOGGER_INFO_UNSAFE(fmt, ...) \
 
467
        vanessa_logger_log(__vanessa_logger_vl, LOG_INFO, fmt, __VA_ARGS__);
 
468
 
 
469
#define VANESSA_LOGGER_INFO(str) \
 
470
        vanessa_logger_log(__vanessa_logger_vl, LOG_INFO, "%s", str);
 
471
 
 
472
#define VANESSA_LOGGER_ERR_UNSAFE(fmt, ...) \
 
473
        vanessa_logger_log(__vanessa_logger_vl, LOG_ERR, fmt, __VA_ARGS__);
 
474
 
 
475
#define VANESSA_LOGGER_ERR_RAW_UNSAFE(fmt, ...) \
 
476
        vanessa_logger_log(__vanessa_logger_vl, LOG_ERR, fmt, __VA_ARGS__);
 
477
 
 
478
#define VANESSA_LOGGER_ERR(str) \
 
479
        vanessa_logger_log(__vanessa_logger_vl, LOG_ERR, "%s", str);
 
480
 
 
481
#define VANESSA_LOGGER_RAW_ERR(str) \
 
482
        vanessa_logger_log(__vanessa_logger_vl, LOG_ERR, "%s", str);
 
483
 
 
484
#define VANESSA_LOGGER_DUMP(buffer, buffer_length, flag) \
 
485
        vanessa_logger_str_dump(__vanessa_logger_vl, (buffer), \
 
486
                        (buffer_length), (flag))
215
487
 
216
488
#endif