4.3BSD/usr/contrib/notes/doc/4.3

.se "User Subroutines"

.ss "Nfcomment"

	The nfcomment subroutine is callable from a user's C program. It
allows any user program to enter text into a notesfile:

	nfcomment (nfname, text, title, dirflag, anonflag)

.KS
.br
The parameters are:

.br
.ls 1
	char *nfname;	/* name of notesfile */
.br
	char *text;	/* null terminated text to be entered */
.br
	char *title;	/* if non-null, title of note */
.br
	int dirflag;	/* != 0 -> director flag on (if allowed) */
.br
	int anonflag;	/* != 0 -> anonymous note (if allowed) */
.br
.ls
.KE

	If the *text pointer is NULL, the text of the note will be read
from standard input.
If no title is specified the subroutine will manufacture a title
from the first line of the note.
This routine is useful for error reports, user comments
about programs, and automatic logging of statistics or internal states.

	This routine can be loaded with a C program by specifying `-lnfcom'
on the `cc' command line.

.ss "Nfabort"

	Nfabort allows users to generate core images of their
process, save the core image in a ``known'' place,
and
log the fact in a notesfile.
This proves useful for intermittent failures;
when a program does crash,
a core image is placed in an appropriate place and a
message is placed in a notesfile.
The programmer regularly scans the notesfile and can examine
the core dump at his leisure.
Some of the problems of recreating conditions which cause errors
are eliminated by this approach.

	Nfabort is callable from the user program. It accepts
the following parameters:

	nfabort (nfname, message, title, cname, exitcode)

.KS
.br
The parameters are:

.br
.ls 1
	char *nfname;	/* name of notesfile */
.br
	char *message;	/* text string to insert */
.br
	char *title;	/* title of the message */
.br
	char *cname;	/* prefix for core image destination */
.br
	int exitcode;	/* code for exit() */
.ls
.KE

	The core image is placed in the file specified by
concatenating the ``cname'' argument and a unique 
integer (the process id of the current process).
The notesfile specified by the ``nfname'' parameter
receives a note whose body consists of the text pointed
to by ``message'' and a line telling the complete pathname
of the core image.
The title of the note is specified by the ``title'' 
parameter.
After the core image is generated and the
note has been written, 
nfabort terminates with the exit code specified
by the ``exitcode'' parameter.

	Nfabort generates default values for each of
the string parameters if NULL pointers are passed.
This routine can be loaded with a C program by specifying `-lnfcom'
on the `cc' command line.