libkern/os/log.h

   1 /*
   2  * Copyright (c) 2015 Apple Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. Please obtain a copy of the License at
  10  * http://www.opensource.apple.com/apsl/ and read it before using this
  11  * file.
  12  *
  13  * The Original Code and all software distributed under the License are
  14  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18  * Please see the License for the specific language governing rights and
  19  * limitations under the License.
  20  *
  21  * @APPLE_LICENSE_HEADER_END@
  22  */
  23
  24 #ifndef __os_log_h
  25 #define __os_log_h
  26
  27 #include <os/object.h>
  28 #include <stdint.h>
  29 #include <stdbool.h>
  30
  31 #ifndef __has_attribute
  32 #define __has_attribute(x) 0
  33 #endif
  34
  35 #ifndef __has_builtin
  36 #define __has_builtin(x) 0
  37 #endif
  38
  39 #if __has_attribute(not_tail_called)
  40 #define OS_LOG_NOTAILCALL __attribute__((not_tail_called))
  41 #define OS_LOG_NOTAILCALL_MARKER
  42 #else
  43 #define OS_LOG_NOTAILCALL
  44 #define OS_LOG_NOTAILCALL_MARKER __asm__("")
  45 #endif
  46
  47 __BEGIN_DECLS
  48
  49 extern void *__dso_handle;
  50
  51 OS_ALWAYS_INLINE static inline void _os_log_verify_format_str(__unused const char *msg, ...) __attribute__((format(os_trace, 1, 2)));
  52 OS_ALWAYS_INLINE static inline void _os_log_verify_format_str(__unused const char *msg, ...) { /* placeholder */ }
  53
  54 #if OS_OBJECT_USE_OBJC
  55 OS_OBJECT_DECL(os_log);
  56 #else
  57 typedef struct os_log_s *os_log_t;
  58 #endif /* OS_OBJECT_USE_OBJC */
  59
  60 /*!
  61  * @const OS_LOG_DISABLED
  62  *
  63  * @discussion
  64  * Use this to disable a specific log message.
  65  */
  66 #define OS_LOG_DISABLED NULL
  67
  68 /*!
  69  * @const OS_LOG_DEFAULT
  70  *
  71  * @discussion
  72  * Use this to log a message in accordance with current system settings.
  73  */
  74 #define OS_LOG_DEFAULT OS_OBJECT_GLOBAL_OBJECT(os_log_t, _os_log_default)
  75 __OSX_AVAILABLE_STARTING(__MAC_10_12,__IPHONE_10_0)
  76 OS_EXPORT
  77 struct os_log_s _os_log_default;
  78
  79 /*!
  80  * @enum os_log_type_t
  81  *
  82  * @discussion
  83  * Supported log message types.
  84  *
  85  * @constant OS_LOG_TYPE_DEFAULT
  86  * Equivalent type for "os_log()" messages, i.e., default messages that are always
  87  * captured to memory or disk.
  88  *
  89  * @constant OS_LOG_TYPE_INFO
  90  * Equivalent type for "os_log_info()" messages, i.e., Additional informational messages.
  91  *
  92  * @constant OS_LOG_TYPE_DEBUG
  93  * Equivalent type for "os_log_debug()" messages, i.e., Debug messages.
  94  *
  95  * @constant OS_LOG_TYPE_ERROR
  96  * Equivalent type for "os_log_error()" messages, i.e., local process error messages.
  97  *
  98  * @constant OS_LOG_TYPE_FAULT
  99  * Equivalent type for "os_log_fault()" messages, i.e., a system error that involves
 100  * potentially more than one process, usually used by daemons and services.
 101  */
 102 OS_ENUM(os_log_type, uint8_t,
 103         OS_LOG_TYPE_DEFAULT = 0x00,
 104         OS_LOG_TYPE_INFO    = 0x01,
 105         OS_LOG_TYPE_DEBUG   = 0x02,
 106         OS_LOG_TYPE_ERROR   = 0x10,
 107         OS_LOG_TYPE_FAULT   = 0x11);
 108
 109 /*!
 110  * @function os_log_create
 111  *
 112  * @abstract
 113  * Creates a log object to be used with other log related functions.
 114  *
 115  * @discussion
 116  * Creates a log object to be used with other log related functions.  The
 117  * log object serves two purposes:  (1) tag related messages by subsystem
 118  * and category name for easy filtering, and (2) control logging system
 119  * behavior for messages.
 120  *
 121  * A log object may customize logging system behavior for its messages by
 122  * adding a configuration file in /Library/LogPreferences. Most options
 123  * accept 3 values: "Default", "Yes" or "No" as strings, where "Default"
 124  * signifies follow system behavior for the level of messages.
 125  *
 126  * For log:
 127  *
 128  *      os_log_create("com.company.mysubsystem", "connections");
 129  *
 130  * System-provided preferences are located in /System/Library/LogPreferences/<subsystem>.plist
 131  *
 132  *      <dict>
 133  *
 134  *          <!-- Default options applied to message types in each category, which can be overriden. -->
 135  *          <key>DEFAULT-OPTIONS</key>
 136  *          <dict>
 137  *              <key>Enabled</key>              <!-- Enabled state follows system defaults -->
 138  *              <string>Default</string>
 139  *              <key>Persist</key>              <!-- Do not persist to disk, use memory-only buffer if enabled -->
 140  *              <string>No</string>
 141  *              <key>TTL</key>                  <!-- Follow system default behavior if persistence is enabled -->
 142  *              <string>Default</string>        <!-- Can specify in days with "d" or hours "h" (e.g., "4h" = 4 hours) -->
 143  *          </dict>
 144  *
 145  *          <!-- category named “connections” -->
 146  *          <key>connections</key>
 147  *          <dict>
 148  *
 149  *              <!-- Options that control "os_log()" behavior.  The "Enabled" option is ignored. -->
 150  *              <key>Default</key>
 151  *              <dict>
 152  *                  <key>Persist</key>          <!-- Always persist to disk -->
 153  *                  <string>Yes</string>
 154  *                  <key>TTL</key>              <!-- Store default messages for maximum 4 days -->
 155  *                  <integer>4d</integer>
 156  *              </dict>
 157  *
 158  *              <!-- Subdictionary of options that control "os_log_info()" behavior -->
 159  *              <key>Info</key>
 160  *              <dict>
 161  *                  <key>Persist</key>          <!-- If enabled persist to disk -->
 162  *                  <string>Yes</string>
 163  *                  <key>TTL</key>              <!-- Store Info messages for 2 days -->
 164  *                  <string>2d</string>
 165  *              </dict>
 166  *
 167  *              <!-- Subdictionary of options that control "os_log_debug()" behavior -->
 168  *              <key>Debug</key>
 169  *              <dict>
 170  *                  <key>Enabled</key>          <!-- Not enabled, must be enabled specifically -->
 171  *                  <string>No</string>
 172  *              </dict>
 173  *          </dict>
 174  *      </dict>
 175  *
 176  * All other preferences and system-overrides are stored in /Library/LogPreferences/.
 177  *
 178  * @param subsystem
 179  * The identifier of the given subsystem should be in reverse DNS form
 180  * (i.e., com.company.mysubsystem).  This string must be a constant string,
 181  * not dynamically generated.
 182  *
 183  * @param category
 184  * The category within the given subsystem that specifies the settings for
 185  * the log object.  This string must be a constant string, not dynamically
 186  * generated.
 187  *
 188  * @result
 189  * Returns an os_log_t value to be passed to other os_log API calls.  This
 190  * should be called once at log initialization and rely on system to detect
 191  * changes to settings.  This object should be released when no longer used
 192  * via os_release or -[release] method.
 193  *
 194  * A value will always be returned to allow for dynamic enablement.
 195  */
 196 __OSX_AVAILABLE_STARTING(__MAC_10_12,__IPHONE_10_0)
 197 OS_EXPORT OS_NOTHROW OS_WARN_RESULT OS_OBJECT_RETURNS_RETAINED
 198 os_log_t
 199 os_log_create(const char *subsystem, const char *category);
 200
 201 /*!
 202  * @function os_log_info_enabled
 203  *
 204  * @abstract
 205  * Returns if development log messages are enabled for a particular log object.
 206  *
 207  * @discussion
 208  * Returns if development log messages are enabled for a particular log object.
 209  *
 210  * @param log
 211  * Pass OS_LOG_DEFAULT or a log object previously created with os_log_create.
 212  *
 213  * @result
 214  * Returns ‘true’ if debug log messages are enabled.
 215  */
 216 __WATCHOS_AVAILABLE(3.0) __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0)
 217 OS_EXPORT OS_NOTHROW OS_WARN_RESULT
 218 bool
 219 os_log_info_enabled(os_log_t log);
 220
 221 /*!
 222  * @function os_log_debug_enabled
 223  *
 224  * @abstract
 225  * Returns if debug log messages are enabled for a particular log object.
 226  *
 227  * @discussion
 228  * Returns if debug log messages are enabled for a particular log object.
 229  *
 230  * @param log
 231  * Pass OS_LOG_DEFAULT or a log object previously created with os_log_create.
 232  *
 233  * @result
 234  * Returns ‘true’ if debug log messages are enabled.
 235  */
 236 __WATCHOS_AVAILABLE(3.0) __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0)
 237 OS_EXPORT OS_NOTHROW OS_WARN_RESULT
 238 bool
 239 os_log_debug_enabled(os_log_t log);
 240
 241 /*!
 242  * @function os_log
 243  *
 244  * @abstract
 245  * Insert a log message into the Unified Logging and Tracing system.
 246  *
 247  * @discussion
 248  * Insert a log message into the Unified Logging and Tracing system in
 249  * accordance with the preferences specified by the provided log object.
 250  * These messages cannot be disabled and therefore always captured either
 251  * to memory or disk.
 252  *
 253  * When an os_activity_id_t is present, the log message will also be scoped by
 254  * that identifier.  Activities provide granular filtering of log messages
 255  * across threads and processes.
 256  *
 257  * There is a physical cap of 256 bytes per entry for dynamic content,
 258  * i.e., %s and %@, that can be written to the persistence store.  As such,
 259  * all content exceeding the limit will be truncated before written to disk.
 260  * Live streams will continue to show the full content.
 261  *
 262  * @param log
 263  * Pass OS_LOG_DEFAULT or a log object previously created with os_log_create.
 264  *
 265  * @param format
 266  * A format string to generate a human-readable log message when the log
 267  * line is decoded.  This string must be a constant string, not dynamically
 268  * generated.  Supports all standard printf types and %@ (objects).
 269  */
 270 #define os_log(log, format, ...) __extension__({                                                \
 271     _Static_assert(__builtin_constant_p(format), "format string must be constant");             \
 272     __attribute__((section("__TEXT,__os_log"))) static const char _os_log_fmt[] = format;       \
 273     _os_log_verify_format_str(format, ##__VA_ARGS__);                                           \
 274     _os_log_internal(&__dso_handle, log, OS_LOG_TYPE_DEFAULT, _os_log_fmt, ##__VA_ARGS__);      \
 275     __asm__(""); /* avoid tailcall */                                                           \
 276 })
 277
 278 /*!
 279  * @function os_log_info
 280  *
 281  * @abstract
 282  * Insert a development log message into the Unified Logging and Tracing system.
 283  *
 284  * @discussion
 285  * Insert a log message into the Unified Logging and Tracing system in
 286  * accordance with the preferences specified by the provided log object.
 287  *
 288  * When an os_activity_id_t is present, the log message will also be scoped by
 289  * that identifier.  Activities provide granular filtering of log messages
 290  * across threads and processes.
 291  *
 292  * There is a physical cap of 256 bytes per entry for dynamic content,
 293  * i.e., %s and %@, that can be written to the persistence store.  As such,
 294  * all content exceeding the limit will be truncated before written to disk.
 295  * Live streams will continue to show the full content.
 296  *
 297  * @param log
 298  * Pass OS_LOG_DEFAULT or a log object previously created with os_log_create.
 299  *
 300  * @param format
 301  * A format string to generate a human-readable log message when the log
 302  * line is decoded.  This string must be a constant string, not dynamically
 303  * generated.  Supports all standard printf types and %@ (objects).
 304  */
 305 #define os_log_info(log, format, ...) __extension__({                                       \
 306     _Static_assert(__builtin_constant_p(format), "format string must be constant");         \
 307     __attribute__((section("__TEXT,__os_log"))) static const char _os_log_fmt[] = format;   \
 308     _os_log_verify_format_str(format, ##__VA_ARGS__);                                       \
 309     _os_log_internal(&__dso_handle, log, OS_LOG_TYPE_INFO, _os_log_fmt, ##__VA_ARGS__);     \
 310     __asm__(""); /* avoid tailcall */                                                       \
 311 })
 312
 313 /*!
 314  * @function os_log_debug
 315  *
 316  * @abstract
 317  * Insert a debug log message into the Unified Logging and Tracing system.
 318  *
 319  * @discussion
 320  * Insert a debug log message into the Unified Logging and Tracing system in
 321  * accordance with the preferences specified by the provided log object.
 322  *
 323  * When an os_activity_id_t is present, the log message will also be scoped by
 324  * that identifier.  Activities provide granular filtering of log messages
 325  * across threads and processes.
 326  *
 327  * There is a physical cap of 256 bytes per entry for dynamic content,
 328  * i.e., %s and %@, that can be written to the persistence store.  As such,
 329  * all content exceeding the limit will be truncated before written to disk.
 330  * Live streams will continue to show the full content.
 331  *
 332  * @param log
 333  * Pass OS_LOG_DEFAULT or a log object previously created with os_log_create.
 334  *
 335  * @param format
 336  * A format string to generate a human-readable log message when the log
 337  * line is decoded.  This string must be a constant string, not dynamically
 338  * generated.  Supports all standard printf types and %@ (objects).
 339  */
 340 #define os_log_debug(log, format, ...) __extension__({                                          \
 341     _Static_assert(__builtin_constant_p(format), "format string must be constant");             \
 342     __attribute__((section("__TEXT,__os_log"))) static const char _os_log_fmt[] = format;       \
 343     _os_log_verify_format_str(format, ##__VA_ARGS__);                                           \
 344     _os_log_internal(&__dso_handle, log, OS_LOG_TYPE_DEBUG, _os_log_fmt, ##__VA_ARGS__);        \
 345     __asm__(""); /* avoid tailcall */                                                           \
 346 })
 347
 348 /*!
 349  * @function os_log_error
 350  *
 351  * @abstract
 352  * Insert an error log message into the Unified Logging and Tracing system.
 353  *
 354  * @discussion
 355  * Insert an error log message into the Unified Logging and Tracing system.
 356  *
 357  * When an os_activity_id_t is present, the log message will also be scoped by
 358  * that identifier.  Activities provide granular filtering of log messages
 359  * across threads and processes.
 360  *
 361  * There is a physical cap of 256 bytes per entry for dynamic content,
 362  * i.e., %s and %@, that can be written to the persistence store.  As such,
 363  * all content exceeding the limit will be truncated before written to disk.
 364  * Live streams will continue to show the full content.
 365  *
 366  * @param log
 367  * Pass OS_LOG_DEFAULT or a log object previously created with os_log_create.
 368  *
 369  * @param format
 370  * A format string to generate a human-readable log message when the log
 371  * line is decoded.  This string must be a constant string, not dynamically
 372  * generated.  Supports all standard printf types and %@ (objects).
 373  */
 374 #define os_log_error(log, format, ...) __extension__({                                          \
 375     _Static_assert(__builtin_constant_p(format), "format string must be constant");             \
 376     __attribute__((section("__TEXT,__os_log"))) static const char _os_log_fmt[] = format;       \
 377     _os_log_verify_format_str(format, ##__VA_ARGS__);                                           \
 378     _os_log_internal(&__dso_handle, log, OS_LOG_TYPE_ERROR, _os_log_fmt, ##__VA_ARGS__);        \
 379     __asm__(""); /* avoid tailcall */                                                           \
 380 })
 381
 382 /*!
 383  * @function os_log_fault
 384  *
 385  * @abstract
 386  * Insert a fault log message into the Unified Logging and Tracing system.
 387  *
 388  * @discussion
 389  * Log a fault message issue into the Unified Logging and Tracing system
 390  * signifying a multi-process (i.e., system error) related issue, either
 391  * due to interaction via IPC or some other.  Faults will gather information
 392  * from the entire process chain and record it for later inspection.
 393  *
 394  * When an os_activity_id_t is present, the log message will also be scoped by
 395  * that identifier.  Activities provide granular filtering of log messages
 396  * across threads and processes.
 397  *
 398  * There is a physical cap of 256 bytes per entry for dynamic content,
 399  * i.e., %s and %@, that can be written to the persistence store.  As such,
 400  * all content exceeding the limit will be truncated before written to disk.
 401  * Live streams will continue to show the full content.
 402  *
 403  * @param log
 404  * Pass OS_LOG_DEFAULT or a log object previously created with os_log_create.
 405  *
 406  * @param format
 407  * A format string to generate a human-readable log message when the log
 408  * line is decoded.  This string must be a constant string, not dynamically
 409  * generated.  Supports all standard printf types and %@ (objects).
 410  */
 411 #define os_log_fault(log, format, ...) __extension__({                                          \
 412     _Static_assert(__builtin_constant_p(format), "format string must be constant");             \
 413     __attribute__((section("__TEXT,__os_log"))) static const char _os_log_fmt[] = format;       \
 414     _os_log_verify_format_str(format, ##__VA_ARGS__);                                           \
 415     _os_log_internal(&__dso_handle, log, OS_LOG_TYPE_FAULT, _os_log_fmt, ##__VA_ARGS__);        \
 416     __asm__(""); /* avoid tailcall */                                                           \
 417 })
 418
 419 /*!
 420  * @function os_log_with_type
 421  *
 422  * @abstract
 423  * Log a message using a specific type.
 424  *
 425  * @discussion
 426  * Will log a message with the provided os_log_type_t.
 427  *
 428  * @param log
 429  * Pass OS_LOG_DEFAULT or a log object previously created with os_log_create.
 430  *
 431  * @param type
 432  * Pass a valid type from os_log_type_t.
 433  *
 434  * @param format
 435  * A format string to generate a human-readable log message when the log
 436  * line is decoded.  This string must be a constant string, not dynamically
 437  * generated.  Supports all standard printf types and %@ (objects).
 438  */
 439 #define os_log_with_type(log, type, format, ...) __extension__({                            \
 440     _Static_assert(__builtin_constant_p(format), "format string must be constant");         \
 441     __attribute__((section("__TEXT,__os_log"))) static const char _os_log_fmt[] = format;   \
 442     _os_log_verify_format_str(format, ##__VA_ARGS__);                                       \
 443     _os_log_internal(&__dso_handle, log, type, _os_log_fmt, ##__VA_ARGS__);                 \
 444     __asm__(""); /* avoid tailcall */                                                       \
 445 })
 446
 447 /*!
 448  * @function os_log_sensitive_debug
 449  *
 450  * @abstract
 451  * Insert a debug log message containing sensitive content (i.e., personal
 452  * identifying information).
 453  *
 454  * @discussion
 455  * Insert a debug log message containing sensitive content (i.e., personal
 456  * identifying information) in accordance with the preferences specified by
 457  * the provided log object.
 458  *
 459  * All strings are considered potentially sensitive, though this call
 460  * specifically signifies the message as containing sensitive content.
 461  * The message will be stored separately from other messages.
 462  *
 463  * When an os_activity_id_t is present, the log message will also be scoped by
 464  * that identifier.  Activities provide granular filtering of log messages
 465  * across threads and processes.
 466  *
 467  * There is a physical cap of 256 bytes per entry for dynamic content,
 468  * i.e., %s and %@, that can be written to the persistence store.  As such,
 469  * all content exceeding the limit will be truncated before written to disk.
 470  * Live streams will continue to show the full content.
 471  *
 472  * @param log
 473  * Pass OS_LOG_DEFAULT or a log object previously created with os_log_create.
 474  *
 475  * @param format
 476  * A format string to generate a human-readable log message when the log
 477  * line is decoded.  This string must be a constant string, not dynamically
 478  * generated.  Supports all standard printf types and %@ (objects).
 479  */
 480 #define os_log_sensitive_debug(log, format, ...) __extension__({                                                      \
 481     _Static_assert(__builtin_constant_p(format), "format string must be constant");                                   \
 482     __attribute__((section("__TEXT,__os_log_sens"))) static const char _os_log_fmt[] = format;                        \
 483     _os_log_verify_format_str(format, ##__VA_ARGS__);                                                                 \
 484     _os_log_sensitive(&__dso_handle, log, OS_LOG_TYPE_DEBUG, _os_log_fmt, ##__VA_ARGS__);                             \
 485     __asm__(""); /* avoid tailcall */                                                                                 \
 486 })
 487
 488 /*!
 489  * @function _os_log_internal
 490  *
 491  * @abstract
 492  * Internal function used by macros.
 493  */
 494 __WATCHOS_AVAILABLE(3.0) __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) __TVOS_AVAILABLE(10.0)
 495 OS_EXPORT OS_NOTHROW
 496 void
 497 _os_log_internal(void *dso, os_log_t log, os_log_type_t type, const char *message, ...);
 498
 499 __END_DECLS
 500
 501 #endif /* __os_log_h */