[apple/xnu.git] / bsd / sys / fslog.h

/*
 * Copyright (c) 2006 Apple Computer, Inc. All rights reserved.
 *
 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
 * 
 * This file contains Original Code and/or Modifications of Original Code
 * as defined in and that are subject to the Apple Public Source License
 * Version 2.0 (the 'License'). You may not use this file except in
 * compliance with the License. The rights granted to you under the License
 * may not be used to create, or enable the creation or redistribution of,
 * unlawful or unlicensed copies of an Apple operating system, or to
 * circumvent, violate, or enable the circumvention or violation of, any
 * terms of an Apple operating system software license agreement.
 * 
 * Please obtain a copy of the License at
 * http://www.opensource.apple.com/apsl/ and read it before using this file.
 * 
 * The Original Code and all software distributed under the License are
 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
 * Please see the License for the specific language governing rights and
 * limitations under the License.
 * 
 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
 */

#ifndef	_FSLOG_H_
#define _FSLOG_H_

#include <sys/syslog.h>
#include <sys/mount.h>
#include <machine/limits.h>

#ifdef KERNEL
/* Log file system related error in key-value format identified by Apple 
 * system log (ASL) facility.  The key-value pairs are string pointers 
 * (char *) and are provided as variable arguments list.  A NULL value 
 * indicates end of the list.
 *
 * Keys can not contain '[', ']', space, and newline.  Values can not 
 * contain '[', ']', and newline.  If any key-value contains any of the 
 * reserved characters, the behavior is undefined.  The caller of the 
 * function should escape any occurrences of '[' and ']' by prefixing
 * it with '\'.
 * 
 * The function takes a message ID which can be used to logically group
 * different ASL messages.  Messages in same logical group have same message
 * ID and have information to describe order of the message --- first, 
 * middle, or last.
 *
 * The following message IDs have special meaning - 
 * FSLOG_MSG_FIRST - This message is the first message in its logical
 *	group.  This generates a unique message ID, creates two key-value 
 *	pairs with message ID and order of the message as "First".
 * FSLOG_MSG_LAST - This is really a MASK which should be logically OR'ed 
 *	with message ID to indicate the last message for a logical group.  
 *	This also creates two key-value pairs with message ID and order of 
 *	message as "Last".
 * FSLOG_MSG_SINGLE - This signifies that the message is the only message
 * 	in its logical group.  Therefore no extra key-values are generated 
 *	for this option.
 * For all other values of message IDs, it regards them as intermediate 
 * message and generates two key-value pairs with message ID and order of
 * message as "Middle".
 * 
 * Returns - 
 *	Message ID of the ASL message printed.  The caller should use
 * 	this value to print intermediate messages or end the logical message
 *	group.
 *	For FSLOG_MSG_SINGLE option, it returns FSLOG_MSG_SINGLE. 
 */
unsigned long fslog_err(unsigned long msg_id, ... );

/* Reserved message IDs to determine message order */
#define FSLOG_MSG_SINGLE	ULONG_MAX
#define FSLOG_MSG_FIRST		0x0
#define FSLOG_MSG_LAST		(~(ULONG_MAX >> 1)) 

#ifdef BSD_KERNEL_PRIVATE

/* Log information about runtime file system corruption detected */
void fslog_fs_corrupt(struct mount *mnt);

/* Log information about IO error detected */
void fslog_io_error(const buf_t bp);

#endif /* BSD_KERNEL_PRIVATE */

#ifdef XNU_KERNEL_PRIVATE

/* Log information about external modification of a target process */
void fslog_extmod_msgtracer(proc_t caller, proc_t target);

#endif /* XNU_KERNEL_PRIVATE */

#endif /* KERNEL */

/* Keys used by FSLog */
#define FSLOG_KEY_FACILITY	"Facility"	/* Facility generating messages */
#define FSLOG_KEY_LEVEL		"Level"		/* Priority level */
#define FSLOG_KEY_MSG_ID	"FSLogMsgID"	/* Message ID */
#define FSLOG_KEY_MSG_ORDER	"FSLogMsgOrder"	/* Message Order */
#define FSLOG_KEY_READ_UID	"ReadUID"	/* Allow read access to this UID only */

