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