doc/internal/man3/ossl_cmp_print_log.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 ossl_cmp_print_log,
   6 ossl_cmp_alert,
   7 ossl_cmp_err,
   8 ossl_cmp_warn,
   9 ossl_cmp_info,
  10 ossl_cmp_debug,
  11 ossl_cmp_log,
  12 ossl_cmp_log1,
  13 ossl_cmp_log2,
  14 ossl_cmp_log3,
  15 ossl_cmp_log4,
  16 ossl_cmp_log_parse_metadata,
  17 ossl_cmp_add_error_txt,
  18 ossl_cmp_add_error_data,
  19 ossl_cmp_add_error_line
  20 - logging and error reporting support for CMP
  21
  22 =head1 SYNOPSIS
  23
  24  #include "cmp_local.h"
  25
  26  int ossl_cmp_print_log(OSSL_CMP_severity level, const OSSL_CMP_CTX *ctx,
  27                         const char *func, const char *file, int line,
  28                         const char *level_str, const char *format, ...);
  29  #define ossl_cmp_alert(ctx, msg)
  30  #define ossl_cmp_err(ctx, msg)
  31  #define ossl_cmp_warn(ctx, msg)
  32  #define ossl_cmp_info(ctx, msg)
  33  #define ossl_cmp_debug(ctx, (msg)
  34  #define ossl_cmp_log(level, ctx, msg)
  35  #define ossl_cmp_log1(level, ctx, fmt, arg1)
  36  #define ossl_cmp_log2(level, ctx, fmt, arg1, arg2)
  37  #define ossl_cmp_log3(level, ctx, fmt, arg1, arg2, arg3)
  38  #define ossl_cmp_log4(level, ctx, fmt, arg1, arg2, arg3, arg4)
  39  const char *ossl_cmp_log_parse_metadata(const char *buf,
  40                                          OSSL_CMP_severity *level, char **func,
  41                                          char **file, int *line);
  42
  43  void ossl_cmp_add_error_txt(const char *separator, const char *txt);
  44  #define ossl_cmp_add_error_data(txt)
  45  #define ossl_cmp_add_error_line(txt)
  46
  47 =head1 DESCRIPTION
  48
  49 ossl_cmp_print_log() prints CMP log messages (i.e., diagnostic info) via the
  50 log callback of the B<ctx> if present and the severity level is sufficient.
  51 If the trace API if enabled the function uses it, prepending the function name,
  52 filename, line number, and severity information to the message being output.
  53 In any case the B<level>, B<func>, B<file>, and B<line> parameters
  54 and the message constructed using the given B<format> and variable further
  55 argument list are passed to the log callback function (unless it is NULL).
  56 The B<ctx>, B<func>, B<file>, and B<level_str> arguments may be NULL.
  57
  58 ossl_cmp_alert(), ossl_cmp_err(), ossl_cmp_warn(), ossl_cmp_info(), and
  59 ossl_cmp_debug() output a simple alert/error/warning/info/debug message
  60 via ossl_cmp_print_log().
  61
  62 ossl_cmp_log(), ossl_cmp_log1(), ossl_cmp_log2(), ossl_cmp_log3(), and
  63 ossl_cmp_log4() output a log message with the given severity,
  64 constructing the message text from the given format and arguments.
  65
  66 ossl_cmp_log_parse_metadata() parses the given message buffer I<buf> populated
  67 by ossl_cmp_log() etc.
  68 according to the pattern OSSL_CMP_LOG_START#level ": %s\n", filling in
  69 the variable pointed to by I<level> with the severity level or -1,
  70 the variable pointed to by I<func> with the function name string or NULL,
  71 the variable pointed to by I<file> with the filename string or NULL, and
  72 the variable pointed to by I<line> with the line number or -1.
  73 Any string returned via I<*func> and I<*file> must be freeed by the caller.
  74
  75 ossl_cmp_add_error_txt() appends text to the extra data field of the last
  76 error message in the OpenSSL error queue, after adding the optional separator
  77 unless data has been empty so far. The text can be of arbitrary length,
  78 which is not possible when using L<ERR_add_error_data(3)> in conjunction with
  79 L<ERR_print_errors_cb(3)>.
  80
  81 ossl_cmp_add_error_data() is a macro calling
  82 ossl_cmp_add_error_txt() with the separator being ":".
  83
  84 ossl_cmp_add_error_line() is a macro calling
  85 ossl_cmp_add_error_txt() with the separator being "\n".
  86
  87 =head1 RETURN VALUES
  88
  89 ossl_cmp_log_parse_metadata() returns the pointer to the actual message text
  90 after the OSSL_CMP_LOG_PREFIX and level and ':' if found in the buffer,
  91 else the beginning of the buffer.
  92
  93 ossl_cmp_add_error_txt()
  94 ossl_cmp_add_error_data(), and
  95 ossl_cmp_add_error_line()
  96 do not return anything.
  97
  98 All other functions return 1 on success, 0 on error.
  99
 100 =head1 HISTORY
 101
 102 The OpenSSL CMP support was added in OpenSSL 3.0.
 103
 104 =head1 COPYRIGHT
 105
 106 Copyright 2007-2019 The OpenSSL Project Authors. All Rights Reserved.
 107
 108 Licensed under the Apache License 2.0 (the "License").  You may not use
 109 this file except in compliance with the License.  You can obtain a copy
 110 in the file LICENSE in the source distribution or at
 111 L<https://www.openssl.org/source/license.html>.
 112
 113 =cut