📄 loglib.html
字号:
<html><head><!-- /vobs/wpwr/docs/vxworks/ref/logLib.html - generated by refgen from logLib.c --> <title> logLib </title></head><body bgcolor="#FFFFFF"> <hr><a name="top"></a><p align=right><a href="libIndex.html"><i>VxWorks Reference Manual : Libraries</i></a></p></blockquote><h1>logLib</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote> <p><strong>logLib</strong> - message logging library </p></blockquote><h4>ROUTINES</h4><blockquote><p><p><b><i><a href="./logLib.html#logInit">logInit</a></i>( )</b> - initialize message logging library<br><b><i><a href="./logLib.html#logMsg">logMsg</a></i>( )</b> - log a formatted error message<br><b><i><a href="./logLib.html#logFdSet">logFdSet</a></i>( )</b> - set the primary logging file descriptor<br><b><i><a href="./logLib.html#logFdAdd">logFdAdd</a></i>( )</b> - add a logging file descriptor<br><b><i><a href="./logLib.html#logFdDelete">logFdDelete</a></i>( )</b> - delete a logging file descriptor<br><b><i><a href="./logLib.html#logTask">logTask</a></i>( )</b> - message-logging support task<br><p></blockquote><h4>DESCRIPTION</h4><blockquote><p>This library handles message logging. It is usually used to display errormessages on the system console, but such messages can also be sent to adisk file or printer.<p>The routines <b><i><a href="./logLib.html#logMsg">logMsg</a></i>( )</b> and <b><i><a href="./logLib.html#logTask">logTask</a></i>( )</b> are the basic components of thelogging system. The <b><i><a href="./logLib.html#logMsg">logMsg</a></i>( )</b> routine has the same calling sequence as<b><i><a href="./fioLib.html#printf">printf</a></i>( )</b>, but instead of formatting and outputting the message directly,it sends the format string and arguments to a message queue. The task<b><i><a href="./logLib.html#logTask">logTask</a></i>( )</b> waits for messages on this message queue. It formats eachmessage according to the format string and arguments in the message,prepends the ID of the sender, and writes it on one or more filedescriptors that have been specified as logging output streams (by<b><i><a href="./logLib.html#logInit">logInit</a></i>( )</b> or subsequently set by <b><i><a href="./logLib.html#logFdSet">logFdSet</a></i>( )</b> or <b><i><a href="./logLib.html#logFdAdd">logFdAdd</a></i>( )</b>).<p></blockquote><h4>USE IN INTERRUPT SERVICE ROUTINES</h4><blockquote><p>Because <b><i><a href="./logLib.html#logMsg">logMsg</a></i>( )</b> does not directly cause output to I/O devices, butinstead simply writes to a message queue, it can be called from aninterrupt service routine as well as from tasks. Normal I/O, such as<b><i><a href="./fioLib.html#printf">printf</a></i>( )</b> output to a serial port, cannot be done from an interrupt serviceroutine.<p></blockquote><h4>DEFERRED LOGGING</h4><blockquote><p>Print formatting is performed within the context of <b><i><a href="./logLib.html#logTask">logTask</a></i>( )</b>, rather thanthe context of the task calling <b><i><a href="./logLib.html#logMsg">logMsg</a></i>( )</b>. Since formatting can requireconsiderable stack space, this can reduce stack sizes for tasks that onlyneed to do I/O for error output.<p>However, this also means that the arguments to <b><i><a href="./logLib.html#logMsg">logMsg</a></i>( )</b> are not interpretedat the time of the call to <b><i><a href="./logLib.html#logMsg">logMsg</a></i>( )</b>, but rather are interpreted at somelater time by <b><i><a href="./logLib.html#logTask">logTask</a></i>( )</b>. This means that the arguments to <b><i><a href="./logLib.html#logMsg">logMsg</a></i>( )</b> shouldnot be pointers to volatile entities. For example, pointers to dynamic orchanging strings and buffers should not be passed as arguments to be formatted.Thus the following would not give the desired results:<p><pre> doLog (which) { char string [100]; strcpy (string, which ? "hello" : "goodbye"); ... logMsg (string); }</pre>By the time <b><i><a href="./logLib.html#logTask">logTask</a></i>( )</b> formats the message, the stack frame of the caller mayno longer exist and the pointer <i>string</i> may no longer be valid.On the other hand, the following is correct since the string pointer passedto the <b><i><a href="./logLib.html#logTask">logTask</a></i>( )</b> always points to a static string:<pre> doLog (which) { char *string; string = which ? "hello" : "goodbye"; ... logMsg (string); }</pre></blockquote><h4>INITIALIZATION</h4><blockquote><p>To initialize the message logging facilities, the routine <b><i><a href="./logLib.html#logInit">logInit</a></i>( )</b> mustbe called before calling any other routine in this module. This is doneby the root task, <b><i><a href="./usrConfig.html#usrRoot">usrRoot</a></i>( )</b>, in <b>usrConfig.c</b>.<p></blockquote><h4>INCLUDE FILES</h4><blockquote><p><b>logLib.h</b><p></blockquote><h4>SEE ALSO</h4><blockquote><p><b><a href="./logLib.html#top">logLib</a></b>, <b><a href="./msgQLib.html#top">msgQLib</a></b>, <i>VxWorks Programmer's Guide: I/O System</i><hr><a name="logInit"></a><p align=right><a href="rtnIndex.html"><i>Libraries : Routines</i></a></p></blockquote><h1><i>logInit</i>( )</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote> <p><strong><i>logInit</i>( )</strong> - initialize message logging library</p></blockquote><h4>SYNOPSIS</h4><blockquote><p><pre>STATUS logInit ( int fd, /* file descriptor to use as logging device */ int maxMsgs /* max. number of messages allowed in log queue */ )</pre></blockquote><h4>DESCRIPTION</h4><blockquote><p>This routine specifies the file descriptor to be used as the loggingdevice and the number of messages that can be in the logging queue. Ifmore than <i>maxMsgs</i> are in the queue, they will be discarded. A messageis printed to indicate lost messages.<p>This routine spawns <b><i><a href="./logLib.html#logTask">logTask</a></i>( )</b>, the task-level portion of error logging.<p>This routine must be called before any other routine in logLib.This is done by the root task, <b><i><a href="./usrConfig.html#usrRoot">usrRoot</a></i>( )</b>, in <b>usrConfig.c</b>.<p></blockquote><h4>RETURNS</h4><blockquote><p>OK, or ERROR if a message queue could not be createdor <b><i><a href="./logLib.html#logTask">logTask</a></i>( )</b> could not be spawned.</blockquote><h4>SEE ALSO</h4><blockquote><p><b><a href="./logLib.html#top">logLib</a></b><hr><a name="logMsg"></a><p align=right><a href="rtnIndex.html"><i>Libraries : Routines</i></a></p></blockquote><h1><i>logMsg</i>( )</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote> <p><strong><i>logMsg</i>( )</strong> - log a formatted error message</p></blockquote><h4>SYNOPSIS</h4><blockquote><p><pre>int logMsg ( char * fmt, /* format string for print */ int arg1, /* first of six required args for fmt */ int arg2, int arg3, int arg4, int arg5, int arg6 )</pre></blockquote><h4>DESCRIPTION</h4><blockquote><p>This routine logs a specified message via the logging task. Thisroutine's syntax is similar to <b><i><a href="./fioLib.html#printf">printf</a></i>( )</b> -- a format string is followedby arguments to format. However, the <b><i><a href="./logLib.html#logMsg">logMsg</a></i>( )</b> routinerequires a fixed number of arguments (6).<p>The task ID of the caller is prepended to the specified message.<p></blockquote><h4>SPECIAL CONSIDERATIONS</h4><blockquote><p>Because <b><i><a href="./logLib.html#logMsg">logMsg</a></i>( )</b> does not actually perform the output directly to thelogging streams, but instead queues the message to the logging task,<b><i><a href="./logLib.html#logMsg">logMsg</a></i>( )</b> can be called from interrupt service routines.<p>However, since the arguments are interpreted by the <b><i><a href="./logLib.html#logTask">logTask</a></i>( )</b> at thetime of actual logging, instead of at the moment when <b><i><a href="./logLib.html#logMsg">logMsg</a></i>( )</b> is called,arguments to <b><i><a href="./logLib.html#logMsg">logMsg</a></i>( )</b> should not be pointers to volatile entities(e.g., dynamic strings on the caller stack).<p>For more detailed information about the use of <b><i><a href="./logLib.html#logMsg">logMsg</a></i>( )</b>, see the manualentry for logLib.<p></blockquote><h4>EXAMPLE</h4><blockquote><p>If the following code were executed by task 20:<pre> { name = "GRONK"; num = 123; logMsg ("ERROR - name = %s, num = %d.\n", name, num, 0, 0, 0, 0); }</pre>the following error message would appear on the system log:<pre> 0x180400 (t20): ERROR - name = GRONK, num = 123.</pre></blockquote><h4>RETURNS</h4><blockquote><p>The number of bytes written to the log queue,or EOF if the routine is unable to write a message.<p></blockquote><h4>SEE ALSO</h4><blockquote><p><b><a href="./logLib.html#top">logLib</a></b>, <b><i><a href="./fioLib.html#printf">printf</a></i>( )</b>, <b><i><a href="./logLib.html#logTask">logTask</a></i>( )</b><hr><a name="logFdSet"></a><p align=right><a href="rtnIndex.html"><i>Libraries : Routines</i></a></p></blockquote><h1><i>logFdSet</i>( )</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote> <p><strong><i>logFdSet</i>( )</strong> - set the primary logging file descriptor</p></blockquote><h4>SYNOPSIS</h4><blockquote><p><pre>void logFdSet ( int fd /* file descriptor to use as logging device */ )</pre></blockquote><h4>DESCRIPTION</h4><blockquote><p>This routine changes the file descriptor where messages from <b><i><a href="./logLib.html#logMsg">logMsg</a></i>( )</b> are written, allowing the log device to be changed from the defaultspecified by <b><i><a href="./logLib.html#logInit">logInit</a></i>( )</b>. It first removes the old file descriptor (if one had been previously set) from the log file descriptor list, then adds the new <i>fd</i>.<p>The old logging file descriptor is not closed or affected by this call; it is simply no longer used by the logging facilities.<p></blockquote><h4>RETURNS</h4><blockquote><p>N/A<p></blockquote><h4>SEE ALSO</h4><blockquote><p><b><a href="./logLib.html#top">logLib</a></b>, <b><i><a href="./logLib.html#logFdAdd">logFdAdd</a></i>( )</b>, <b><i><a href="./logLib.html#logFdDelete">logFdDelete</a></i>( )</b><hr><a name="logFdAdd"></a><p align=right><a href="rtnIndex.html"><i>Libraries : Routines</i></a></p></blockquote><h1><i>logFdAdd</i>( )</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote> <p><strong><i>logFdAdd</i>( )</strong> - add a logging file descriptor</p></blockquote><h4>SYNOPSIS</h4><blockquote><p><pre>STATUS logFdAdd ( int fd /* file descriptor for additional logging device */ )</pre></blockquote><h4>DESCRIPTION</h4><blockquote><p>This routine adds to the log file descriptor list another file descriptor<i>fd</i> to which messages will be logged. The file descriptor must be a valid open file descriptor.<p></blockquote><h4>RETURNS</h4><blockquote><p><p>OK, or ERROR if the allowable number of additional logging file descriptors(5) is exceeded.<p></blockquote><h4>SEE ALSO</h4><blockquote><p><b><a href="./logLib.html#top">logLib</a></b>, <b><i><a href="./logLib.html#logFdDelete">logFdDelete</a></i>( )</b><hr><a name="logFdDelete"></a><p align=right><a href="rtnIndex.html"><i>Libraries : Routines</i></a></p></blockquote><h1><i>logFdDelete</i>( )</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote> <p><strong><i>logFdDelete</i>( )</strong> - delete a logging file descriptor</p></blockquote><h4>SYNOPSIS</h4><blockquote><p><pre>STATUS logFdDelete ( int fd /* file descriptor to stop using as logging device */ )</pre></blockquote><h4>DESCRIPTION</h4><blockquote><p>This routine removes from the log file descriptor list a logging file descriptor added by <b><i><a href="./logLib.html#logFdAdd">logFdAdd</a></i>( )</b>. The file descriptor is not closed; but isno longer used by the logging facilities.<p></blockquote><h4>RETURNS</h4><blockquote><p><p>OK, or ERROR if the file descriptor was not added with <b><i><a href="./logLib.html#logFdAdd">logFdAdd</a></i>( )</b>.<p></blockquote><h4>SEE ALSO</h4><blockquote><p><b><a href="./logLib.html#top">logLib</a></b>, <b><i><a href="./logLib.html#logFdAdd">logFdAdd</a></i>( )</b><hr><a name="logTask"></a><p align=right><a href="rtnIndex.html"><i>Libraries : Routines</i></a></p></blockquote><h1><i>logTask</i>( )</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote> <p><strong><i>logTask</i>( )</strong> - message-logging support task</p></blockquote><h4>SYNOPSIS</h4><blockquote><p><pre>void logTask (void)</pre></blockquote><h4>DESCRIPTION</h4><blockquote><p>This routine prints the messages logged with <b><i><a href="./logLib.html#logMsg">logMsg</a></i>( )</b>. It waits on amessage queue and prints the messages as they arrive on the file descriptorspecified by <b><i><a href="./logLib.html#logInit">logInit</a></i>( )</b> (or a subsequent call to <b><i><a href="./logLib.html#logFdSet">logFdSet</a></i>( )</b> or <b><i><a href="./logLib.html#logFdAdd">logFdAdd</a></i>( )</b>).<p>This task is spawned by <b><i><a href="./logLib.html#logInit">logInit</a></i>( )</b>.<p></blockquote><h4>RETURNS</h4><blockquote><p>N/A<p></blockquote><h4>SEE ALSO</h4><blockquote><p><b><a href="./logLib.html#top">logLib</a></b>, <b><i><a href="./logLib.html#logMsg">logMsg</a></i>( )</b></body></html>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -