xref: /third_party/NuttX/include/syslog.h (revision beacf11b) 
1/****************************************************************************
2 * include/syslog.h
3 *
4 * Licensed to the Apache Software Foundation (ASF) under one or more
5 * contributor license agreements.  See the NOTICE file distributed with
6 * this work for additional information regarding copyright ownership.  The
7 * ASF licenses this file to you under the Apache License, Version 2.0 (the
8 * "License"); you may not use this file except in compliance with the
9 * License.  You may obtain a copy of the License at
10 *
11 *   http://www.apache.org/licenses/LICENSE-2.0
12 *
13 * Unless required by applicable law or agreed to in writing, software
14 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
15 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
16 * License for the specific language governing permissions and limitations
17 * under the License.
18 *
19 ****************************************************************************/
20
21#ifndef __INCLUDE_SYSLOG_H
22#define __INCLUDE_SYSLOG_H
23
24/****************************************************************************
25 * Included Files
26 ****************************************************************************/
27
28#include "vfs_config.h"
29
30#include "stdint.h"
31#include "stdarg.h"
32
33#ifdef __cplusplus
34#if __cplusplus
35extern "C"{
36#endif
37#endif /* __cplusplus */
38
39/****************************************************************************
40 * Pre-processor Definitions
41 ****************************************************************************/
42/* The option argument to openlog() is an OR of any of these:
43 *
44 *   LOG_CONS     - Write directly to system console if there is an error
45 *                  while sending to system logger.
46 *   LOG_NDELAY   - Open the connection immediately (normally, the connection
47 *                  is opened when the first message is logged).
48 *   LOG_NOWAIT   - Don't wait for child processes that may have been created
49 *                  while logging the message.
50 *   LOG_ODELAY   - The converse of LOG_NDELAY; opening of the connection is
51 *                  delayed until syslog() is called. (This is the default,
52 *                  and need not be specified.)
53 *   LOG_PERROR   - (Not in POSIX.1-2001 or POSIX.1-2008.) Print to stderr
54 *                  as well (Linux).
55 *   LOG_PID      - Include PID with each message.
56 */
57
58/* Note: openlog() is not currently supported */
59
60/* The facility argument is used to specify what type of program is logging
61 * the message. This lets the configuration file specify that messages from
62 * different facilities will be handled differently.
63 *
64 *   LOG_AUTH     - Security/authorization messages
65 *   LOG_AUTHPRIV - Security/authorization messages (private)
66 *   LOG_CRON     - Clock daemon (cron and at)
67 *   LOG_DAEMON   - System daemons without separate facility value
68 *   LOG_FTP      - FTP daemon
69 *   LOG_KERN     - Kernel messages (these can't be generated from user
70 *                  processes)
71 *   LOG_LOCAL0 through LOG_LOCAL7 - Reserved for local use
72 *   LOG_LPR      - Line printer subsystem
73 *   LOG_MAIL     - Mail subsystem
74 *   LOG_NEWS     - USENET news subsystem
75 *   LOG_SYSLOG   - Messages generated internally by syslogd(8)
76 *   LOG_USER     - Generic user-level messages (default)
77 *   LOG_UUCP     - UUCP subsystem
78 */
79
80#define LOG_AUTH      0
81#define LOG_AUTHPRIV  0
82#define LOG_CRON      0
83#define LOG_DAEMON    0
84#define LOG_FTP       0
85#define LOG_KERN      0
86#define LOG_LOCAL0    0
87#define LOG_LOCAL1    0
88#define LOG_LOCAL2    0
89#define LOG_LOCAL3    0
90#define LOG_LOCAL4    0
91#define LOG_LOCAL5    0
92#define LOG_LOCAL6    0
93#define LOG_LOCAL7    0
94#define LOG_LPR       0
95#define LOG_MAIL      0
96#define LOG_NEWS      0
97#define LOG_SYSLOG    0
98#define LOG_USER      0
99#define LOG_UUCP      0
100
101/* This determines the importance of the message. The levels are, in order
102 * of decreasing importance:
103 */
104
105#define LOG_EMERG     0  /* System is unusable */
106#define LOG_ALERT     1  /* Action must be taken immediately */
107#define LOG_CRIT      2  /* Critical conditions */
108#define LOG_ERR       3  /* Error conditions */
109#define LOG_WARNING   4  /* Warning conditions */
110#define LOG_NOTICE    5  /* Normal, but significant, condition */
111#define LOG_INFO      6  /* Informational message */
112#define LOG_DEBUG     7  /* Debug-level message */
113
114/* Used with setlogmask() */
115
116#define LOG_MASK(p)   (1 << (p))
117#define LOG_UPTO(p)   ((1 << (p)) - 1)
118#define LOG_ALL       0xff
119
120/****************************************************************************
121 * Public Function Prototypes
122 ****************************************************************************/
123
124#if defined(CONFIG_SYSLOG_CHAR) && !defined(CONFIG_SYSLOG_DEVPATH)
125#  define CONFIG_SYSLOG_DEVPATH "/dev/ttyS1"
126#endif
127
128/****************************************************************************
129 * Name: openlog
130 *
131 * Description:
132 *   The openlog() function sets process attributes that affect subsequent
133 *   calls to syslog(). The ident argument is a string that is prepended to
134 *   every message. The logopt argument indicates logging options. Values
135 *   for logopt are constructed by a bitwise-inclusive OR of zero or more of
136 *   the following:
137 *
138 *     LOG_PID - Log the process ID with each message. This is useful for
139 *       identifying specific processes.
140 *
141 *     LOG_CONS - Write messages to the system console if they cannot be
142 *       sent to the logging facility. The syslog() function ensures that
143 *       the process does not acquire the console as a controlling terminal
144 *       in the process of writing the message.
145 *
146 *     LOG_NDELAY - Open the connection to the logging facility immediately.
147 *       Normally the open is delayed until the first message is logged.
148 *       This is useful for programs that need to manage the order in which
149 *       file descriptors are allocated.
150 *
151 *     LOG_ODELAY - Delay open until syslog() is called.
152 *
153 *     LOG_NOWAIT - Do not wait for child processes that may have been
154 *       created during the course of logging the message. This option
155 *       should be used by processes that enable notification of child
156 *       termination using SIGCHLD, since syslog() may otherwise block
157 *       waiting for a child whose exit status has already been collected.
158 *
159 *   The facility argument encodes a default facility to be assigned to all
160 *   messages that do not have an explicit facility already encoded. The
161 *   initial default facility is LOG_USER.
162 *
163 *   It is not necessary to call openlog() prior to calling syslog().
164 *
165 ****************************************************************************/
166
167#if 0 /* Not supported */
168void openlog(FAR const char *ident, int option, int facility);
169#endif
170
171/****************************************************************************
172 * Name: closelog
173 *
174 * Description:
175 *   The openlog() and syslog() functions may allocate a file descriptor.
176 *   The closelog() function will close any open file descriptors allocated
177 *   by previous calls to openlog() or syslog().
178 *
179 ****************************************************************************/
180
181#if 0 /* Not supported */
182void closelog(void);
183#endif
184
185/****************************************************************************
186 * Name: syslog and vsyslog
187 *
188 * Description:
189 *   syslog() generates a log message. The priority argument is formed by
190 *   ORing the facility and the level values (see include/syslog.h). The
191 *   remaining arguments are a format, as in printf and any arguments to the
192 *   format.
193 *
194 *   The NuttX implementation does not support any special formatting
195 *   characters beyond those supported by printf.
196 *
197 *   The function vsyslog() performs the same task as syslog() with the
198 *   difference that it takes a set of arguments which have been obtained
199 *   using the stdarg variable argument list macros.
200 *
201 ****************************************************************************/
202
203int syslog(int priority, const char *format, ...);
204int vsyslog(int priority, const char *src, va_list ap);
205
206/****************************************************************************
207 * Name: lowsyslog and lowvsyslog
208 *
209 * Description:
210 *   syslog() generates a log message. The priority argument is formed by
211 *   ORing the facility and the level values (see include/syslog.h). The
212 *   remaining arguments are a format, as in printf and any arguments to the
213 *   format.
214 *
215 *   This is a non-standard, low-level system logging interface.  The
216 *   difference between syslog() and lowsyslog() is that the syslog()
217 *   interface writes to the syslog device (usually fd=1, stdout) whereas
218 *   lowsyslog() uses a lower level interface that works even from interrupt
219 *   handlers.
220 *
221 *   If the platform cannot support lowsyslog, then we will substitute the
222 *   standard syslogging functions.  These will, however, probably cause
223 *   problems if called from interrupt handlers, depending upon the nature of
224 *   the underlying syslog device.
225 *
226 *   The function lowvsyslog() performs the same task as lowsyslog() with
227 *   the difference that it takes a set of arguments which have been
228 *   obtained using the stdarg variable argument list macros.
229 *
230 ****************************************************************************/
231
232#ifdef CONFIG_ARCH_LOWPUTC
233
234int lowsyslog(int priority, FAR const char *format, ...);
235int lowvsyslog(int priority, FAR const char *format, va_list ap);
236
237#else
238
239#  ifdef CONFIG_CPP_HAVE_VARARGS
240#    define lowsyslog(p,f,...) syslog(p,f,##__VA_ARGS__)
241#  else
242#    define lowsyslog (void)
243#  endif
244#  define lowvsyslog(p,f,a) vsyslog(p,f,a)
245
246#endif
247
248/****************************************************************************
249 * Name: setlogmask
250 *
251 * Description:
252 *   The setlogmask() function sets the logmask and returns the previous
253 *   mask. If the mask argument is 0, the current logmask is not modified.
254 *
255 *   The SYSLOG priorities are: LOG_EMERG, LOG_ALERT, LOG_CRIT, LOG_ERR,
256 *   LOG_WARNING, LOG_NOTICE, LOG_INFO, and LOG_DEBUG.  The bit corresponding
257 *   to a priority p is LOG_MASK(p); LOG_UPTO(p) provides the mask of all
258 *   priorities in the above list up to and including p.
259 *
260 *   Per OpenGroup.org "If the maskpri argument is 0, the current log mask
261 *   is not modified."  In this implementation, the value zero is permitted
262 *   in order to disable all syslog levels.
263 *
264 *   NOTE:  setlogmask is not a thread-safe, re-entrant function.  Concurrent
265 *   use of setlogmask() will have undefined behavior.
266 *
267 *   REVISIT: Per POSIX the syslog mask should be a per-process value but in
268 *   NuttX, the scope of the mask is dependent on the nature of the build:
269 *
270 *   Flat Build:  There is one, global SYSLOG mask that controls all output.
271 *   Protected Build:  There are two SYSLOG masks.  One within the kernel
272 *     that controls only kernel output.  And one in user-space that controls
273 *     only user SYSLOG output.
274 *   Kernel Build:  The kernel build is compliant with the POSIX requirement:
275 *     There will be one mask for for each user process, controlling the
276 *     SYSLOG output only form that process.  There will be a separate mask
277 *     accessible only in the kernel code to control kernel SYSLOG output.
278 *
279 ****************************************************************************/
280
281int setlogmask(int mask);
282
283#ifdef __cplusplus
284#if __cplusplus
285}
286#endif
287#endif /* __cplusplus */
288
289#endif /* __INCLUDE_SYSLOG_H */
290