/* Values for message order (FSLOG_KEY_MSG_ORDER) */
#define FSLOG_VAL_ORDER_FIRST	"First"		
#define FSLOG_VAL_ORDER_MIDDLE	"Middle"
#define FSLOG_VAL_ORDER_LAST 	"Last"

/* Values used by FSLog */
#define FSLOG_VAL_FACILITY	"com.apple.system.fs" /* Facility generating messages */
#define FSLOG_VAL_LEVEL		LOG_ERR		/* Priority level */
#define FSLOG_VAL_READ_UID	0		/* Allow read access to root only */

/* Keys for IO/FS logging using FSLog */
#define	FSLOG_KEY_ERR_TYPE	"ErrType"	/* Type of problem (IO, FS Corruption) */
#define	FSLOG_KEY_ERRNO		"ErrNo"		/* Error number (Integer) */
#define FSLOG_KEY_IOTYPE	"IOType"	/* Type of IO (Read/Write) */
#define FSLOG_KEY_PHYS_BLKNUM	"PBlkNum"	/* Physical block number */
#define FSLOG_KEY_LOG_BLKNUM	"LBlkNum"	/* Logical block number */
#define FSLOG_KEY_DEVNODE	"DevNode"	/* Device node (f_mntfromname) */
#define FSLOG_KEY_PATH		"Path"		/* File system path */
#define FSLOG_KEY_MNTPT		"MountPt"	/* Mount point */

/* Values for type of error (FSLOG_KEY_ERR_TYPE) */
#define FSLOG_VAL_ERR_TYPE_IO	"IO"		/* IO error */
#define FSLOG_VAL_ERR_TYPE_FS	"FS"		/* FS error */

/* Values for type of operation (FSLOG_KEY_IOTYPE) */
#define FSLOG_VAL_IOTYPE_READ	"Read"
#define FSLOG_VAL_IOTYPE_WRITE	"Write"

#endif /* !_FSLOG_H_ */
Commit	Line	Data
2d21ac55 A	1	/*
	2	* Copyright (c) 2006 Apple Computer, Inc. All rights reserved.
	3	*
	4	* @APPLE_OSREFERENCE_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. The rights granted to you under the License
	10	* may not be used to create, or enable the creation or redistribution of,
	11	* unlawful or unlicensed copies of an Apple operating system, or to
	12	* circumvent, violate, or enable the circumvention or violation of, any
	13	* terms of an Apple operating system software license agreement.
	14	*
	15	* Please obtain a copy of the License at
	16	* http://www.opensource.apple.com/apsl/ and read it before using this file.
	17	*
	18	* The Original Code and all software distributed under the License are
	19	* distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
	20	* EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
	21	* INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
	22	* FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
	23	* Please see the License for the specific language governing rights and
	24	* limitations under the License.
	25	*
	26	* @APPLE_OSREFERENCE_LICENSE_HEADER_END@
	27	*/
	28
	29	#ifndef _FSLOG_H_
	30	#define _FSLOG_H_
	31
	32	#include <sys/syslog.h>
	33	#include <sys/mount.h>
	34	#include <machine/limits.h>
	35
	36	#ifdef KERNEL
	37	/* Log file system related error in key-value format identified by Apple
	38	* system log (ASL) facility. The key-value pairs are string pointers
	39	* (char *) and are provided as variable arguments list. A NULL value
	40	* indicates end of the list.
	41	*
	42	* Keys can not contain '[', ']', space, and newline. Values can not
	43	* contain '[', ']', and newline. If any key-value contains any of the
	44	* reserved characters, the behavior is undefined. The caller of the
	45	* function should escape any occurrences of '[' and ']' by prefixing
	46	* it with '\'.
	47	*
	48	* The function takes a message ID which can be used to logically group
	49	* different ASL messages. Messages in same logical group have same message
	50	* ID and have information to describe order of the message --- first,
	51	* middle, or last.
	52	*
	53	* The following message IDs have special meaning -
	54	* FSLOG_MSG_FIRST - This message is the first message in its logical
	55	* group. This generates a unique message ID, creates two key-value
	56	* pairs with message ID and order of the message as "First".
	57	* FSLOG_MSG_LAST - This is really a MASK which should be logically OR'ed
	58	* with message ID to indicate the last message for a logical group.
	59	* This also creates two key-value pairs with message ID and order of
	60	* message as "Last".
	61	* FSLOG_MSG_SINGLE - This signifies that the message is the only message
	62	* in its logical group. Therefore no extra key-values are generated
	63	* for this option.
	64	* For all other values of message IDs, it regards them as intermediate
65	* message and generates two key-value pairs with message ID and order of
66	* message as "Middle".
67	*
68	* Returns -
69	* Message ID of the ASL message printed. The caller should use
70	* this value to print intermediate messages or end the logical message
71	* group.
72	* For FSLOG_MSG_SINGLE option, it returns FSLOG_MSG_SINGLE.
73	*/
74	unsigned long fslog_err(unsigned long msg_id, ... );
75
76	/* Reserved message IDs to determine message order */
77	#define FSLOG_MSG_SINGLE ULONG_MAX
78	#define FSLOG_MSG_FIRST 0x0
79	#define FSLOG_MSG_LAST (~(ULONG_MAX >> 1))
80
81	#ifdef BSD_KERNEL_PRIVATE
82
83	/* Log information about runtime file system corruption detected */
84	void fslog_fs_corrupt(struct mount *mnt);
85
86	/* Log information about IO error detected */
87	void fslog_io_error(const buf_t bp);
88
89	#endif /* BSD_KERNEL_PRIVATE */
6d2010ae A	90
	91	#ifdef XNU_KERNEL_PRIVATE
	92
	93	/* Log information about external modification of a target process */
	94	void fslog_extmod_msgtracer(proc_t caller, proc_t target);
	95
	96	#endif /* XNU_KERNEL_PRIVATE */
	97
