MiscLogFile.rtf

This is MiscLogFile.rtf in view mode; [Download] [Up]

MiscLogFile

Inherits From: Object

Declared In: misckit/MiscLogFile.h

Protocols: NXTransport

Class Description

A MiscLogFile is used to log information to a UNIX text file. You simply pass it lines of text�as MiscString objects�to append to the log file. If you wish, and this is necessary if multiple processes might write to the log file, you can have the MiscLogFile make use of a MiscLockFile to provide a proper lock on the log file. You can log messages to stdout, stderr, or an arbitrary file.

To use a MiscLogFile in your application, simply create the object using �alloc and �init and then set up the file to be used for logging. This may be done by using any one of the following methods: �setFileName:, �usestdout, or �usestderr. To add a line to the log file, send the �addLineToLogFile: message, which takes a MiscString (or other object which responds to �stringValue) as an argument and returns a YES if successful. The �addLineToLogFile: method automatically handles opening and closing the file for you, each time that you call it. As such, it can be somewhat slow and resource intensive.

Alternatively, if you plan to write many lines to the log file at a time, then open the log file with an �openFile message, write your lines with the �appendToLogFile:andFlush: method, and then, when you are finished, send the �closeFile message. Note that all three messages return a NO if they are unsuccessful in any way. If, when appending lines, you do not flush them right away, repeated lines will be compressed into a single line saying �The last line was repeated x times.� The disadvantage to this is that during the whole time, you are holding the log file locked. If multiple processes need to log problems, then this is probably a bad idea, since they will either have to give up on logging or spin wait. (A way to get around this is to spin off a separate thread to do the logging for the main thread.)

Instance Variables

BOOL fileOpen;
BOOL special;
FILE *file;
id lastLine;
id lockFile;
id fileName;
int repeats;

file File we are writing to; only valid if fileOpen == YES.

fileName The name of the file being logged to.

fileOpen YES if the log file is currently opened for appending.

lastLine The line most recently output by the MiscLogFile object

lockFile A supporting MiscLockFile (if the log file is protected by a lock)

repeats How many times the last line has been sent to the file.

special YES if the MiscLogFile is logging to stderr or stdout.

Method Types

Initializing a MiscLogFile � init
� copy
� free

Changing parameters � setFileName:
� setLockFile:
� usestderr
� usestdout

Getting information about � fileName
� file
� fileIsOpen
� special
� lockFile

Saving to a file � read:
� write:

Updating the log file � addLineToLogFile:
� appendToLogFile:andFlush:
� openFile
� closeFile

Instance Methods

addLineToLogFile:
- (BOOL)addLineToLogFile:aString

Opens the log file, obtaining a lock if necessary, and appends aString to the file. The argument aString should be an object which responds to the �stringValue method. After appending the message, this method then closes the file and returns a YES if successful. A failure is noted by returning a NO.