mozglue/misc/Debug.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim: set ts=8 sts=2 et sw=2 tw=80: */
   3 /* This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
   6
   7 #ifndef mozilla_glue_Debug_h
   8 #define mozilla_glue_Debug_h
   9
  10 #include "mozilla/Attributes.h"  // For MOZ_FORMAT_PRINTF
  11 #include "mozilla/Types.h"       // For MFBT_API
  12
  13 #include <cstdarg>
  14 #include <sstream>
  15
  16 /* This header file intends to supply debugging utilities for use in code
  17  * that cannot use XPCOM debugging facilities like nsDebug.h.
  18  * e.g. mozglue, browser/app
  19  *
  20  * NB: printf_stderr() is in the global namespace, so include this file with
  21  * care; avoid including from header files.
  22  */
  23
  24 #ifdef __cplusplus
  25 extern "C" {
  26 #endif  // __cplusplus
  27
  28 /**
  29  * printf_stderr(...) is much like fprintf(stderr, ...), except that:
  30  *  - on Android and Firefox OS, *instead* of printing to stderr, it
  31  *    prints to logcat.  (Newlines in the string lead to multiple lines
  32  *    of logcat, but each function call implicitly completes a line even
  33  *    if the string does not end with a newline.)
  34  *  - on Windows, if a debugger is present, it calls OutputDebugString
  35  *    in *addition* to writing to stderr
  36  */
  37 MFBT_API void printf_stderr(const char* aFmt, ...) MOZ_FORMAT_PRINTF(1, 2);
  38
  39 /**
  40  * Same as printf_stderr, but taking va_list instead of varargs
  41  */
  42 MFBT_API void vprintf_stderr(const char* aFmt, va_list aArgs)
  43     MOZ_FORMAT_PRINTF(1, 0);
  44
  45 /**
  46  * fprintf_stderr is like fprintf, except that if its file argument
  47  * is stderr, it invokes printf_stderr instead.
  48  *
  49  * This is useful for general debugging code that logs information to a
  50  * file, but that you would like to be useful on Android and Firefox OS.
  51  * If you use fprintf_stderr instead of fprintf in such debugging code,
  52  * then callers can pass stderr to get logging that works on Android and
  53  * Firefox OS (and also the other side-effects of using printf_stderr).
  54  *
  55  * Code that is structured this way needs to be careful not to split a
  56  * line of output across multiple calls to fprintf_stderr, since doing
  57  * so will cause it to appear in multiple lines in logcat output.
  58  * (Producing multiple lines at once is fine.)
  59  */
  60 MFBT_API void fprintf_stderr(FILE* aFile, const char* aFmt, ...)
  61     MOZ_FORMAT_PRINTF(2, 3);
  62
  63 /*
  64  * print_stderr and fprint_stderr are like printf_stderr and fprintf_stderr,
  65  * except they deal with Android logcat line length limitations. They do this
  66  * by printing individual lines out of the provided stringstream using separate
  67  * calls to logcat.
  68  */
  69 MFBT_API void print_stderr(std::stringstream& aStr);
  70 MFBT_API void fprint_stderr(FILE* aFile, std::stringstream& aStr);
  71
  72 #ifdef __cplusplus
  73 }
  74 #endif  // __cplusplus
  75
  76 #endif  // mozilla_glue_Debug_h