blob: 46b3aeb1dd8af3dedc034072ab933fec6e3ceb91 [file] [log] [blame]
// Copyright 2015 The Cobalt Authors. All Rights Reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
// Module Overview: Starboard Logging module
//
// Defines core debug logging functions.
#ifndef STARBOARD_LOG_H_
#define STARBOARD_LOG_H_
#include <stdarg.h>
#include "starboard/configuration.h"
#include "starboard/export.h"
#include "starboard/system.h"
#ifdef __cplusplus
extern "C" {
#endif
// The priority at which a message should be logged. The platform may be
// configured to filter logs by priority, or render them differently.
typedef enum SbLogPriority {
kSbLogPriorityUnknown = 0,
kSbLogPriorityInfo,
kSbLogPriorityWarning,
kSbLogPriorityError,
kSbLogPriorityFatal,
} SbLogPriority;
// Writes |message| to the platform's debug output log. This method is
// thread-safe, and responsible for ensuring that the output from multiple
// threads is not mixed.
//
// |priority|: The SbLogPriority at which the message should be logged. Note
// that passing |kSbLogPriorityFatal| does not terminate the program. Such a
// policy must be enforced at the application level. In fact, |priority| may
// be completely ignored on many platforms.
// |message|: The message to be logged. Must not be NULL. No formatting is
// required to be done
// on the value, including newline termination. That said, platforms can
// adjust the message to be more suitable for their output method by
// wrapping the text, stripping unprintable characters, etc.
SB_EXPORT void SbLog(SbLogPriority priority, const char* message);
// A bare-bones log output method that is async-signal-safe, i.e. safe to call
// from an asynchronous signal handler (e.g. a |SIGSEGV| handler). It should not
// do any additional formatting.
//
// |message|: The message to be logged. Must not be NULL.
SB_EXPORT void SbLogRaw(const char* message);
// Dumps the stack of the current thread to the log in an async-signal-safe
// manner, i.e. safe to call from an asynchronous signal handler (e.g. a
// |SIGSEGV| handler). Does not include SbLogRawDumpStack itself.
//
// |frames_to_skip|: The number of frames to skip from the top of the stack
// when dumping the current thread to the log. This parameter lets you remove
// noise from helper functions that might end up on top of every stack dump
// so that the stack dump is just the relevant function stack where the
// problem occurred.
SB_EXPORT void SbLogRawDumpStack(int frames_to_skip);
// A formatted log output method that is async-signal-safe, i.e. safe to call
// from an asynchronous signal handler (e.g. a |SIGSEGV| handler).
SB_EXPORT void SbLogRawFormat(const char* format, va_list args)
SB_PRINTF_FORMAT(1, 0);
// Inline wrapper of SbLogFormat to convert from ellipsis to va_args.
static SB_C_INLINE void SbLogRawFormatF(const char* format, ...)
SB_PRINTF_FORMAT(1, 2);
static SB_C_INLINE void SbLogRawFormatF(const char* format, ...) {
va_list args;
va_start(args, format);
SbLogRawFormat(format, args);
va_end(args);
}
// A log output method that additionally performs a string format on the
// data being logged.
SB_EXPORT void SbLogFormat(const char* format, va_list args)
SB_PRINTF_FORMAT(1, 0);
// Inline wrapper of SbLogFormat that converts from ellipsis to va_args.
static SB_C_INLINE void SbLogFormatF(const char* format, ...)
SB_PRINTF_FORMAT(1, 2);
static SB_C_INLINE void SbLogFormatF(const char* format, ...) {
va_list args;
va_start(args, format);
SbLogFormat(format, args);
va_end(args);
}
// Flushes the log buffer on some platforms. This method is safe to call from
// multiple threads.
SB_EXPORT void SbLogFlush();
// Indicates whether the log output goes to a TTY or is being redirected.
SB_EXPORT bool SbLogIsTty();
#ifdef __cplusplus
} // extern "C"
#endif
#endif // STARBOARD_LOG_H_