llog(S) 6 January 1993 llog(S) Name llog - library logging package Syntax cc . . . -lmmdf #include ll_log.h ll_close (loginfo) struct ll_struct *loginfo; ll_err (loginfo, verbosity, printf args . . . ) char verbosity; struct ll_struct *loginfo; ll_hdinit (loginfo, pref) struct ll_struct *loginfo; char *pref; ll_init (lloginfo) struct ll_struct *loginfo; ll_log (loginfo, verbosity, printf args . . . ) struct ll_struct *loginfo; char verbosity; ll_open (loginfo) struct ll_struct *loginfo; struct ll_struct { char *ll_file; /* Path name to logging file */ char *ll_hdr; /* Text to put in opening line */ char ll_level; /* Max verbosity level */ LLOGBST /* Basic statistics */ LLOGBTR /* Trace of more basic activities */ LLOGFAT /* Fatal error */ LLOGFST /* Full statistics */ LLOGFTR /* Full program trace */ LLOGGEN /* General information */ LLOGMAX /* Maximum possible value */ LLOGPTR /* Trace of program phases */ LLOGTMP /* Temporary (minor?) error */ char ll_msize; /* Max log size, in 100's of blocks */ char ll_stat; /* Assorted switches */ LLOGCLS /* Close after each write */ LLOGCYC /* Cycle to beginning when log full */ LLOGSOME /* CLS and WAT */ LLOGTIMED /* Reopen periodically */ LLOGWAT /* Wait, if log locked and LLOGCLS */ char ll_fd; /* char holds file descriptor */ int ll_timmax; /* Time fd can be in use before reopen */ time_t ll_timer; /* Time of last open of log file */ FILE *ll_fp; /* Standard I/O stream pointer */ }; Description This package is intended to perform standardized information logging for programs. The time of an entry is recorded in addition to its text. Format of Entries Depending on the mode of logging (whether the log is left open between lllog calls or is re-opened to make each entry, as indicated by the LLOGCLS flag) the date, hour and loginfo.llhdr string are recorded on a header line when the log is opened (if LLOGCLS and LLOGTIMED are off) or on the logging line (if LLOGCLS is on). In addition, the current minute and second are recorded, followed by the actual log text. Each log entry is started on a new line. The text of the entry is entered with a printf, called with parameters passed to the lllog function. Access to Log Files Multiple logs can be accessed simultaneously by the same process, because all of the state information for a single log is kept in the user- maintained structure, llogstruct, which is included as a parameter when calling llog functions. While opened by one process, a single log cannot be shared with another process, since logging files are opened with exclusive access (the specific locking mechanism depends on the version of the UNIX operating system that you are running). The LLOGCLS flag is intended to help circumvent this protection. Also, the LLOGWAT flag may be used to cause llopen to repeatedly retry opening the log, if the failure to open it was due to its being used by another process. llopen tries up to five times, waiting five seconds between tries; after that, it returns. The failure is treated as temporary if LLOGCLS is used (implying infrequent logging expected); otherwise the failure is treated as permanent. In either case, the log is marked as "broken" and no further attempts are made to use it until either llclose or llopen is called. Exclusive opening of the log file is not currently used. As a result, the LLOGWAT flag does not have any effect. Exclusive opening could be re-added but seeking to the end of the log and flushing after writes works most of the time. Limiting Size of Log Files The package can impose a size limit to log files. If lloginfo.llmsize is zero, size-limiting is not imposed, otherwise llog does not allow a log to grow larger (25 * lloginfo.llmsize) blocks. If the log is being held open between entries and cycling is allowed (that is, LLOGCYC is set and LLOGCLS is not) then when llinit is called (by llopen or by the user) during successive uses, entries are made starting from the beginning of the file. If the LLOGCLS bit is set or if the LLOGCYC bit is not set, then the log is marked as unusable. The llopen routine attempts to open the logging file. It returns the return value from its open call. It does not attempt to create the file if the file does not exist. The result of the open call is placed in the llfd member of the logstruct structure. The using program should ensure that llfd initially has the value zero. lllog simply returns, if llfd is -1; therefore the caller can ignore failures to open the log. Also, the existence of the logging file can be used as a convenient external switch for turning logging on and off. Entries are appended to the end of any old entries in the file, except when cycling occurs. If the LLOGCLS bit is set in the loginfo.llstat field, then the file is opened only long enough to make an entry. This action makes it more reasonable for multiple processes to share a log into which relatively few entries are made, such as when only error mes- sages are recorded. The llinit routine is to be used when the logging file is already opened (for example, when the file descriptor has been inherited from a parent process) instead of calling llopen. The lllog routine actually makes the log entries. If the log is not already opened and loginfo.llfd is 0, lllog calls llopen. (Note that this means that the calling program usually does not need to call llopen, unless there is a concern about locking the file.) The lllevel value indicates how much logging the caller desires. When called, lllog does not make the log entry if the value of the verbosity argument is greater than than the value of lllevel. This allows, for example, dis- tinction between mandatory and debugging information, with many levels of (256) information possible. As a guide, the list shown in the synopsis can be used. The lllog routine uses printf to make the entries. There is a limit of ten (10) arguments that may be passed to it. The third argument to lllog becomes the first argument to printf. The flush routine is then called so that the log is always up-to-date; this is deemed more impor- tant than fully minimizing write calls, and in any event, is required to allow lllog to use the printf mechanism in a way that does not interfere with its use elsewhere in the process. The llclose routine closes the logging file and marks llfd as clear (that is, it resets it to be zero). Note that this normally need not be called, since the file is automatically closed when the process exits. However, it is necessary to close the log, during execution, if a child or some other process is expected to open the same log independently. Calling llclose also always clears the file descriptor, making it possi- ble for a new try at opening the log, if it failed previously. Diagnostics The llopen routine returns the value of its open call, if that fails; otherwise it returns the value of its call to llinit. The lllog routine returns the value of its flush call, or zero if llfd is -1; if flush returns less than zero, then lllog closes the log and returns NOTOK. The llclose routine returns the value of its close call. See also mlsend(S), mmdf(S), phs(S), tai(S) Standards conformance The ll package is not part of any currently supported standard; it was developed at the University of Delaware and is used by permission.