VxWorks Reference Manual : Libraries
logLib - message logging library
logInit( ) - initialize message logging library
logMsg( ) - log a formatted error message
logFdSet( ) - set the primary logging file descriptor
logFdAdd( ) - add a logging file descriptor
logFdDelete( ) - delete a logging file descriptor
logTask( ) - message-logging support task
This library handles message logging. It is usually used to display error messages on the system console, but such messages can also be sent to a disk file or printer.
The routines logMsg( ) and logTask( ) are the basic components of the logging system. The logMsg( ) routine has the same calling sequence as printf( ), but instead of formatting and outputting the message directly, it sends the format string and arguments to a message queue. The task logTask( ) waits for messages on this message queue. It formats each message according to the format string and arguments in the message, prepends the ID of the sender, and writes it on one or more file descriptors that have been specified as logging output streams (by logInit( ) or subsequently set by logFdSet( ) or logFdAdd( )).
Because logMsg( ) does not directly cause output to I/O devices, but instead simply writes to a message queue, it can be called from an interrupt service routine as well as from tasks. Normal I/O, such as printf( ) output to a serial port, cannot be done from an interrupt service routine.
Print formatting is performed within the context of logTask( ), rather than the context of the task calling logMsg( ). Since formatting can require considerable stack space, this can reduce stack sizes for tasks that only need to do I/O for error output.
However, this also means that the arguments to logMsg( ) are not interpreted at the time of the call to logMsg( ), but rather are interpreted at some later time by logTask( ). This means that the arguments to logMsg( ) should not be pointers to volatile entities. For example, pointers to dynamic or changing strings and buffers should not be passed as arguments to be formatted. Thus the following would not give the desired results:
doLog (which) { char string [100]; strcpy (string, which ? "hello" : "goodbye"); ... logMsg (string); }By the time logTask( ) formats the message, the stack frame of the caller may no longer exist and the pointer string may no longer be valid. On the other hand, the following is correct since the string pointer passed to the logTask( ) always points to a static string:doLog (which) { char *string; string = which ? "hello" : "goodbye"; ... logMsg (string); }
To initialize the message logging facilities, the routine logInit( ) must be called before calling any other routine in this module. This is done by the root task, usrRoot( ), in usrConfig.c.
logLib.h
logLib, msgQLib, VxWorks Programmer's Guide: I/O System
logInit( ) - initialize message logging library
STATUS logInit ( int fd, /* file descriptor to use as logging device */ int maxMsgs /* max. number of messages allowed in log queue */ )
This routine specifies the file descriptor to be used as the logging device and the number of messages that can be in the logging queue. If more than maxMsgs are in the queue, they will be discarded. A message is printed to indicate lost messages.
This routine spawns logTask( ), the task-level portion of error logging.
This routine must be called before any other routine in logLib. This is done by the root task, usrRoot( ), in usrConfig.c.
OK, or ERROR if a message queue could not be created or logTask( ) could not be spawned.
logMsg( ) - log a formatted error message
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 )
This routine logs a specified message via the logging task. This routine's syntax is similar to printf( ) -- a format string is followed by arguments to format. However, the logMsg( ) routine requires a fixed number of arguments (6).
The task ID of the caller is prepended to the specified message.
Because logMsg( ) does not actually perform the output directly to the logging streams, but instead queues the message to the logging task, logMsg( ) can be called from interrupt service routines.
However, since the arguments are interpreted by the logTask( ) at the time of actual logging, instead of at the moment when logMsg( ) is called, arguments to logMsg( ) should not be pointers to volatile entities (e.g., dynamic strings on the caller stack).
For more detailed information about the use of logMsg( ), see the manual entry for logLib.
If the following code were executed by task 20:
{ name = "GRONK"; num = 123; logMsg ("ERROR - name = %s, num = %d.\n", name, num, 0, 0, 0, 0); }the following error message would appear on the system log:0x180400 (t20): ERROR - name = GRONK, num = 123.
The number of bytes written to the log queue, or EOF if the routine is unable to write a message.
logFdSet( ) - set the primary logging file descriptor
void logFdSet ( int fd /* file descriptor to use as logging device */ )
This routine changes the file descriptor where messages from logMsg( ) are written, allowing the log device to be changed from the default specified by logInit( ). It first removes the old file descriptor (if one had been previously set) from the log file descriptor list, then adds the new fd.
The old logging file descriptor is not closed or affected by this call; it is simply no longer used by the logging facilities.
N/A
logLib, logFdAdd( ), logFdDelete( )
logFdAdd( ) - add a logging file descriptor
STATUS logFdAdd ( int fd /* file descriptor for additional logging device */ )
This routine adds to the log file descriptor list another file descriptor fd to which messages will be logged. The file descriptor must be a valid open file descriptor.
OK, or ERROR if the allowable number of additional logging file descriptors (5) is exceeded.
logLib, logFdDelete( )
logFdDelete( ) - delete a logging file descriptor
STATUS logFdDelete ( int fd /* file descriptor to stop using as logging device */ )
This routine removes from the log file descriptor list a logging file descriptor added by logFdAdd( ). The file descriptor is not closed; but is no longer used by the logging facilities.
OK, or ERROR if the file descriptor was not added with logFdAdd( ).
logTask( ) - message-logging support task
void logTask (void)
This routine prints the messages logged with logMsg( ). It waits on a message queue and prints the messages as they arrive on the file descriptor specified by logInit( ) (or a subsequent call to logFdSet( ) or logFdAdd( )).
This task is spawned by logInit( ).
N/A