Creates and initializes a trace object with name traceName. The traceName and instName fields are also used to create the name of the trace output file. If instName is NULL, the output file is ``traceName.dt''; otherwise, it is ``traceName_instName.dt'' (substituting the appropriate values for the variable names).
The logsize parameter specifies the size of the trace buffer in bytes, and fileSize states the maximum length of the trace file in terms of trace buffers (e.g., logsize = 10000 and fileSize = 3 means a trace buffer of approximately 10KB and a maximum trace file size of 30KB).
dt *dtCreateTraceObj(char *traceName, char *instName, int logsize, int fileSize)
Note that both the trace buffer and trace file are circular. When the trace buffer is full, it will be flushed to disk; when the trace file is full, the next trace buffer written will overwrite the first one in the file.
A list of all trace objects created by any protocol is maintained by the datatrace tool. The newly created trace object is put at the end of this list.
The dtTracen macros take n arguments in addition to a pointer to a dt object. The effect of all of them is to save the trace variables given as arguments to the trace buffer, and advance the buffer pointer. When the trace buffer becomes full, it is flushed to disk and the buffer pointer is reset to the start of the trace buffer.
void dtTracen(dt *dtobj, args,...)
The dtTraceBuf macro can be used instead of dtTracen. It copies a single buffer, pointed to by buf and of length len, to the trace buffer, and advances the buffer pointer. When the trace buffer becomes full, it is flushed to disk and the buffer pointer is reset to the start of the trace buffer.
dtTraceBuf(dt *dtobj, char *buf, int len)
Flushes the data in the buffers to the data file. Also flushes the postamble data if flush_post is non-zero.
void dtFlushTraceObj(dt *dtobj, int flush_post)
Associate closefunc with trace object dtobj. Function closefunc is invoked with argument closearg when dtClose() is called.
void dtRegisterCloseFunc(dt *dtobj, dtCloseFunc closefunc, void *closearg)
This function first calls the function registered with dtobj by dtRegisterCloseFunc(), if there is one. It then removes the trace object from the trace object list, flushes the trace buffer to disk, and frees all storage associated with the object.
void dtClose(dt *dtobj)
Invokes dtClose() on all trace objects. This function should be called at the end of the program.
void dtCloseAll()
Adds a buffer to the trace object dtobj, which is flushed to the end of the file when dtClose() is called. Assumes that the buffer has been preallocated. The buffer is placed at the end of the postamble list.
XkReturn dtAppendPostAmble(dt *dtobj, char *buffer, int size)
Adds a buffer to the trace object dtobj, which is flushed to the end of the file when dtClose() is called. Assumes that the buffer has been preallocated. The buffer is placed at the beginning of the postamble list.
XkReturn dtInsertPostAmble(dt *dtobj, char *buffer, int size)
Returns the offset from the beginning of the file to the beginning of the postamble information.
long dtPostAmbleLocation(dthdr *FileHdr)
Returns the trace object that was created with name traceName.
dt *dtGetTraceObj(char *traceName)
Returns the first trace objects in the list of trace objects.
dt *dtGetTopTraceObj()
This routine would typically be called in a protocol's initialization routine, if the protocol supports tracing. See Section 9.3 for more information.
void dtLoadXObjRomOpts(Protl prot)