2d21ac55 A	98	#endif /* KERNEL */
	99
	100	/* Keys used by FSLog */
	101	#define FSLOG_KEY_FACILITY "Facility" /* Facility generating messages */
	102	#define FSLOG_KEY_LEVEL "Level" /* Priority level */
	103	#define FSLOG_KEY_MSG_ID "FSLogMsgID" /* Message ID */
	104	#define FSLOG_KEY_MSG_ORDER "FSLogMsgOrder" /* Message Order */
	105	#define FSLOG_KEY_READ_UID "ReadUID" /* Allow read access to this UID only */
	106
	107	/* Values for message order (FSLOG_KEY_MSG_ORDER) */
	108	#define FSLOG_VAL_ORDER_FIRST "First"
	109	#define FSLOG_VAL_ORDER_MIDDLE "Middle"
	110	#define FSLOG_VAL_ORDER_LAST "Last"
	111
	112	/* Values used by FSLog */
	113	#define FSLOG_VAL_FACILITY "com.apple.system.fs" /* Facility generating messages */
	114	#define FSLOG_VAL_LEVEL LOG_ERR /* Priority level */
	115	#define FSLOG_VAL_READ_UID 0 /* Allow read access to root only */
	116
	117	/* Keys for IO/FS logging using FSLog */
	118	#define FSLOG_KEY_ERR_TYPE "ErrType" /* Type of problem (IO, FS Corruption) */
	119	#define FSLOG_KEY_ERRNO "ErrNo" /* Error number (Integer) */
	120	#define FSLOG_KEY_IOTYPE "IOType" /* Type of IO (Read/Write) */
	121	#define FSLOG_KEY_PHYS_BLKNUM "PBlkNum" /* Physical block number */
	122	#define FSLOG_KEY_LOG_BLKNUM "LBlkNum" /* Logical block number */
	123	#define FSLOG_KEY_DEVNODE "DevNode" /* Device node (f_mntfromname) */
	124	#define FSLOG_KEY_PATH "Path" /* File system path */
	125	#define FSLOG_KEY_MNTPT "MountPt" /* Mount point */
	126
	127	/* Values for type of error (FSLOG_KEY_ERR_TYPE) */
	128	#define FSLOG_VAL_ERR_TYPE_IO "IO" /* IO error */
	129	#define FSLOG_VAL_ERR_TYPE_FS "FS" /* FS error */
	130
	131	/* Values for type of operation (FSLOG_KEY_IOTYPE) */
	132	#define FSLOG_VAL_IOTYPE_READ "Read"
	133	#define FSLOG_VAL_IOTYPE_WRITE "Write"
	134
	135	#endif /* !_FSLOG_H_ */