Adding man pages for new libs and commands.
diff --git a/doc/man1/doio.1 b/doc/man1/doio.1
new file mode 100644
index 0000000..6d7c5eb
--- /dev/null
+++ b/doc/man1/doio.1
@@ -0,0 +1,70 @@
+.\"
+.\" $Id: doio.1,v 1.1 2000/07/27 16:59:03 alaffin Exp $
+.\"
+.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved.
+.\"
+.\" This program is free software; you can redistribute it and/or modify it
+.\" under the terms of version 2 of the GNU General Public License as
+.\" published by the Free Software Foundation.
+.\"
+.\" This program is distributed in the hope that it would be useful, but
+.\" WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+.\"
+.\" Further, this software is distributed without any warranty that it is
+.\" free of the rightful claim of any third person regarding infringement
+.\" or the like. Any license provided herein, whether implied or
+.\" otherwise, applies only to this software file. Patent licenses, if
+.\" any, provided herein do not apply to combinations of this program with
+.\" other software, or any other product whatsoever.
+.\"
+.\" You should have received a copy of the GNU General Public License along
+.\" with this program; if not, write the Free Software Foundation, Inc., 59
+.\" Temple Place - Suite 330, Boston MA 02111-1307, USA.
+.\"
+.\" Contact information: Silicon Graphics, Inc., 1600 Amphitheatre Pkwy,
+.\" Mountain View, CA 94043, or:
+.\"
+.\" http://www.sgi.com
+.\"
+.\" For further information regarding this notice, see:
+.\"
+.\" http://oss.sgi.com/projects/GenInfo/NoticeExplan/
+.\"
+.TH doio 1 10/13/93 "UNICOS Testing"
+.SH NAME
+\*Cdoio\fR - Executes I/O Requests
+.SH IMPLEMENTATION
+All Cray Research systems
+.SH SYNOPSIS
+\*Cdoio\fR
+.SH DESCRIPTION
+.QS
+Doio is one of the device-beater tools.
+.PP
+Options:
+.RS .5i
+.IP "-a"
+abort on data compare errors
+.IP "-n opt"
+.IP "-k opt"
+lockd request pipe
+.IP "-K opt"
+use fcntl() file locking
+.IP "-r opt"
+resource release interval
+.IP "-s opt"
+syscall log file
+.IP "-w opt"
+file write log file
+.IP "-v"
+verify writes if set
+.IP "-U opt"
+upanic() on varios conditions
+.RE
+.SH AUTHOR
+Mark Maule wrote the code.
+.br
+Glen Overby wrote the man page.
+.SH BUGS
+See "Features".
diff --git a/doc/man1/iogen.1 b/doc/man1/iogen.1
new file mode 100644
index 0000000..7732be0
--- /dev/null
+++ b/doc/man1/iogen.1
@@ -0,0 +1,78 @@
+.\"
+.\" $Id: iogen.1,v 1.1 2000/07/27 16:59:03 alaffin Exp $
+.\"
+.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved.
+.\"
+.\" This program is free software; you can redistribute it and/or modify it
+.\" under the terms of version 2 of the GNU General Public License as
+.\" published by the Free Software Foundation.
+.\"
+.\" This program is distributed in the hope that it would be useful, but
+.\" WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+.\"
+.\" Further, this software is distributed without any warranty that it is
+.\" free of the rightful claim of any third person regarding infringement
+.\" or the like. Any license provided herein, whether implied or
+.\" otherwise, applies only to this software file. Patent licenses, if
+.\" any, provided herein do not apply to combinations of this program with
+.\" other software, or any other product whatsoever.
+.\"
+.\" You should have received a copy of the GNU General Public License along
+.\" with this program; if not, write the Free Software Foundation, Inc., 59
+.\" Temple Place - Suite 330, Boston MA 02111-1307, USA.
+.\"
+.\" Contact information: Silicon Graphics, Inc., 1600 Amphitheatre Pkwy,
+.\" Mountain View, CA 94043, or:
+.\"
+.\" http://www.sgi.com
+.\"
+.\" For further information regarding this notice, see:
+.\"
+.\" http://oss.sgi.com/projects/GenInfo/NoticeExplan/
+.\"
+.TH iogen 1 10/13/93 "UNICOS Testing"
+.SH NAME
+\*Ciogen\fR - Generate I/O Requests
+.SH IMPLEMENTATION
+All Cray Research systems
+.SH SYNOPSIS
+\*Ciogen\fR
+.SH DESCRIPTION
+.QS
+Iogen is one of the device-beater tools.
+.PP
+Options:
+.RS .5i
+.IP "-f [opt]"
+open flags:
+raw, sync, ssd, ldraw, buffered
+.IP "-i [opt]"
+Number of iterations to run.
+0 implies infinite.
+.IP "-q"
+.IP "-m [opt]"
+Offset mode.
+One of: random, sequential, reverse.
+.IP "-o"
+Overlap flag.
+.IP "-p [opt]"
+output pipe (default is stdout)
+.IP "-r [opt]"
+specify raw io multiple instead of getting it from the mounted on device.
+Only applies to regular files.
+.IP "-s [opt]"
+System calls to use for I/O.
+A list of:
+read, write, reada, writea, ssread, sswrite
+.IP "-t [opt]"
+min transfer size
+.IP "-T [opt]"
+max transfer size
+.RE
+.SH AUTHOR
+Mark Maule wrote the code.
+.br
+Glen Overby wrote the man page.
+.SH BUGS
+See "Features".
diff --git a/doc/man3/forker.3 b/doc/man3/forker.3
new file mode 100644
index 0000000..b06c1e5
--- /dev/null
+++ b/doc/man3/forker.3
@@ -0,0 +1,151 @@
+.\"
+.\" $Id: forker.3,v 1.1 2000/07/27 16:59:03 alaffin Exp $
+.\"
+.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved.
+.\"
+.\" This program is free software; you can redistribute it and/or modify it
+.\" under the terms of version 2 of the GNU General Public License as
+.\" published by the Free Software Foundation.
+.\"
+.\" This program is distributed in the hope that it would be useful, but
+.\" WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+.\"
+.\" Further, this software is distributed without any warranty that it is
+.\" free of the rightful claim of any third person regarding infringement
+.\" or the like. Any license provided herein, whether implied or
+.\" otherwise, applies only to this software file. Patent licenses, if
+.\" any, provided herein do not apply to combinations of this program with
+.\" other software, or any other product whatsoever.
+.\"
+.\" You should have received a copy of the GNU General Public License along
+.\" with this program; if not, write the Free Software Foundation, Inc., 59
+.\" Temple Place - Suite 330, Boston MA 02111-1307, USA.
+.\"
+.\" Contact information: Silicon Graphics, Inc., 1600 Amphitheatre Pkwy,
+.\" Mountain View, CA 94043, or:
+.\"
+.\" http://www.sgi.com
+.\"
+.\" For further information regarding this notice, see:
+.\"
+.\" http://oss.sgi.com/projects/GenInfo/NoticeExplan/
+.\"
+.TH FORKER 3 07/25/2000 "Linux Test Project"
+.SH NAME
+forker \- fork desired number of copies of the current process
+.br
+background \- fork a process and return control to caller
+
+.SH SYNOPSIS
+int
+.br
+\fBbackground\fR(\fIprefix\fR)
+.br
+char *\fIprefix\fR;
+
+int
+.br
+\fBforker\fR(\fIncopies, mode, prefix\fR)
+.br
+int \fIncopies\fR;
+.br
+int \fImode\fR;
+.br
+char *\fIprefix\fR;
+
+extern int \fBForker_pids\fR[];
+.br
+extern int \fBForker_npids\fR;
+
+.SH DESCRIPTION
+The \fBbackground\fR function will do a fork of the current process.
+The parent process will then exit, thus orphaning the
+child process. Doing this will not nice the child process
+like executing a cmd in the background using "&" from the shell.
+If the fork fails and prefix is not NULL, a error message is printed
+to stderr and the process will exit with a value of errno.
+
+The \fBforker\fR function will fork \fIncopies\fR minus one copies
+of the current process. There are two modes in how the forks
+will be done. Mode 0 (default) will have all new processes
+be children of the parent process. Using Mode 1,
+the parent process will have one child and that child will
+fork the next process, if necessary, and on and on.
+The \fBforker\fR function will return the number of successful
+forks. This value will be different for the parent and each child.
+Using mode 0, the parent will get the total number of successful
+forks. Using mode 1, the newest child will get the total number
+of forks. The parent will get a return value of 1.
+
+The \fBforker \fRfunction also updates the global variables
+\fIForker_pids[\fR] and Forker_npids. The \fIForker_pids\fR array will
+be updated to contain the pid of each new process. The
+\fIForker_npids\fR variable contains the number of entries
+in \fIForker_pids.\fR Note, not all processes will have
+access to all pids via \fIForker_pids.\fR If using mode 0, only the
+parent process will have all information. If using mode 1,
+only the last child process will have all information.
+
+If the \fIprefix\fR parameter is not NULL and the fork system call fails,
+a error message will be printed to stderr. The error message
+will be preceded with \fIprefix\fR string. If \fIprefix\fR is NULL,
+no error message is printed.
+
+.SH EXAMPLES
+
+.nf
+.in +3
+/*
+ * The following is a unit test main for the background and forker
+ * functions.
+ */
+
+#include <stdio.h>
+
+main(argc, argv)
+int argc;
+char **argv;
+{
+ int ncopies=1;
+ int mode=0;
+ int ret;
+
+ if ( argc == 1 ) {
+ printf("Usage: %s ncopies [mode]\n", argv[0]);
+ exit(1);
+ }
+
+ if ( sscanf(argv[1], "%i", &ncopies) != 1 ) {
+ printf("%s: ncopies argument must be integer\n", argv[0]);
+ exit(1);
+ }
+
+ if ( argc == 3 )
+ if ( sscanf(argv[2], "%i", &mode) != 1 ) {
+ printf("%s: mode argument must be integer\n", argv[0]);
+ exit(1);
+ }
+
+ printf("Starting Pid = %d\n", getpid());
+ ret=background(argv[0]);
+ printf("After background() ret:%d, pid = %d\n", ret, getpid());
+
+ ret=forker(ncopies, mode, argv[0]);
+
+ printf("forker(%d, %d, %s) ret:%d, pid = %d, sleeping 30 seconds.\n",
+ ncopies, mode, argv[0], ret, getpid());
+ sleep(30);
+ exit(0);
+}
+.in -3
+.fi
+
+.SH "SEE ALSO"
+fork(2).
+
+.SH BUGS
+The child pids are stored in the fixed array, \fIForker_pids\fR.
+The array only has space for 4098 pids. Only the first
+4098 pids will be stored in the array.
+
diff --git a/doc/man3/get_attrib.3 b/doc/man3/get_attrib.3
new file mode 100644
index 0000000..52c673a
--- /dev/null
+++ b/doc/man3/get_attrib.3
@@ -0,0 +1,136 @@
+.\"
+.\" $Id: get_attrib.3,v 1.1 2000/07/27 16:59:03 alaffin Exp $
+.\"
+.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved.
+.\"
+.\" This program is free software; you can redistribute it and/or modify it
+.\" under the terms of version 2 of the GNU General Public License as
+.\" published by the Free Software Foundation.
+.\"
+.\" This program is distributed in the hope that it would be useful, but
+.\" WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+.\"
+.\" Further, this software is distributed without any warranty that it is
+.\" free of the rightful claim of any third person regarding infringement
+.\" or the like. Any license provided herein, whether implied or
+.\" otherwise, applies only to this software file. Patent licenses, if
+.\" any, provided herein do not apply to combinations of this program with
+.\" other software, or any other product whatsoever.
+.\"
+.\" You should have received a copy of the GNU General Public License along
+.\" with this program; if not, write the Free Software Foundation, Inc., 59
+.\" Temple Place - Suite 330, Boston MA 02111-1307, USA.
+.\"
+.\" Contact information: Silicon Graphics, Inc., 1600 Amphitheatre Pkwy,
+.\" Mountain View, CA 94043, or:
+.\"
+.\" http://www.sgi.com
+.\"
+.\" For further information regarding this notice, see:
+.\"
+.\" http://oss.sgi.com/projects/GenInfo/NoticeExplan/
+.\"
+.TH GET_ATTRIB 3 07/25/2000 "Linux Test Project"
+.SH NAME
+\fBget_attrib\fR \- Returns needed attributes to execute a command successfully on any system.
+.SH SYNOPSIS
+.sp
+\fB#include "get_attrib.h"\fR
+.sp
+\fBchar *get_attrib (char *\fIcommand_name\fB, char *\fIpermits\fB, char *\fIactive_categories\fB, char *\fIauthorized_categories\fB, long \fIflag\fR);\fR
+.SH DESCRIPTION
+The \fBget_attributes\fR routine is designed to determine the system type
+currently running and return the needed \fBruncmd(1)\fR string to run the
+command specified successfully on any 7.0 and above systems. On systems
+with TFM configured 'ON' some commands need special attributes that can't
+be determined easily, this routine then uses an internal table to return the
+needed attributes to run the command. On other system types the needed
+attributes are easily determined without use of this table.
+.PP
+The \fBget_attrib\fR arguments are as follows:
+.TP 10
+\fIcommand_name\fR
+Pointer to the command the attributes are to be returned about.
+.TP
+\fIpermits\fR
+Pointer to either an octal or name string of permits to be
+added to string returned.
+.TP
+\fIactive_category\fR
+Pointer to either an octal or name string of active categories to be
+added to string returned.
+.TP
+\fIauthorized_categories\fR
+Pointer to either an octal or name string of categories to be
+added to string returned.
+.TP
+\fIflag\fR
+Long set to any combination of values defined in get_attrib.h. These values
+are used to specify that the string returned should be for the specified
+system type.
+.sp
+ \fBGA_BOTH_OFF \fR PRIV_SU and PRIV_TFM off.
+.sp
+ \fBGA_SU_ON \fR PRIV_SU on.
+.sp
+ \fBGA_TFM_ON \fR PRIV_TFM on.
+.sp
+ \fBGA_BOTH_ON \fR PRIV_SU and PRIV_TFM on.
+.sp
+ \fBGA_CURRENT_SYS\fR Current system type.
+.sp
+.PP
+.SH "EXAMPLE"
+.P
+The following example shows how \fBget_attrib\fR can be used to determine
+the needed attributes to run a command successfully:
+.P
+.nf
+#include <stdio.h>
+#include "get_attrib.h"
+
+main()
+{
+ char cmd[256];
+ char *string;
+
+ if ((string =
+ get_attrib("mount",NULL,NULL,NULL,GA_CURRENT_SYS)) == (char *)NULL) {
+ printf("get_attrib() failed\en");
+ exit(1);
+ } else {
+ sprintf(cmd, "runcmd %s mount /dev/dsk/qtest3 /qtest3", string);
+ printf("Command = %s\en",cmd);
+ }
+
+
+ if ((string =
+ get_attrib("mount", NULL, NULL, NULL, GA_BOTH_OFF))==(char *)NULL) {
+ printf("get_attrib() failed\en");
+ exit(1);
+ } else {
+ sprintf(cmd, "runcmd %s mount /dev/dsk/qtest3 /qtest3", string);
+ printf("Command = %s\en",cmd);
+ }
+}
+.ni
+
+On an MLS system with PRIV_SU ON the first sprintf would return,
+\fBruncmd -u root mount /dev/dsk/qtest3 /qtest3\fR.
+
+On the same system the second sprintf would return, \fBruncmd -J secadm -j
+secadm mount /dev/dsk/qtest3 /qtest3\fR Which is as if PRIV_TFM and PRIV_SU
+were OFF.
+.PP
+.SH "RETURN VALUE"
+If \fBget_attrib()\fR completes successfully, a pointer to a string
+containing the options of the runcmd string is returned; otherwise NULL is
+returned.
+.SH ERRORS
+If \fBget_attrib()\fR has problems, an error message will be put in GA_Err_Msg
+and NULL will be returned.
+.SH "SEE ALSO"
+\fBget_attrib\fR(1)
+.P
+\fBruncmd\fR(1)
diff --git a/doc/man3/mc_getopt.3 b/doc/man3/mc_getopt.3
new file mode 100644
index 0000000..87f437a
--- /dev/null
+++ b/doc/man3/mc_getopt.3
@@ -0,0 +1,275 @@
+.\"
+.\" $Id: mc_getopt.3,v 1.1 2000/07/27 16:59:03 alaffin Exp $
+.\"
+.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved.
+.\"
+.\" This program is free software; you can redistribute it and/or modify it
+.\" under the terms of version 2 of the GNU General Public License as
+.\" published by the Free Software Foundation.
+.\"
+.\" This program is distributed in the hope that it would be useful, but
+.\" WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+.\"
+.\" Further, this software is distributed without any warranty that it is
+.\" free of the rightful claim of any third person regarding infringement
+.\" or the like. Any license provided herein, whether implied or
+.\" otherwise, applies only to this software file. Patent licenses, if
+.\" any, provided herein do not apply to combinations of this program with
+.\" other software, or any other product whatsoever.
+.\"
+.\" You should have received a copy of the GNU General Public License along
+.\" with this program; if not, write the Free Software Foundation, Inc., 59
+.\" Temple Place - Suite 330, Boston MA 02111-1307, USA.
+.\"
+.\" Contact information: Silicon Graphics, Inc., 1600 Amphitheatre Pkwy,
+.\" Mountain View, CA 94043, or:
+.\"
+.\" http://www.sgi.com
+.\"
+.\" For further information regarding this notice, see:
+.\"
+.\" http://oss.sgi.com/projects/GenInfo/NoticeExplan/
+.\"
+.TH MC_GETOPT 3 07/25/2000 "Linux Test Project"
+.SH NAME
+mc_getopt \- multiple character option parsing like getopt(3)
+.br
+mc_getoptv \- multiple character option parsing like getopt(3)
+
+.SH SYNOPSIS
+
+#include "mc_getopt.h"
+.br
+
+char *
+.br
+\fBmc_getopt\fR(\fIargc, argv, flags, optstring\fR)
+.br
+int \fIargc\fR;
+.br
+char \fI*argv[]\fR;
+.br
+int \fIflags\fR;
+.br
+char \fI*optstring\fR;
+
+\fBmc_getoptv\fR(\fIargc, argv, flags, nopts, opt_arr\fR)
+.br
+int \fIargc\fR;
+.br
+char \fI*argv[]\fR;
+.br
+int \fIflags\fR;
+.br
+int \fInopts\fR;
+.br
+char \fI*opt_arr[]\fR;
+.br
+
+extern int \fImc_optind\fR;
+.br
+extern char *\fImc_optarg\fR;
+.br
+extern char *\fImc_optopt\fR;
+
+.SH DESCRIPTION
+The \fBmc_getopt()\fR and \fBmc_getoptv()\fR functions are command line parsers.
+The \fIargc\fR parameter specifies the argument count and the \fIargv\fR parameter
+specifies the argument array. The \fIoptstring\fR argument contains a string
+of recognized option strings; if an option string is followed by a
+colon, the option takes an argument. Options are whitespace separated.
+A option string can be a single character or a word.
+
+The \fIopt_arr\fR array contains \fInopts\fR elements. Each option element in
+\fIopt_arr\fR must be NULL terminated string; if an option string is followed
+by a colon, the option takes an argument. A option string can be a
+single character or a word. \fIopt_arr\fR must be at least \fInopts\fR elements
+in size.
+
+The variable \fImc_optind\fR specifies the index of the next element of the
+\fIargv\fR parameter to be processed. It is initialized to 1, and the
+\fBmc_getopt()\fR function updates it as each element of \fIargv\fR is processed.
+
+The \fBmc_getopt()\fR and \fBmc_getoptv()\fR functions returns the \fIoptstring\fR
+string that uniquely matches the next element of the \fIargv\fR parameter.
+If the option string takes an argument, the \fBmc_getopt()\fR
+function sets the \fImc_optarg\fR variable to point to the option string
+argument according to the following rules:
+
+.BL
+.LI
+If the \fIargv\fR's option was the last option string in the string,
+\fImc_optarg\fR contains
+the next element of the \fIargv\fR array, and the \fImc_optind\fR variable is
+incremented by 2. If the resulting value of \fImc_optind\fR is greater than
+or equal to \fIargc\fR, the \fBmc_getopt()\fR function returns an \fBMC_MISSING_OPTARG\fR
+.LI
+Otherwise, \fImc_optarg\fR points to the string following the option
+character in that element of the \fIargv\fR parameter, and the \fImc_optind\fR
+variable is incremented by 1.
+.LE
+
+If any of the following conditions are true when the \fBmc_getopt()\fR
+function is called, the \fBmc_getopt()\fR function returns \fBMC_DONE\fR without
+changing the \fImc_optind\fR variable:
+
+.BL
+.LI
+\fIargv[\fImc_optind\fR] is a null pointer
+.LI
+*\fIargv[\fImc_optind\fR] is not the character '-'
+.LI
+\fIargv[\fImc_optind\fR] points to the string "-"
+.LE
+
+If the \fIargv[\fImc_optind\fR] parameter points to the "--" string, the \fImc_getopt\fR
+function returns \fBMC_DONE\fR after incrementing the \fImc_optind\fR variable.
+
+The \fIflags\fR argument can be used to change how an \fIargv\fR option string
+is compared to \fIoptstring\fR. The \fRflags\fR argument is a bitmask.
+The only two bits defined thus far are:
+
+.BL
+.LI
+\fBMC_FULL_TOKEN_MATCH\fR
+.LI
+MC_CASE_INSENSITIVE
+.LE
+
+How \fIflags\fR bits can be used to affect \fBmc_getopt()'\fRs actions:
+.BL
+.LI
+Without the \fBMC_FULL_TOKEN_MATCH\fR bit set, if the \fIargv\fR string exactly
+matches one \fIoptstring\fR option, that option will be returned.
+Otherwise, if the \fIargv\fR string matches the beginning of only one
+\fIoptstring\fR option, that \fIoptstring\fR option is returned.
+.LI
+With the \fBMC_FULL_TOKEN_MATCH\fR bit set, the \fIargv\fR string must exactly
+match the \fIoptstring\fR, excluding the colon ":". When word options are
+being used, the exact word option string must be in \fIargv\fR to be
+recognized as a match.
+.LI
+Without the MC_CASE_INSENSITIVE bit set, case comparisons are used.
+The -I option is different than the -i option.
+.LI
+With the MC_CASE_INSENSITIVE bit set, all strings are converted to
+lower case before comparisons are made. This means the -I and -i
+option are the same. The returned option string will be all lowercase.
+The \fBmc_getoptv()\fR function assumes the option string in the \fIopt_arr\fR
+is already converted to lowercase.
+.LE
+
+If the \fBmc_getopt(v)\fR function encounters an option string that is not
+contained in the \fIoptstring\fR parameter, it returns \fBMC_UNKNOWN_OPTION\fR
+string. If it detects a missing option argument, it returns
+\fBMC_MISSING_OPTARG\fR string. Unlike getopt, \fBmc_getopt()\fR will NOT print
+message if an \fIargv\fR option string is not found in \fIoptstring\fR.
+
+If the \fIargv\fR option string matches more than one \fIoptstring\fR strings,
+\fBMC_AMBIGUOUS_OPTION\fR string is returned.
+
+\fBmc_getopt\fR and \fBmc_getoptv\fR will not modify \fIargv\fR or \fIoptstring\fR.
+\fBmc_getopt\fR will will strdup \fIoptstring\fR and update some character pointers.
+The \fIoptstring\fR is parsed only once whenever a \fImc_optind\fR is set to
+one or once a \fBMC_DONE\fR was returned. The strdup space is freed before
+a \fBMC_DONE\fR is returned. This means that \fIoptstring\fR is ignored on all
+subsequent calls. The user is not given a pointer to the strdup'ed space; thus
+a user can not free it directly.
+
+.SH EXAMPLES
+.nf
+.in +3
+#include <stdio.h>
+#include "mc_getopt.h"
+
+#define ITERATION "iterations:"
+#define FLAG "flag"
+
+#define OPTSTR "iterations: flag"
+
+main(argc, argv)
+int argc;
+char **argv;
+{
+ char *option;
+ int iterate=1;
+ int flag=0;
+ extern int mc_optind;
+ extern char *mc_optarg, *mc_optopt;
+
+ while ( (option=mc_getopt(argc, argv, 0, OPTSTR)) != MC_DONE) {
+
+ if ( strcmp(MC_UNKNOWN_OPTION, option) == 0 ) {
+ fprintf(stderr,
+ "ERROR - Unknown option: \\"-%s\\"\\n", mc_optopt);
+ exit(1);
+ } else if ( strcmp(MC_AMBIGIOUS_OPTION, option) == 0 ) {
+ fprintf(stderr,
+ "ERROR - option \\"-%s\\" is not unique, be more specific\\n",
+ mc_optopt);
+ exit(1);
+ } else if ( strcmp(MC_MISSING_OPTARG, option) == 0 ) {
+ fprintf(stderr,
+ "ERROR - option \\"-%s\\" is missing its argument\\n",
+ mc_optopt);
+ exit(1);
+
+ } else if ( strcmp(option, ITERATION) == 0 ) {
+ if ( sscanf(mc_optarg, "%i", &iterate) != 1 ) {
+ fprintf(stderr,
+ "ERROR - option \\"-%s\\" argument must be numeric\\n",
+ mc_optopt);
+ exit(1);
+ }
+ } else if ( strcmp(option, FLAG) == 0 ) {
+ flag=1;
+ }
+
+ } /* end of mc_getopt loop */
+
+ /* ... code ... */
+
+}
+.in -3
+.fi
+
+.SH "SEE ALSO"
+getopt(3), parse_opts(3),
+.\"USC_setup(3).
+
+.SH DIAGNOSTICS
+The \fBmc_getopt(v)\fR function returns the next option string specified on
+the command line. The string will be the string as listed in \fIoptstring\fR.
+
+\fBMC_MISSING_OPTARG\fR is returned if the \fBmc_getopt(v)\fR function detects a
+missing argument.
+
+\fBMC_UNKNOWN_OPTION\fR is returned if the \fBmc_getopt(v)\fR function encounters an
+option string not in the \fIoptstring\fR argument.
+
+\fBMC_AMBIGUOUS_OPTION\fR is returned if the \fBmc_getopt(v)\fR function encounters
+option string that matches two or more \fIoptstring\fR argument and there
+is not a single exact match. This condition could occur if
+\fIflags\fR argument does not have the \fBMC_FULL_TOKEN_MATCH\fR bit set and
+the option string is not a unique string as defined in \fIoptstring\fR.
+(i.e. -it, when optsting contains " iterations: italic") It
+could also occur if an \fIoptstring\fR option is duplicated
+(i.e. -iterations, when optsting contains " iterations: iterations").
+
+Otherwise, the \fBmc_getopt(v)\fR function returns \fBMC_DONE\fR when all command
+line options are parsed.
+
+.SH LIMITATIONS
+\fBmc_getopt()\fR has an internal limit of 256 options
+allowed in \fIoptstring\fR.
+
+Most users are familiar with \fBgetopt\fR(3) and how it affects
+the parsing of command-lines. In attempting to deal with
+word, or multiple character, options, there are a couple
+differences between command-lines parsed with \fBgetop\fRt and
+\fBmc_getopt()\fR. Command-lines parsed with \fBmc_getopt()\fR,
+options can not be concatenated; each option must be listed beginning
+with "\fI-\fR" minus sign and be whitespace separated.
+The option argument can not be concatenated to the option;
+there must be a whitespace between the option and its argument.
diff --git a/doc/man3/parse_open_flags.3 b/doc/man3/parse_open_flags.3
new file mode 100644
index 0000000..ec55795
--- /dev/null
+++ b/doc/man3/parse_open_flags.3
@@ -0,0 +1,137 @@
+.\"
+.\" $Id: parse_open_flags.3,v 1.1 2000/07/27 16:59:03 alaffin Exp $
+.\"
+.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved.
+.\"
+.\" This program is free software; you can redistribute it and/or modify it
+.\" under the terms of version 2 of the GNU General Public License as
+.\" published by the Free Software Foundation.
+.\"
+.\" This program is distributed in the hope that it would be useful, but
+.\" WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+.\"
+.\" Further, this software is distributed without any warranty that it is
+.\" free of the rightful claim of any third person regarding infringement
+.\" or the like. Any license provided herein, whether implied or
+.\" otherwise, applies only to this software file. Patent licenses, if
+.\" any, provided herein do not apply to combinations of this program with
+.\" other software, or any other product whatsoever.
+.\"
+.\" You should have received a copy of the GNU General Public License along
+.\" with this program; if not, write the Free Software Foundation, Inc., 59
+.\" Temple Place - Suite 330, Boston MA 02111-1307, USA.
+.\"
+.\" Contact information: Silicon Graphics, Inc., 1600 Amphitheatre Pkwy,
+.\" Mountain View, CA 94043, or:
+.\"
+.\" http://www.sgi.com
+.\"
+.\" For further information regarding this notice, see:
+.\"
+.\" http://oss.sgi.com/projects/GenInfo/NoticeExplan/
+.\"
+.TH PARSE_OPEN_FLAGS 3 07/25/2000 "Linux Test Project"
+.SH NAME
+parse_open_flags \- converts open flag symbols into bitmask
+.br
+openflags2symbols \- converts open flag bitmask into symbols
+
+.SH SYNOPSIS
+int
+.br
+\fBparse_open_flags\fR(\fIsymbols, badname\fR)
+.br
+char *\fIsymbols\fR;
+.br
+char **\fIbadname\fR;
+
+char *
+.br
+\fBopenflags2symbols\fR(\fIopenflags, sep, mode\fR)
+.br
+int \fIopenflags\fR;
+.br
+char *\fIsep\fR;
+.br
+int \fImode\fR;
+
+.SH DESCRIPTION
+The \fBparse_open_flags\fR function can be used to convert
+a list of comma separated \fBopen\fR(2) flag symbols (i.e. O_TRUNC)
+into the bitmask that can be used by open(2).
+If a symbol is unknown and \fIbadname\fR is not NULL, \fIbadname\fR
+will updated to point that symbol in \fIsymbols\fR.
+\fBParse_open_flags\fR will return -1 on this error.
+Otherwise \fBparse_open_flags\fR will return the open flag bitmask.
+If \fBparse_open_flags\fR returns, \fIstring\fR will left unchanged.
+
+The \fBopenflags2symbols\fR function attempts to convert open flag
+bits into human readable symbols (i.e. O_TRUNC). If there
+are more than one symbol, the \fBsep\fR string will be placed as
+a separator between symbols. Commonly used separators would
+be a comma "," or pipe "|". If \fImode\fR is one and not all
+\fIopenflags\fR bits can be converted to symbols, the \fBUNKNOWN\fR
+symbol will be added to return string.
+Openflags2symbols will return the identified symbols.
+If no symbols are recognized the return value will be a empty
+string or the \fBUNKNOWN\fR symbol.
+
+If the \fBO_WRONLY\fR and \fBO_RDWR\fR bits are not set, \fBopenflags2symbols\fR
+assumes that \fBO_RDONLY\fR symbol is wanted.
+
+.SH "SEE ALSO"
+open(2),
+/usr/include/sys/fcntl.h.
+
+.SH EXAMPLES
+.nf
+.in +3
+/*
+ * The following code provides a UNIT test main for
+ * parse_open_flags and openflags2symbols functions.
+ */
+#include <stdio.h>
+
+main(argc, argv)
+int argc;
+char **argv;
+{
+ int bits;
+ int ret;
+ char *err;
+
+ if (argc == 1 ) {
+ printf("Usage: %s openflagsbits\n\t%s symbols\n", argv[0], argv[0]);
+ exit(1);
+ }
+
+ if ( sscanf(argv[1], "%i", &bits) == 1 ) {
+ printf("openflags2symbols(%#o, \",\", 1) returned %s\n",
+ bits, openflags2symbols(bits, ",", 1));
+
+ } else {
+ ret=parse_open_flags(argv[1], &err);
+ if ( ret == -1 )
+ printf("parse_open_flags(%s, &err) returned -1, err = %s\n",
+ argv[0], err);
+ else
+ printf("parse_open_flags(%s, &err) returned %#o\n", argv[0], ret);
+ }
+
+ exit(0);
+}
+
+.in -3
+.fi
+
+.SH LIMITATIONS
+Currently (06/96) all known symbols are coded into \fBopenflags2symbols\fR.
+If new open flags are added this function code will have to updated
+to know about them or they will not be recognized.
+
+The static space where \fBopenflags2symbols\fR stores open flag
+symbols with callers separators is limited to 512 characters.
+This should be large enough for most open flags symbols as long as the
+separator is kept short.
+
diff --git a/doc/man3/parse_opts.3 b/doc/man3/parse_opts.3
new file mode 100644
index 0000000..e1be610
--- /dev/null
+++ b/doc/man3/parse_opts.3
@@ -0,0 +1,167 @@
+.\"
+.\" $Id: parse_opts.3,v 1.1 2000/07/27 16:59:03 alaffin Exp $
+.\"
+.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved.
+.\"
+.\" This program is free software; you can redistribute it and/or modify it
+.\" under the terms of version 2 of the GNU General Public License as
+.\" published by the Free Software Foundation.
+.\"
+.\" This program is distributed in the hope that it would be useful, but
+.\" WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+.\"
+.\" Further, this software is distributed without any warranty that it is
+.\" free of the rightful claim of any third person regarding infringement
+.\" or the like. Any license provided herein, whether implied or
+.\" otherwise, applies only to this software file. Patent licenses, if
+.\" any, provided herein do not apply to combinations of this program with
+.\" other software, or any other product whatsoever.
+.\"
+.\" You should have received a copy of the GNU General Public License along
+.\" with this program; if not, write the Free Software Foundation, Inc., 59
+.\" Temple Place - Suite 330, Boston MA 02111-1307, USA.
+.\"
+.\" Contact information: Silicon Graphics, Inc., 1600 Amphitheatre Pkwy,
+.\" Mountain View, CA 94043, or:
+.\"
+.\" http://www.sgi.com
+.\"
+.\" For further information regarding this notice, see:
+.\"
+.\" http://oss.sgi.com/projects/GenInfo/NoticeExplan/
+.\"
+.TH PARSE_OPTS 3 07/25/2000 "Linux Test Project"
+.SH NAME
+parse_opts \- parse standard and user options
+.SH SYNOPSIS
+#include "test.h"
+#include "usctest.h"
+.sp
+char *\fBparse_opts\fR(ac, av, option_array)
+.br
+int ac;
+.br
+char **av;
+.br
+option_t option_array[\fInum\fR];
+.sp
+char *\fBSTD_opts\fR();
+.sp
+char *\fBSTD_opts_help\fR();
+.P
+.SH DESCRIPTION
+The \fBparse_opts\fR routine parses options from the command line, looking for user
+specified options or standard options (see below). The command line arguments are
+provided to \fBparse_opts\fR by sending the \fBargc\fR and \fBargv\fR from \fBmain\fR in the
+\fBac\fR and \fBav\fR parameters. User options may be specified in the \fBoption_array\fR.
+.sp
+The \fBoption_t\fR data type is defined as follows:
+.sp
+.nf
+typedef struct {
+ char *option; /* Valid option string (one option only) like "a:" */
+ int *flag; /* pointer to integer location to set true if option given */
+ char **arg; /* pointer to location to place argument, if needed */
+} option_t;
+.fi
+.sp
+Users specify options by initializing elements of an array of \fBoption_t\fR
+structures.
+.sp
+The \fBoption\fR field is the option string. If the option requires
+an argument, the last character must be a "\fB:\fR". If the user specifies a
+standard option, the standard option is disabled.
+.sp
+The \fBflag\fR field is a pointer to an integer location that is to be set if
+the option is present in the set of command line arguments (av). If the
+\fBoption\fR field does require an argument, then \fBflag\fR is optional,
+\fBflag\fR equal to NULL. Otherwise it must contain address of the integer
+to be set.
+.sp
+The \fBarg\fR field is a pointer to a character pointer variable that will be
+set to the option argument (av[optind]) if the option is present in the set of
+command line arguments. This pointer MUST be provided if the \fBoption\fR
+field contains a "\fB:\fR". Failure to provide a location will cause
+\fBparse_opts\fR to return an error.
+.sp
+For example, the following code defines two options, one with an argument,
+one without.
+.sp
+.nf
+int aflag, bflag;
+char *b_arg;
+option_t opt_array[3] = { {"a", &aflag, (char **) NULL}, /* No argument */
+ {"b:", &bflag, &b_arg} }; /* argument required */
+main(ac, av)
+int ac;
+char **av;
+{
+char* msg;
+
+if ( (msg=parse_opts(ac, av, opt_array)) != (char *) NULL )
+ error_exit(msg);
+}
+.fi
+.sp
+If no user options exist, a null pointer ( (option_t *)NULL ) must be sent
+as \fBoption_array\fR.
+.sp
+Below is a list of the standard options defined in \fBparse_opts\fR:
+.in +1
+.nf
+-\fBiteration\fI cnt\fR set STD_LOOP_COUNT to \fIcnt\fR if \fIcnt\fR > 0 (default 1).
+ Loop \fIcnt\fR times, or infinitely if \fIcnt\fR=0.
+-\fBduration\fI secs\fR Set STD_LOOP_WALLTIME to \fIsecs\fR (default is 0.0)
+ The test will loop until \fIsecs\fR has pasted.
+-\fBdelay\fI secs\fR This option will do a delay of \fIsecs\fR after each iteration.
+-\fBnofunc\fR set STD_FUNCTIONAL_TEST to 0 (default 1).
+
+-\fBerrno_logging\fR set STD_ERRNO_LOG to 1 (default 0). turn on
+ logging all errno's received.
+ This option is to facilitate security audit testing for MLS.
+-\fBpause_for_sigusr1\fR set STD_PAUSE to 1 (default 0). Pause for SIGUSR1 before
+ testing.
+-\fBtiming\fR set STD_TIMING_ON to 1 (default 0). Produce timing statistics.
+
+.fi
+.in -1
+To make dealing with word options easier, the parsing
+allows the minimum unique string that identifies an option.
+.sp
+It should be strongly noted that the minimum unique option string
+should only be used when running tests manually. When coding
+command lines in scripts or in databases, use the full option
+string. Failing to code full option strings, could under
+mine the effort of word options.
+
+.sp
+The \fBSTD_opts\fR routine returns
+a pointer to a string containing the usage information for the standard
+options recognized by \fBparse_opts\fR. The string is of the form:
+"[-iteration cnt][-duration secs][-delay secs][-nofunc]".
+.sp
+The \fBSTD_opts_help\fR routine returns a pointer to a string containing a
+help message, describing the standard options recognized by \fBparse_opts\fR.
+The format of the help message is as follows:
+.nf
+.in +1
+-o : Description
+.in -1
+.fi
+The option designator (-o) is in columns 3 and 4. The colon (:) is in column 11. The Description
+starts in column 13.
+.sp
+The STD_* flags are used by system call test macros defined in usctest.h
+(see \fBusctest(3)\fR), or may be used in the user's code.
+.SH "RETURN VALUES"
+\fBparse_opts\fR returns a null pointer upon successful completion.
+\fBparse_opts\fR validates the array of user options to verify that valid
+pointers are present when needed. If an error occurs in the
+\fBparse_opts\fR routine, a pointer to an error message is returned. The
+\fBSTD_opts\fR and \fBSTD_opts_help\fR routines each return a character pointer.
+.SH "SEE ALSO"
+mc_getopt(3),
+usctest(3).
+
+
diff --git a/doc/man3/parse_ranges.3 b/doc/man3/parse_ranges.3
new file mode 100644
index 0000000..9259317
--- /dev/null
+++ b/doc/man3/parse_ranges.3
@@ -0,0 +1,169 @@
+.\"
+.\" $Id: parse_ranges.3,v 1.1 2000/07/27 16:59:03 alaffin Exp $
+.\"
+.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved.
+.\"
+.\" This program is free software; you can redistribute it and/or modify it
+.\" under the terms of version 2 of the GNU General Public License as
+.\" published by the Free Software Foundation.
+.\"
+.\" This program is distributed in the hope that it would be useful, but
+.\" WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+.\"
+.\" Further, this software is distributed without any warranty that it is
+.\" free of the rightful claim of any third person regarding infringement
+.\" or the like. Any license provided herein, whether implied or
+.\" otherwise, applies only to this software file. Patent licenses, if
+.\" any, provided herein do not apply to combinations of this program with
+.\" other software, or any other product whatsoever.
+.\"
+.\" You should have received a copy of the GNU General Public License along
+.\" with this program; if not, write the Free Software Foundation, Inc., 59
+.\" Temple Place - Suite 330, Boston MA 02111-1307, USA.
+.\"
+.\" Contact information: Silicon Graphics, Inc., 1600 Amphitheatre Pkwy,
+.\" Mountain View, CA 94043, or:
+.\"
+.\" http://www.sgi.com
+.\"
+.\" For further information regarding this notice, see:
+.\"
+.\" http://oss.sgi.com/projects/GenInfo/NoticeExplan/
+.\"
+.TH PARSE_RANGES 3 07/25/2000 "Linux Test Project"
+.SH NAME
+parse_ranges \- function to parse a string formatted like 'min:max:mult,...'
+.SH SYNOPSIS
+.nf
+int parse_ranges(char *str, int defmin, int defmax, int defmult, int (*parse_func)(), char **rangeptr, char **errptr);
+int range_min(char *rbuf, int r);
+int range_max(char *rbuf, int r);
+int range_mult(char *rbuf, int r);
+.fi
+.SH DESCRIPTION
+parse_ranges() is a function to parse a comma-separated list of range
+tokens each having the following form:
+.SP
+.nf
+ num
+ or
+ min:max[:mult]
+.fi
+
+any of the values may be blank (ie. min::mult, :max, etc.) and default
+values for missing arguments may be supplied by the caller.
+
+The special first form is short hand for 'num:num'.
+
+After parsing the string, the ranges are put into an array of integers,
+which is malloc'd by the routine. The min, max, and mult entries of each
+range can be extracted from the array using the range_min(), range_max(),
+and range_mult() functions.
+
+If \fIrange_ptr\fP is not NULL, and parse_ranges() successfully parses the
+range string (ie. does not return -1), *range_ptr will point to space
+malloc'd by parse_ranges(). The user may free this space by calling free().
+
+parse_ranges() parameters are:
+.SP
+.TP 1i
+\fIstr\fP
+The string to parse - assumed to be a comma-separated
+list of tokens having the above format.
+.TP 1i
+\fIdefmin\fP
+default value to plug in for min, if it is missing
+.TP 1i
+\fIdefmax\fP
+default value to plug in for max, if it is missing
+.TP 1i
+\fIdefmult\fP
+default value to plug in for mult, if missing
+.TP 1i
+\fIparse_func\fP
+A user-supplied function pointer, which parse_ranges()
+can call to parse the min, max, and mult strings. This
+allows for customized number formats. The function
+MUST have the following prototype:
+.SP
+.nf
+ int parse_func(char *str, int *val)
+.fi
+.SP
+The function should return -1 if str cannot be parsed
+into an integer, or >= 0 if it was successfully
+parsed. The resulting integer will be stored in
+*val. If parse_func is NULL, parse_ranges will parse
+the tokens in a manner consistent with the the sscanf %i format.
+.TP 1i
+\fIrange_ptr\fP
+A user-supplied char **, which will be set to point
+at malloc'd space which holds the parsed range
+values. If range_ptr is NULL, parse_ranges() just
+parses the string. The data returned in range_ptr
+should not be processed directly - use the functions
+range_min(), range_max(), and range_mult() to access
+data for a given range.
+.TP 1i
+\fIerrptr\fP
+user-supplied char ** which can be set to point to a
+static error string. If errptr is NULL, it is ignored.
+.in -1i
+
+.SP
+range_min(), range_max(), and range_mult() parameters are:
+.SP
+.SP
+.TP 1i
+\fIrbuf\fP
+An array of ranges set up by parse_ranges().
+.TP 1i
+\fIr\fP
+The range number to extract information from. Must be an integer >= 0 and
+< the number of ranges returned by parse_ranges().
+.in -1i
+
+.SH EXAMPLES
+\fC
+.ta .25i +.25i +.25i +.25i
+.nf
+/*
+ * simple example to take a list of ranges on the cmdline (in argv[1]), and
+ * print a random number from within that range.
+ */
+
+#include <stdio.h>
+
+main()
+{
+ extern int parse_ranges(), range_min(), range_max(), range_mult();
+ extern long random_range(), random_range_seed();
+ int min, max, mult, nranges;
+ char *ep, *rp;
+
+ random_range_seed(getpid());
+ if ((nranges = parse_ranges(argv[1], 0, INT_MAX, 1, NULL, &rp, &ep)) < 0) {
+ fprintf(stderr, "parse_ranges() failed: %s\n", ep);
+ exit(1);
+ }
+
+ range = random_range(0, nranges-1, 1);
+ min = range_min(rp, range);
+ max = range_max(rp, range);
+ mult = range_mult(rp, range);
+
+ fprintf("%d\\n", random_range(min, max-1, mult));
+ exit(0);
+}
+\fP
+.DT
+.SH "SEE ALSO"
+random_range(3),
+random_range_seed(3),
+str_to_bytes(3).
+.SH DIAGNOSTICS
+parse_ranges() returns -1 on error or the number of ranges parsed. No space
+will be malloc'd if parse_ranges() fails. Error
+messages are passed back through the errptr parameter. There are no error
+conditions for range_min(), range_max(), or range_mult().
diff --git a/doc/man3/pattern.3 b/doc/man3/pattern.3
new file mode 100644
index 0000000..76b3988
--- /dev/null
+++ b/doc/man3/pattern.3
@@ -0,0 +1,90 @@
+.\"
+.\" $Id: pattern.3,v 1.1 2000/07/27 16:59:03 alaffin Exp $
+.\"
+.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved.
+.\"
+.\" This program is free software; you can redistribute it and/or modify it
+.\" under the terms of version 2 of the GNU General Public License as
+.\" published by the Free Software Foundation.
+.\"
+.\" This program is distributed in the hope that it would be useful, but
+.\" WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+.\"
+.\" Further, this software is distributed without any warranty that it is
+.\" free of the rightful claim of any third person regarding infringement
+.\" or the like. Any license provided herein, whether implied or
+.\" otherwise, applies only to this software file. Patent licenses, if
+.\" any, provided herein do not apply to combinations of this program with
+.\" other software, or any other product whatsoever.
+.\"
+.\" You should have received a copy of the GNU General Public License along
+.\" with this program; if not, write the Free Software Foundation, Inc., 59
+.\" Temple Place - Suite 330, Boston MA 02111-1307, USA.
+.\"
+.\" Contact information: Silicon Graphics, Inc., 1600 Amphitheatre Pkwy,
+.\" Mountain View, CA 94043, or:
+.\"
+.\" http://www.sgi.com
+.\"
+.\" For further information regarding this notice, see:
+.\"
+.\" http://oss.sgi.com/projects/GenInfo/NoticeExplan/
+.\"
+.TH PATTERN 3 07/25/2000 "Linux Test Project"
+.SH NAME
+pattern_fill \- Fill a buffer with copies of a pattern
+.br
+pattern_check \- Validate a buffer against copies of a pattern
+.SH SYNOPSIS
+\fBpattern_fill\fP(char *\fIbuf\fP, int \fIbuflen\fP, char *\fIpat\fP, int \fIpatlen\fP, int \fIpatshift\fP)
+.br
+\fBpattern_check\fP(char *\fIbuf\fP, int \fIbuflen\fP, char *\fIpat\fP, int \fIpatlen\fP, int \fIpatshift\fP)
+.SH DESCRIPTION
+\fBpattern_fill()\fP fills a buffer of length \fIbuflen\fP with repeated
+occurrences of a pattern whose length is \fIpatlen\fP.
+If \fIbuflen\fP is not a multiple of \fIpatlen\fP, a partial pattern will
+be written in the last part of the buffer. This implies that a buffer which is
+shorter than the pattern length will receive only a partial pattern.
+
+\fBpattern_check()\fP verifies that \fIbuf\fP contains repeated occurrences
+of the indicated pattern.
+
+The \fIpatshift\fP argument to \fBpattern_fill()\fP and \fBpattern_shift()\fP
+specify that \fIpat\fP should be rotated (\fIpatshift\fP % \fIpatlen\fP) bytes
+to the left before filling or comparing the buffer. Since the pattern is
+rotated by (\fIpatshift\fP % \fIpatlen\fP), \fIpatshift\fP may be greater than
+\fIpathlen\fP.
+.SH EXAMPLES
+\fBpattern_fill(buf, sizeof(buf), "abcde", 5, 0)\fR
+.br
+.RS 8
+
+fill buf with repeated occurrences of "abcde"
+
+.RE
+.br
+\fBpattern_check(buf, sizeof(buf), "abcde", 5, 0)\fR
+.br
+.RS 8
+
+verify that buf consists of repeated occurrences of "abcde"
+
+.RE
+.br
+\fBpattern_fill(buf, sizeof(buf), "abcde", 5, 3)\fR
+.br
+.RS 8
+
+fill buf with repeated occurrences of "deabc"
+
+.RE
+
+.SH DIAGNOSTICS
+\fBpattern_fill()\fP always returns 0 - no validation of arguments is done.
+.br
+\fBpattern_check()\fP returns -1 if the buffer does not contain repeated
+occurrences of the indicated pattern (rotated \fIpatshift\fB bytes) or 0
+otherwise.
+.SH BUGS
+None known.
diff --git a/doc/man3/random_range.3 b/doc/man3/random_range.3
new file mode 100755
index 0000000..025b21c
--- /dev/null
+++ b/doc/man3/random_range.3
@@ -0,0 +1,114 @@
+.\"
+.\" $Id: random_range.3,v 1.1 2000/07/27 16:59:03 alaffin Exp $
+.\"
+.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved.
+.\"
+.\" This program is free software; you can redistribute it and/or modify it
+.\" under the terms of version 2 of the GNU General Public License as
+.\" published by the Free Software Foundation.
+.\"
+.\" This program is distributed in the hope that it would be useful, but
+.\" WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+.\"
+.\" Further, this software is distributed without any warranty that it is
+.\" free of the rightful claim of any third person regarding infringement
+.\" or the like. Any license provided herein, whether implied or
+.\" otherwise, applies only to this software file. Patent licenses, if
+.\" any, provided herein do not apply to combinations of this program with
+.\" other software, or any other product whatsoever.
+.\"
+.\" You should have received a copy of the GNU General Public License along
+.\" with this program; if not, write the Free Software Foundation, Inc., 59
+.\" Temple Place - Suite 330, Boston MA 02111-1307, USA.
+.\"
+.\" Contact information: Silicon Graphics, Inc., 1600 Amphitheatre Pkwy,
+.\" Mountain View, CA 94043, or:
+.\"
+.\" http://www.sgi.com
+.\"
+.\" For further information regarding this notice, see:
+.\"
+.\" http://oss.sgi.com/projects/GenInfo/NoticeExplan/
+.\"
+.TH random_range 3 07/25/2000 "Linux Test Project"
+.SH NAME
+random_range \- a set of routines for dealing with integer ranges, and random numbers in a range
+.SH SYNOPSIS
+.nf
+void random_range_seed(int seed)
+long random_range(int min, int max, int mult, char **errp)
+long random_rangel(long min, long max, long mult, char **errp)
+long long random_rangell(long long min, long long max,
+ long long mult, char **errp)
+long random_bit(long mask)
+.fi
+.SH DESCRIPTION
+This is a set of routines for parsing numeric ranges, and choosing random
+numbers from a range.
+
+random_range() chooses a random number in the range min-max (inclusive) which
+is a multiple of mult. min and max may be any integer, but mult must be
+a positive integer greater than 0. errp is a char ** which is used to detect
+error conditions. If errp is not NULL, *errp will be set to point to an
+error message. If errp is NULL, error conditions cannot be detected by the
+caller. If mult is 1 (the most common case), there are no possible error
+conditions, and the return value is guaranteed to be valid.
+
+random_range_seed() sets the random number generator seed to the specified
+value.
+
+random_bit() will return a randomly selected single bit bitmask from the bits
+set in mask. The bit is randomly chosen using random_range().
+If mask is zero, zero is returned.
+
+random_range() functions uses lrand48() internally. If the range is bigger
+than will fit in a 32 bit long (2G), lrand48() with a
+a internal recursive algorithm to produce a random number.
+
+.SH EXAMPLES
+\fC
+.ta .25i +.25i +.25i +.25i
+.nf
+#include <stdio.h>
+
+main(argc, argv)
+int argc;
+char **argv;
+{
+ int r;
+ char *errp;
+ extern void random_range_seed();
+ extern long random_range();
+
+ random_range_seed(getpid());
+
+ r = random_range(atoi(argv[1]), atoi(argv[2]), atoi(argv[3]), &errp);
+ if (errp == NULL) {
+ fprintf(stderr, "random_range failed: %s\n", errp);
+ exit(1);
+ } else {
+ printf("%d\n", r);
+ }
+
+ exit(0);
+}
+\fP
+.fi
+
+.SH "SEE ALSO"
+lrand48(3c)
+.SH DIAGNOSTICS
+If random_range() fails, errp will point to NULL, and the return value will be
+undefined. If mult is 1, there are no possible error conditions, so the return
+value is always valid in this case.
+
+.SH BUGS
+On CRAY systems, random_range(), random_rangel(), random_rangell()
+all have the 64 bit limit since int, long and long long are always 64 bits.
+
+On IRIX systems, random_range() can only produce a 32 number.
+random_rangel() when compiled as a 32 bit object is still limited to 32 bit
+number. random_rangell() can be used to return a value bigger than 32 bits
+even when compiled as a 32 bit object.
+
diff --git a/doc/man3/random_range_seed.3 b/doc/man3/random_range_seed.3
new file mode 100755
index 0000000..6b4d131
--- /dev/null
+++ b/doc/man3/random_range_seed.3
@@ -0,0 +1,114 @@
+.\"
+.\" $Id: random_range_seed.3,v 1.1 2000/07/27 16:59:03 alaffin Exp $
+.\"
+.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved.
+.\"
+.\" This program is free software; you can redistribute it and/or modify it
+.\" under the terms of version 2 of the GNU General Public License as
+.\" published by the Free Software Foundation.
+.\"
+.\" This program is distributed in the hope that it would be useful, but
+.\" WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+.\"
+.\" Further, this software is distributed without any warranty that it is
+.\" free of the rightful claim of any third person regarding infringement
+.\" or the like. Any license provided herein, whether implied or
+.\" otherwise, applies only to this software file. Patent licenses, if
+.\" any, provided herein do not apply to combinations of this program with
+.\" other software, or any other product whatsoever.
+.\"
+.\" You should have received a copy of the GNU General Public License along
+.\" with this program; if not, write the Free Software Foundation, Inc., 59
+.\" Temple Place - Suite 330, Boston MA 02111-1307, USA.
+.\"
+.\" Contact information: Silicon Graphics, Inc., 1600 Amphitheatre Pkwy,
+.\" Mountain View, CA 94043, or:
+.\"
+.\" http://www.sgi.com
+.\"
+.\" For further information regarding this notice, see:
+.\"
+.\" http://oss.sgi.com/projects/GenInfo/NoticeExplan/
+.\"
+.TH random_range 3 07/25/2000 "Linux Test Project"
+.SH NAME
+random_range \- a set of routines for dealing with integer ranges, and random numbers in a range
+.SH SYNOPSIS
+.nf
+void random_range_seed(int seed)
+long random_range(int min, int max, int mult, char **errp)
+long random_rangel(long min, long max, long mult, char **errp)
+long long random_rangell(long long min, long long max,
+ long long mult, char **errp)
+long random_bit(long mask)
+.fi
+.SH DESCRIPTION
+This is a set of routines for parsing numeric ranges, and choosing random
+numbers from a range.
+
+random_range() chooses a random number in the range min-max (inclusive) which
+is a multiple of mult. min and max may be any integer, but mult must be
+a positive integer greater than 0. errp is a char ** which is used to detect
+error conditions. If errp is not NULL, *errp will be set to point to an
+error message. If errp is NULL, error conditions cannot be detected by the
+caller. If mult is 1 (the most common case), there are no possible error
+conditions, and the return value is guaranteed to be valid.
+
+random_range_seed() sets the random number generator seed to the specified
+value.
+
+random_bit() will return a randomly selected single bit bitmask from the bits
+set in mask. The bit is randomly chosen using random_range().
+If mask is zero, zero is returned.
+
+random_range() functions uses lrand48() internally. If the range is bigger
+than will fit in a 32 bit long (2G), lrand48() with a
+a internal recursive algorithm to produce a random number.
+
+.SH EXAMPLES
+\fC
+.ta .25i +.25i +.25i +.25i
+.nf
+#include <stdio.h>
+
+main(argc, argv)
+int argc;
+char **argv;
+{
+ int r;
+ char *errp;
+ extern void random_range_seed();
+ extern long random_range();
+
+ random_range_seed(getpid());
+
+ r = random_range(atoi(argv[1]), atoi(argv[2]), atoi(argv[3]), &errp);
+ if (errp == NULL) {
+ fprintf(stderr, "random_range failed: %s\n", errp);
+ exit(1);
+ } else {
+ printf("%d\n", r);
+ }
+
+ exit(0);
+}
+\fP
+.fi
+
+.SH "SEE ALSO"
+lrand48(3c)
+.SH DIAGNOSTICS
+If random_range() fails, errp will point to NULL, and the return value will be
+undefined. If mult is 1, there are no possible error conditions, so the return
+value is always valid in this case.
+
+.SH BUGS
+On CRAY systems, random_range(), random_rangel(), random_rangell()
+all have the 64 bit limit since int, long and long long are always 64 bits.
+
+On IRIX systems, random_range() can only produce a 32 number.
+random_rangel() when compiled as a 32 bit object is still limited to 32 bit
+number. random_rangell() can be used to return a value bigger than 32 bits
+even when compiled as a 32 bit object.
+
diff --git a/doc/man3/rmobj.3 b/doc/man3/rmobj.3
new file mode 100644
index 0000000..da8be36
--- /dev/null
+++ b/doc/man3/rmobj.3
@@ -0,0 +1,59 @@
+.\"
+.\" $Id: rmobj.3,v 1.1 2000/07/27 16:59:03 alaffin Exp $
+.\"
+.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved.
+.\"
+.\" This program is free software; you can redistribute it and/or modify it
+.\" under the terms of version 2 of the GNU General Public License as
+.\" published by the Free Software Foundation.
+.\"
+.\" This program is distributed in the hope that it would be useful, but
+.\" WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+.\"
+.\" Further, this software is distributed without any warranty that it is
+.\" free of the rightful claim of any third person regarding infringement
+.\" or the like. Any license provided herein, whether implied or
+.\" otherwise, applies only to this software file. Patent licenses, if
+.\" any, provided herein do not apply to combinations of this program with
+.\" other software, or any other product whatsoever.
+.\"
+.\" You should have received a copy of the GNU General Public License along
+.\" with this program; if not, write the Free Software Foundation, Inc., 59
+.\" Temple Place - Suite 330, Boston MA 02111-1307, USA.
+.\"
+.\" Contact information: Silicon Graphics, Inc., 1600 Amphitheatre Pkwy,
+.\" Mountain View, CA 94043, or:
+.\"
+.\" http://www.sgi.com
+.\"
+.\" For further information regarding this notice, see:
+.\"
+.\" http://oss.sgi.com/projects/GenInfo/NoticeExplan/
+.\"
+.TH RMOBJ 3 07/25/2000 "Linux Test Project"
+.SH NAME
+\fBrmobj\fR \- Remove a file, or a directory and all its subdirectories
+.SH SYNOPSIS
+\fBint rmobj(\fIobject\fB, \fIerrmsg\fB);
+.br
+ char *\fIobject\fB;
+.br
+ char **\fIerrmsg\fB;\fR
+.br
+.SH DESCRIPTION
+The \fBrmobj\fR function will remove the specified object. If the
+specified object is a directory, it will recursively remove the
+directory and everything underneath it. \fBrmobj\fR assumes that it
+has the necessary privilege to remove whatever was specified. If
+\fBrmobj\fR encounters any problems, and \fIerrmsg\fR is not NULL,
+\fIerrmsg\fR is set to point to a string explaining the error.
+.SH RETURN VALUE
+If \fBrmobj\fR encounters any problems, it will set \fIerrmsg\fR (if
+it was not NULL) and return -1. Otherwise it will return 0.
+.SH SEE ALSO
+.\"\fBsects(1)\fR
+.\".br
+\fBrmdir(2)\fR
+.br
+\fBunlink(2)\fR
diff --git a/doc/man3/str_to_bytes.3 b/doc/man3/str_to_bytes.3
new file mode 100644
index 0000000..0c5d2fc
--- /dev/null
+++ b/doc/man3/str_to_bytes.3
@@ -0,0 +1,101 @@
+.\"
+.\" $Id: str_to_bytes.3,v 1.1 2000/07/27 16:59:03 alaffin Exp $
+.\"
+.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved.
+.\"
+.\" This program is free software; you can redistribute it and/or modify it
+.\" under the terms of version 2 of the GNU General Public License as
+.\" published by the Free Software Foundation.
+.\"
+.\" This program is distributed in the hope that it would be useful, but
+.\" WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+.\"
+.\" Further, this software is distributed without any warranty that it is
+.\" free of the rightful claim of any third person regarding infringement
+.\" or the like. Any license provided herein, whether implied or
+.\" otherwise, applies only to this software file. Patent licenses, if
+.\" any, provided herein do not apply to combinations of this program with
+.\" other software, or any other product whatsoever.
+.\"
+.\" You should have received a copy of the GNU General Public License along
+.\" with this program; if not, write the Free Software Foundation, Inc., 59
+.\" Temple Place - Suite 330, Boston MA 02111-1307, USA.
+.\"
+.\" Contact information: Silicon Graphics, Inc., 1600 Amphitheatre Pkwy,
+.\" Mountain View, CA 94043, or:
+.\"
+.\" http://www.sgi.com
+.\"
+.\" For further information regarding this notice, see:
+.\"
+.\" http://oss.sgi.com/projects/GenInfo/NoticeExplan/
+.\"
+.TH STR_TO_BYTES 3 07/25/2000 "Linux Test Project"
+.SH NAME
+str_to_bytes \- convert a string to a int byte count
+str_to_lbytes \- convert a string to a long byte count
+str_to_llbytes \- convert a string to a long long byte count
+.SH SYNOPSIS
+int str_to_byte(char *\fIstr\fR);
+.br
+long str_to_lbyte(char *\fIstr\fR);
+.br
+long long str_to_llbyte(char *\fIstr\fR);
+.SH DESCRIPTION
+\fBstr_to_bytes()\fR, \fBstr_to_lbytes()\fR, and \fBstr_to_llbytes()\fR converts
+\fIstr\fR to an integer, long, or long long byte count. \fIstr\fR is an
+floating point number optionally followed by a single character multiplier.
+Currently the following multipliers are supported:
+.sp
+.nf
+ Char Meaning Multiplier
+ ---- --------- --------------------------------
+ b Blocks BSIZE or UBSIZE
+ k Kilobytes 2^10 (1024)
+ K Kilowords 2^10 (1024) * sizeof(long)
+ m Megabytes 2^20 (1048576)
+ M Megawords 2^20 (1048576) * sizeof(long)
+ g Gigabytes 2^30 (1073741824)
+ G Gigawords 2^30 (1073741824) * sizeof(long)
+.fi
+.sp
+\fIstr\fR is interpreted as floating point number (base 10).
+When using \fBstr_to_llbytes()\fR, the uppercase suffix will result
+in multiplying by the size of a (long long) or 8.
+.SH RETURNS
+-1 if the integer portion of \fIstr\fR is invalid, if an unsupported
+multiplier is supplied, or if \fIstr\fR has extra leading or trailing
+characters. If \fIstr\fR contains a negative number, the return
+value will be negative.
+.SH EXAMPLES
+\fBstr_to_bytes("1000")\fR
+.br
+.RS 8
+Returns 1000
+.RE
+.br
+\fBstr_to_bytes("5b")\fR
+.br
+.RS 8
+Returns 5 * BSIZE.
+.RE
+\fBstr_to_bytes("1.5m")\fR
+.br
+.RS 8
+Returns 1.5 * 1048576 or 1572864
+.RE
+
+.SH LIMITATIONS
+
+\fBstr_to_bytes()\fR and \fBstr_to_lbytes()\fR when compiled as
+a 32 bit IRIX binary can only return a max number of 2g (2147483647).
+However, \fBstr_to_lbytes()\fR is not limited by the 2g limit when
+compiled as 64 bit binary, where \fBstr_to_bytes()\fR still is limited.
+
+Note that the size of long will vary depending how if compiled as
+a 32 or 64 bit binary. The size of a long long is always 8.
+
+Also note that on a traditional CRAY system, a block is 4096 bytes, where
+on most IRIX systems a block is 1024 bytes.
+
diff --git a/doc/man3/string_to_tokens.3 b/doc/man3/string_to_tokens.3
new file mode 100644
index 0000000..9d864ff
--- /dev/null
+++ b/doc/man3/string_to_tokens.3
@@ -0,0 +1,71 @@
+.\"
+.\" $Id: string_to_tokens.3,v 1.1 2000/07/27 16:59:03 alaffin Exp $
+.\"
+.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved.
+.\"
+.\" This program is free software; you can redistribute it and/or modify it
+.\" under the terms of version 2 of the GNU General Public License as
+.\" published by the Free Software Foundation.
+.\"
+.\" This program is distributed in the hope that it would be useful, but
+.\" WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+.\"
+.\" Further, this software is distributed without any warranty that it is
+.\" free of the rightful claim of any third person regarding infringement
+.\" or the like. Any license provided herein, whether implied or
+.\" otherwise, applies only to this software file. Patent licenses, if
+.\" any, provided herein do not apply to combinations of this program with
+.\" other software, or any other product whatsoever.
+.\"
+.\" You should have received a copy of the GNU General Public License along
+.\" with this program; if not, write the Free Software Foundation, Inc., 59
+.\" Temple Place - Suite 330, Boston MA 02111-1307, USA.
+.\"
+.\" Contact information: Silicon Graphics, Inc., 1600 Amphitheatre Pkwy,
+.\" Mountain View, CA 94043, or:
+.\"
+.\" http://www.sgi.com
+.\"
+.\" For further information regarding this notice, see:
+.\"
+.\" http://oss.sgi.com/projects/GenInfo/NoticeExplan/
+.\"
+.TH STRING_TO_TOKEN 3 07/25/2000 "Linux Test Project"
+.SH NAME
+string_to_tokens \- Break a string into its tokens
+.SH SYNOPSIS
+.nf
+\fB
+int string_to_tokens(arg_string, arg_array, array_size, separator)
+char *arg_string;
+char *arg_array[];
+int array_size;
+char *separator;
+\fR
+.fi
+
+.SH DESCRIPTION
+This function parses the string \fIarg_string\fR, placing pointers to
+the \fIseparator\fR separated tokens into the elements of \fIarg_array\fR.
+The array is terminated with a null pointer.
+\fIarg_array\fR must contains at least \fIarray_size\fR elements.
+Only the first \fIarray_size\fR minus one tokens will be placed into
+\fIarg_array\fR. If there are more than \fIarray_size\fR-1 tokens, the rest are
+ignored by this routine.
+.RE
+
+.SH "SEE ALSO"
+strtok(3).
+
+.SH DIAGNOSTICS
+This function returns the number of \fIseparator\fR separated tokens that
+were found in \fIarg_string\fR.
+If \fIarg_array\fR or \fIseparator\fR is NULL or \fIarray_size\fR is less than 2,
+-1 is returned.
+
+.SH BUGS
+This function uses \fBstrtok()\fR to parse \fIarg_string\fR, and thus
+physically alters \fIarg_string\fR by placing null characters where the
+separators originally were.
+
diff --git a/doc/man3/tst_res.3 b/doc/man3/tst_res.3
new file mode 100644
index 0000000..05f4f02
--- /dev/null
+++ b/doc/man3/tst_res.3
@@ -0,0 +1,377 @@
+.\"
+.\" $Id: tst_res.3,v 1.1 2000/07/27 16:59:03 alaffin Exp $
+.\"
+.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved.
+.\"
+.\" This program is free software; you can redistribute it and/or modify it
+.\" under the terms of version 2 of the GNU General Public License as
+.\" published by the Free Software Foundation.
+.\"
+.\" This program is distributed in the hope that it would be useful, but
+.\" WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+.\"
+.\" Further, this software is distributed without any warranty that it is
+.\" free of the rightful claim of any third person regarding infringement
+.\" or the like. Any license provided herein, whether implied or
+.\" otherwise, applies only to this software file. Patent licenses, if
+.\" any, provided herein do not apply to combinations of this program with
+.\" other software, or any other product whatsoever.
+.\"
+.\" You should have received a copy of the GNU General Public License along
+.\" with this program; if not, write the Free Software Foundation, Inc., 59
+.\" Temple Place - Suite 330, Boston MA 02111-1307, USA.
+.\"
+.\" Contact information: Silicon Graphics, Inc., 1600 Amphitheatre Pkwy,
+.\" Mountain View, CA 94043, or:
+.\"
+.\" http://www.sgi.com
+.\"
+.\" For further information regarding this notice, see:
+.\"
+.\" http://oss.sgi.com/projects/GenInfo/NoticeExplan/
+.\"
+.TH TST_RES 3 07/25/2000 "Linux Test Project"
+.SH NAME
+tst_res \- Print result message, including file contents
+.sp
+tst_resm \- Print result message
+.sp
+tst_brk \- Print result message and break remaining test cases
+.sp
+tst_brkm \- Print result message, including file contents, and break remaining test cases
+.sp
+tst_brkloop \- Print result message and break remaining test cases in loop
+.sp
+tst_brkloopm \- Print result message, including file contents, and break remaining test cases in loop
+.sp
+tst_flush \- Print any messages pending because of CONDENSE mode, and flush output stream
+.sp
+tst_exit \- Exit test with a meaningful exit value
+.sp
+tst_environ \- Keep results coming to original stdout
+.SH SYNOPSIS
+\fB#include "test.h"\fR
+.P
+\fBvoid tst_res(int \fIttype\fB, char *\fIfname\fB, char *\fItmesg,
+[arg ...]\fR)
+.P
+\fBvoid tst_resm(int \fIttype\fB, char *\fItmesg, [arg ...]\fR)
+.P
+\fBvoid tst_brk(int \fIttype\fB, char *\fIfname\fB, void (*\fIfunc\fB)(),
+char *\fItmesg, [arg ...]\fR)
+.P
+\fBvoid tst_brkm(int \fIttype\fB, void (*\fIfunc\fB)(), char *\fItmesg,
+[arg ...]\fR)
+.P
+\fBvoid tst_brkloop(int \fIttype\fB, char *\fIfname\fB, void (*\fIfunc\fB)(),
+char *\fItmesg, [arg ...]\fR)
+.P
+\fBvoid tst_brkloopm(int \fIttype\fB, void (*\fIfunc\fB)(), char *\fItmesg,
+[arg ...]\fR)
+.P
+\fBvoid tst_flush()
+.P
+\fBvoid tst_exit()
+.P
+\fBint tst_environ()
+.P
+\fBextern int Tst_count;
+.br
+extern int Tst_range;
+.br
+extern int Tst_lpstart;
+.br
+extern int Tst_lptotal;
+\fR
+.SH DESCRIPTION
+.SS Introduction
+This library of functions are used by UNICOS tests to report results to
+standard out in a consistent manner. It is assumed that tests using this
+library have a distinct number of test cases, and that each test case is
+distinct and uniquely identified by the test case number. It is also assumed
+that test case results are printed in consecutive order, starting with 1.
+The library maintains a set of global variables (\fBTCID, TST_TOTAL,
+Tst_count, Tst_range, Tst_lpstart\fR, \fBTst_lptotal\fR), which are used by
+the various functions to format the results and to keep track of the current
+result reporting state (i.e. how many total test cases there are, and how
+many have been reported so far) for the calling test.
+.P
+The \fBTCID\fR and \fBTST_TOTAL\fR global variables are externed in the
+library, and MUST be defined/initialized by tests using the library.
+\fBTCID\fR must be set to the \fBT\fRest \fBC\fRase \fBID\fRentifier, and
+\fBTST_TOTAL\fR must be set to the total number of test cases that will be
+reported.
+.P
+The other global variables are available as externs to tests linked with
+tst_res.o. \fBTst_count\fR is the running count of the number of test
+results that have been reported so far. The library initializes it to 0, and
+it should not be modified by the test. \fBTst_range\fR, \fBTst_lpstart\fR,
+and \fBTst_lptotal\fR are used by to control how many test results are
+reported under certain conditions, by some of the functions in this library.
+The details are described below under the appropriate functions.
+.SS Arguments
+.RS 5
+.TP 10
+.I ttype
+test result type; one of \fBTPASS, TFAIL, TBROK, TCONF, TRETR, TWARN\fR, or
+\fBTINFO\fR (explained below).
+.TP 10
+.I fname
+pointer to a character string holding the name of a file whose contents will
+be printed on a new line following \fItmesg\fR. If this pointer is NULL, it
+is ignored.
+.TP 10
+.I tmesg, [arg ...]
+pointer to a character string containing a message explaining the test
+result. This character string can contain percent-sign conversion
+specifications as in \fBprintf\fR(3C) with corresponding \fIarg\fR arguments
+following the \fItmesg\fR argument.
+.br
+\fBNOTE:\fR These routines use static space internally to hold the
+expanded message. The maximum size allowed for an expanded message is
+2048 bytes.
+.TP 10
+.I func
+pointer to a function which performs either the cleanup necessary prior to
+exiting the test or some function executed at the end of each iteration of a
+loop.
+.RE
+.SS Result Types
+The possible test result types defined in \fBtest.h\fR are as follows:
+.RS 5
+.TP 10
+.B TPASS
+The test case produced expected results.
+.TP 10
+.B TFAIL
+The test case produced unexpected results.
+.TP 10
+.B TBROK
+A resource needed to execute the test case was not available (e.g. a
+temporary file could not be opened).
+.TP 10
+.B TCONF
+The test case was not appropriate for the current hardware or software
+configuration (e.g. MLS was not enabled).
+.TP 10
+.B TRETR
+The test case was no longer valid and has been "retired."
+.TP 10
+.B TWARN
+The testing procedure caused undesirable side effects that did not affect
+test results (e.g. a temporary file could not be removed after all test
+results were recorded).
+.TP 10
+.B TINFO
+An informative message about the execution of the test that does not
+correspond to a test case result and does not indicate a problem.
+.RE
+.SS Function Descriptions
+\fBtst_res()\fR and \fBtst_resm()\fR are the basic result reporting
+functions. They report 1 or more test case results of the specified
+\fIttype\fR. All result types are valid for these functions. The
+\fBTst_range\fR global variable indicates the number of results that will be
+reported for each call to one of these functions. It is initialized by the
+library to 1, but may be set to a value > 1 by the test. Each call to one of
+these functions will result in \fBTst_range\fR test case results being
+reported, each with an identical message (\fItmesg\fR). \fBTst_range\fR is
+always reset to 1 by the library before returning to the caller. If
+\fBtst_res()\fR is called with a \fIfname\fR argument, the contents of the
+file will only be printed for the first reported result. \fBtst_res()\fR
+takes the \fIfname\fR argument whereas \fBtst_resm()\fR does not.
+.P
+NOTE: All calls to \fBtst_res()\fR specifying a \fIttype\fR of \fBTWARN\fR or
+\fBTINFO\fR will be printed with a test case number of zero. Because of
+this, a \fBTst_range\fR value > 1 is not valid for these types.
+.P
+\fBtst_brk()\fR and \fBtst_brkm()\fR are used to report results for all test
+cases remaining in the test, and then call a cleanup function. The only
+result types that are valid for these functions are: \fBTFAIL, TBROK,
+TCONF\fR, and \fBTRETR\fR. When called with a \fIttype\fR of \fBTFAIL\fR or
+\fBTBROK\fR, one result of the specified \fIttype\fR will be printed,
+followed by results of type \fBTBROK\fR for the remaining test cases. When
+called with a \fIttype\fR of \fBTCONF\fR or \fBTRETR\fR, the specified
+\fIttype\fR will be printed for all remaining test cases. If \fIfunc\fR is
+not NULL, \fBtst_brk()\fR and \fBtst_brkm()\fR will call \fIfunc\fR after all
+results have been printed. If the call to \fIfunc\fR returns,
+\fBtst_brk()\fR and \fBtst_brkm()\fR will then call \fBtst_exit()\fR. If
+\fIfunc\fR is NULL, \fBtst_brk()\fR and \fBtst_brkm()\fR return to the caller
+after all results have been printed. If \fBtst_brk()\fR is called with a
+\fIfname\fR argument, the contents of the file will only be printed for the
+first reported result. \fBtst_brk()\fR takes the \fIfname\fR argument
+whereas \fBtst_brkm()\fR does not.
+.P
+\fBtst_brkloop()\fR and \fBtst_brkloopm()\fR work just like \fBtst_brk()\fR
+and \fBtst_brkm()\fR, except they only report results for a the test cases
+remaining in the current loop. The \fBTst_lpstart\fR and \fBTst_lptotal\fR
+global variables are used to determine how many test cases to report results
+for. Prior to the start of the loop, the test must set \fBTst_lpstart\fR to
+\fBTst_count\fR, and \fBTst_lptotal\fR to the number of test cases in the
+loop. If a test calls \fBtst_brkloop()\fR or \fBtst_brkloopm()\fR without
+first setting \fBTst_lpstart\fR and \fBTst_lptotal\fR to meaningful values, a
+WARN result will be reported and control will be immediately returned to the
+caller. This will most likely cause the result messages to be out of order.
+Unlike the \fBtst_brk()\fR functions, \fBtst_brkloop()\fR and
+\fBtst_brkloopm()\fR will not call \fBtst_exit()\fR if the \fIfunc\fR
+argument is not NULL and returns. \fBtst_brkloop()\fR takes the \fIfname\fR
+argument whereas \fBtst_brkloopm()\fR does not.
+.P
+\fBtst_flush()\fR is used to print any results pending because of
+\fBCONDENSE\fR or \fBNOPASS\fR modes (described below), and flushes the
+output stream.
+.P
+\fBtst_exit()\fR is used to allow tests to exit with a meaningful exit
+value. A bit is set in the exit value for each of the non passing test
+case result types (TFAIL, TBROK, and TWARN) encountered by the library.
+Thus any bit which is set in the exit value indicates that the
+corresponding result flag was used at least once in the test run.
+.P
+The current bit fields for the result types are as follows:
+.RS 5
+.TP 10
+TPASS
+0000 /* .... .... */
+.TP 10
+TFAIL
+0001 /* .... ...1 */
+.TP 10
+TBROK
+0002 /* .... ..1. */
+.TP 10
+TWARN
+0004 /* .... .1.. */
+.TP 10
+TRETR
+0010 /* .... 1... */
+.TP 10
+TINFO
+0020 /* ...1 .... */
+.TP 10
+TCONF
+0040 /* ..1. .... */
+.RE
+.P
+NOTE: \fBTPASS, TRETR, TINFO\fR, and \fBTCONF\fR do not have an effect
+on the test program exit status.
+.P
+\fBtst_environ()\fR is used to ensure that results reported by this library
+will go to the original stdout, even if the test changes the original stdout
+to another file, or closes it. A test may want to do this in order to
+redirect output that normally goes to stdout (e.g. printf() output) to a
+file. \fBtst_environ()\fR returns 0 upon successful completion, and -1 if it
+encountered any problems.
+.SS Output Modes
+Four output display modes are supported by the \fBtst_res()\fR family of
+functions to enhance output readability. The active mode is controlled via
+the environment variable \fBTOUTPUT\fR, which must be set prior to the start
+of the test in order to have any effect (see \fBksh\fR(1) for information on
+environment variables). The supported modes are as follows:
+.RS 5
+.TP 15
+.B VERBOSE
+A test result output line is generated for each test result. This is the
+default mode.
+.TP 15
+.B CONDENSE
+Consecutive, identical PASS, FAIL, BROK, CONF, and RETR test results are
+condensed into one output line. The test case number field contains the range
+of results involved. WARN and INFO output lines are not condensed, but
+printed as usual.
+.TP 15
+.B NOPASS
+All PASS, CONF, INFO, and RETR output lines are discarded (i.e. not printed),
+and consecutive, identical FAIL and BROK output lines are condensed as in
+\fBCONDENSE\fR mode. WARN output lines are printed as usual.
+.TP 15
+.B DISCARD
+All output lines are discarded.
+.RE
+.SH EXAMPLES
+.nf
+#include "test.h"
+
+char *TCID = "tsttcs01"; /* set test case identifier */
+int TST_TOTAL = 15; /* set total number of test results */
+extern int Tst_count; /* access count of results completed */
+extern int Tst_lpstart; /* holds value for start of loop */
+extern int Tst_lptotal; /* holds the number of test cases in loop */
+
+main()
+{
+ .
+ .
+ /* a successful test result */
+ tst_resm(TPASS, "\fIwhat was tested\fR");
+ /* or */
+ tst_res(TPASS, file, "\fIwhat was tested\fR");
+ .
+ .
+
+ /* break all remaining test results */
+ tst_brkm(TBROK, cleanup, "\fIwhat didn't work\fR");
+ /* or */
+ tst_brk(TBROK, file, cleanup, "\fIwhat didn't work\fR");
+ .
+ .
+
+ /* Break all remaining tests in loop */
+ Tst_lpstart = Tst_count;
+ Tst_lptotal = 5;
+
+ tst_brkloopm(TBROK, loop_setup, "\fIsetup did not work.\fR");
+ /* or */
+ tst_brkloop(TBROK, file, loop_setup, "\fIsetup did not work.\fR");
+ .
+ .
+
+ /* exit after all test results have been passed to tst_res */
+ tst_exit();
+}
+.fi
+.P
+Sample output:
+.RS 5
+.nf
+tsttcs01 1 PASS : Able to create MAXUP processes
+tsttcs01 2 FAIL : Too many processes (MAXUP+1) created
+tsttcs01 3 BROK : tabinfo(PROCTAB, &tbs) failed; errno = 13: Permission denied
+tsttcs01 4-10 BROK : Remaining cases broken
+tsttcs01 0 WARN : cleanup(): kill(0, SIGALRM) failed; errno = 3: No such process
+.fi
+.SH "SEE ALSO"
+utst_res(1),
+tst_setup(1),
+printf(3C),
+ksh(1).
+.SH DIAGNOSTICS
+.P
+A WARN result message will be printed if any of the following occur:
+.RS 5
+.P
+If an invalid test type is specified.
+.P
+If \fBTst_count\fR is negative.
+.P
+If \fBTst_range\fR is non-positive.
+.P
+If \fBTst_range\fR is > 1, and the test type is \fBTINFO\fR or \fBTWARN\fR.
+.P
+If one of the \fBtst_brk[loop][m]()\fR routines is called with a test type
+other than \fBTFAIL, TBROK, TCONF\fR, or \fBTRETR\fR.
+.P
+If \fBTst_lpstart\fR is negative.
+.P
+If \fBTst_lptotal\fR is non-positive.
+.P
+If there are any problems opening/reading/writing the contents of \fIfname\fR.
+.RE
+.SH LIMITATIONS
+If \fIfname\fR is NULL and \fItmesg\fR is NULL or empty, the result message
+will be empty. This allows a test to not print a message for a result, but
+it is not advised.
+.SH BUGS
+.P
+The programmer is free to alter the value of \fBTst_count\fR causing possible
+test result order problems.
+
diff --git a/doc/man3/tst_set_error.3 b/doc/man3/tst_set_error.3
new file mode 100644
index 0000000..afe7f0c
--- /dev/null
+++ b/doc/man3/tst_set_error.3
@@ -0,0 +1,150 @@
+.\"
+.\" $Id: tst_set_error.3,v 1.1 2000/07/27 16:59:03 alaffin Exp $
+.\"
+.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved.
+.\"
+.\" This program is free software; you can redistribute it and/or modify it
+.\" under the terms of version 2 of the GNU General Public License as
+.\" published by the Free Software Foundation.
+.\"
+.\" This program is distributed in the hope that it would be useful, but
+.\" WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+.\"
+.\" Further, this software is distributed without any warranty that it is
+.\" free of the rightful claim of any third person regarding infringement
+.\" or the like. Any license provided herein, whether implied or
+.\" otherwise, applies only to this software file. Patent licenses, if
+.\" any, provided herein do not apply to combinations of this program with
+.\" other software, or any other product whatsoever.
+.\"
+.\" You should have received a copy of the GNU General Public License along
+.\" with this program; if not, write the Free Software Foundation, Inc., 59
+.\" Temple Place - Suite 330, Boston MA 02111-1307, USA.
+.\"
+.\" Contact information: Silicon Graphics, Inc., 1600 Amphitheatre Pkwy,
+.\" Mountain View, CA 94043, or:
+.\"
+.\" http://www.sgi.com
+.\"
+.\" For further information regarding this notice, see:
+.\"
+.\" http://oss.sgi.com/projects/GenInfo/NoticeExplan/
+.\"
+.TH TST_SET_ERROR 3 07/25/2000 "Linux Test Project"
+.SH NAME
+tst_set_error \- Sets global Tst_error values
+.br
+tst_clear_error \- clears global Tst_error values
+.SH SYNOPSIS
+.nf
+\fB
+#include "test.h"
+
+void
+tst_set_error(file, line, func, fmt...)
+char *file;
+int line;
+char *func;
+char *fmt; /* printf format */
+
+void
+tst_clear_error()
+\fR
+.fi
+
+.SH DESCRIPTION
+These two functions provide a simple interface to allow
+a programmer set and clear the global variables in
+\fBTst_error\fR defined in \fItest_error.c\fR.
+
+The purpose of these global variables to provide space
+for error messages passing. Functions within our library
+can use this space and these routines to a pass error messages and
+some debug data to the caller.
+
+\fBTst_error\fR is a global variable, which is really a structure
+of five elements. The structure is defined \fItest.h\fR and looks
+like:
+
+.nf
+ int te_line;
+ /* line where last error was reported. */
+ /* Use "__LINE__" and let compiler do */
+ /* the rest */
+ int te_level;
+ /* If set, will prevent current stored */
+ /* error to not be overwritten */
+ char te_func[TST_ERR_FUNC_SIZE+1];
+ /* name of function of last error */
+ /* Name of function or NULL */
+ char te_file[TST_ERR_FILE_SIZE+1];
+ /* module of last error. Use */
+ /* "__FILE__" and let compiler do the */
+ /* rest */
+ char te_mesg[TST_ERR_MESG_SIZE+1];
+ /* string of last error */
+.fi
+
+Any new or existing function will be able to call \fBtst_set_error()\fR
+to save error information. Any caller of a function that uses
+this data, can access the data fields directly and print any of
+error data in desired format.
+
+Do not append newline to the end \fBte_mesg\fR string, it is the
+responsibility of the user of these mesg to print the trailing newline.
+This does not say that for long error messages, that there can not be
+newlines in the message.
+
+\fBtst_set_error()\fR will not overwrite these global variables if
+\fBTst_error.te_level\fR is not zero.
+
+\fBtst_clear_error()\fR will make all strings zero length and set all integers to zero.
+
+These global variables should not be used as the
+method for determining if there is an error. The functions that use
+\fBtst_set_error\fR, should provide another way to indicating that an error
+has occurred. These variables should be used reporting the error message.
+Although, if you use \fBtst_clear_error()\fR prior to calling any functions
+and \fBTst_error.te_mesg\fR[0] != '\0', you know someone reported an error or
+at least used the space.
+
+.RE
+
+.SH "Examples"
+
+To clear/initialize a programmer can use the tst_clear_error()
+function or access the variables directly.
+
+.nf
+#include "test.h"
+ ....
+ tst_clear_error();
+.fi
+
+To report an error, use tst_set_error() function:
+
+.nf
+#include "test.h"
+ ....
+ tst_set_error(__LINE__, __FILE__, "funcname",
+ "Malloc(%d) failed, errno:%d", size, errno);
+.fi
+
+To access the error information an issue an error message:
+
+.nf
+#include "test.h"
+ ....
+ fprintf(stderr, "%s: funcname failed: %s\n", Prog, Tst_error.te_mesg);
+
+.fi
+
+.SH DIAGNOSTICS
+Both functions are void, thus not return value.
+
+.SH BUGS
+There is no space overwrite preventions on the \fBTst_error.te_mesg\fR field.
+If \fIfmt\fR parameter of \fBtst_set_error\fR expands to a string
+larger than the space in \fBTst_error.te_mesg\fR, you will start overwriting
+memory. This field contains 1024 bytes, which is fairly big error message.
diff --git a/doc/man3/tst_sig.3 b/doc/man3/tst_sig.3
new file mode 100644
index 0000000..81afe19
--- /dev/null
+++ b/doc/man3/tst_sig.3
@@ -0,0 +1,142 @@
+.\"
+.\" $Id: tst_sig.3,v 1.1 2000/07/27 16:59:03 alaffin Exp $
+.\"
+.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved.
+.\"
+.\" This program is free software; you can redistribute it and/or modify it
+.\" under the terms of version 2 of the GNU General Public License as
+.\" published by the Free Software Foundation.
+.\"
+.\" This program is distributed in the hope that it would be useful, but
+.\" WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+.\"
+.\" Further, this software is distributed without any warranty that it is
+.\" free of the rightful claim of any third person regarding infringement
+.\" or the like. Any license provided herein, whether implied or
+.\" otherwise, applies only to this software file. Patent licenses, if
+.\" any, provided herein do not apply to combinations of this program with
+.\" other software, or any other product whatsoever.
+.\"
+.\" You should have received a copy of the GNU General Public License along
+.\" with this program; if not, write the Free Software Foundation, Inc., 59
+.\" Temple Place - Suite 330, Boston MA 02111-1307, USA.
+.\"
+.\" Contact information: Silicon Graphics, Inc., 1600 Amphitheatre Pkwy,
+.\" Mountain View, CA 94043, or:
+.\"
+.\" http://www.sgi.com
+.\"
+.\" For further information regarding this notice, see:
+.\"
+.\" http://oss.sgi.com/projects/GenInfo/NoticeExplan/
+.\"
+.TH TST_SIG 3 07/25/2000 "Linux Test Project"
+.SH NAME
+tst_sig \- set up for unexpected signals
+.SH SYNOPSIS
+.nf
+\fB
+#include "test.h"
+
+void tst_sig(fork_flag, handler, cleanup)
+char *fork_flag;
+int (*handler)();
+void (*cleanup)();
+\fR
+.fi
+.SH DESCRIPTION
+.P
+\fITst_sig\fR is used by UNICOS test case programs
+to set up signal handling functions for unexpected
+signals. This provides test cases with a graceful means
+of exiting following an unexpected interruption by a signal.
+\fITst_sig\fR should be called only once by a test
+program.
+.P
+The \fIfork_flag\fR parameter is used to tell \fItst_sig\fR
+whether or not to ignore the SIGCLD signal caused by the death of a
+child process that had previously been created by the
+\fIfork\fR(2) system call (see \fIsignal\fR(2) for more
+information on the SIGCLD signal).
+.P
+Setting \fIfork_flag\fR to FORK will cause \fItst_sig\fR to
+ignore the SIGCLD signal. This option should be set if the
+test program directly (eg. call \fIfork\fR(2)) or indirectly
+(eg. call \fIsystem\fR(3S)) creates a child process.
+.P
+Setting \fIfork_flag\fR to NOFORK will cause \fItst_sig\fR to
+treat the SIGCLD signal just as any other unexpected
+signal (ie. the \fIhandler\fR will be called).
+This option should be set by any test program which does not
+directly or indirectly create any child processes.
+.P
+The \fIhandler\fR parameter is
+a pointer to a function returning type int which is
+executed upon the receipt of an unexpected signal.
+The test program may pass a pointer to a signal handling
+function or it may elect to use a \fIdefault handler\fR
+supplied by \fItst_sig\fR.
+
+The \fIdefault handler\fR is specified by passing DEF_HANDLER
+as the \fIhandler\fR argument. Upon receipt of an unexpected
+signal, the \fIdefault handler\fR will generate
+\fItst_res\fR(3) messages for all test results that had
+not been completed at the time of the signal, execute the
+\fIcleanup\fR routine, if provided, and call \fItst_exit\fR.
+Note: if the \fIdefault handler\fR is used, the variables
+\fBTCID\fR and \fBTst_count\fR must be defined and available to
+\fItst_sig\fR (see \fItst_res\fR(3)).
+.P
+The \fIcleanup\fR parameter is a pointer to a user-defined
+function returning type void which is executed
+by the \fIdefault handler\fR. The \fIcleanup\fR function
+should remove any files, directories, processes, etc. created
+by the test program.
+If no cleanup is required, this parameter should be set to NULL.
+
+.SH EXAMPLES
+
+.nf
+#include "test.h"
+
+/*
+ * the TCID and TST_TOTAL variables must be available to tst_sig
+ * if the \fIdefault handler\fR is used. The \fIdefault handler\fR will call
+ * \fItst_res\fR(3) and will need this information.
+ */
+int TCID = "tsttcs01"; /* set test case identifier */
+int TST_TOTAL = 5; /* set total number of test results */
+
+
+ void tst_sig();
+
+ /*
+ * set up for unexpected signals:
+ * no \fIfork\fR() system calls will be executed during the test run
+ * use the default signal handler provided by \fItst_sig\fR
+ * no cleanup is necessary
+ */
+ tst_sig(NOFORK, DEF_HANDLER, NULL);
+
+
+ void tst_sig(), cleanup();
+ int handler();
+
+ /*
+ * set up for unexpected signals:
+ * \fIfork\fR() system calls will be executed during the test run
+ * use user-defined signal handler
+ * use cleanup
+ */
+ tst_sig(FORK, handler, cleanup);
+
+.fi
+.SH "SEE ALSO"
+signal(2),
+tst_res(3),
+tst_setup(1).
+.SH DIAGNOSTICS
+.P
+\fITst_sig\fR will output warnings in standard \fItst_res\fR
+format if it cannot set up the signal handlers.
diff --git a/doc/man3/tst_tmpdir.3 b/doc/man3/tst_tmpdir.3
new file mode 100644
index 0000000..94656b1
--- /dev/null
+++ b/doc/man3/tst_tmpdir.3
@@ -0,0 +1,76 @@
+.\"
+.\" $Id: tst_tmpdir.3,v 1.1 2000/07/27 16:59:03 alaffin Exp $
+.\"
+.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved.
+.\"
+.\" This program is free software; you can redistribute it and/or modify it
+.\" under the terms of version 2 of the GNU General Public License as
+.\" published by the Free Software Foundation.
+.\"
+.\" This program is distributed in the hope that it would be useful, but
+.\" WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+.\"
+.\" Further, this software is distributed without any warranty that it is
+.\" free of the rightful claim of any third person regarding infringement
+.\" or the like. Any license provided herein, whether implied or
+.\" otherwise, applies only to this software file. Patent licenses, if
+.\" any, provided herein do not apply to combinations of this program with
+.\" other software, or any other product whatsoever.
+.\"
+.\" You should have received a copy of the GNU General Public License along
+.\" with this program; if not, write the Free Software Foundation, Inc., 59
+.\" Temple Place - Suite 330, Boston MA 02111-1307, USA.
+.\"
+.\" Contact information: Silicon Graphics, Inc., 1600 Amphitheatre Pkwy,
+.\" Mountain View, CA 94043, or:
+.\"
+.\" http://www.sgi.com
+.\"
+.\" For further information regarding this notice, see:
+.\"
+.\" http://oss.sgi.com/projects/GenInfo/NoticeExplan/
+.\"
+.TH TST_TMPDIR 3 07/25/2000 "Linux Test Project"
+.SH NAME
+tst_tmpdir \- create a unique testing directory and make it current.
+.br
+tst_rmdir \- remove the directory created by \fBtst_tmpdir\fR.
+.SH SYNOPSIS
+\fBvoid tst_tmpdir()
+.P
+void tst_rmdir()
+.P
+extern char *TESTDIR;\fR
+.SH DESCRIPTION
+The \fBtst_tmpdir()\fR function uses the first three characters of the
+\fBTCID\fR global variable as the prefix in forming a unique directory name
+(via \fBtempnam\fR(3S)). The directory is then created and made the current
+working directory.
+.P
+If \fBtst_tmpdir()\fR cannot form a unique directory name, create the
+directory, or \fBchdir\fR to the directory, it uses \fBtst_brk()\fR to issue
+"BROK" messages for all test cases. It then exits via \fBtst_exit()\fR.
+Because \fBtst_tmpdir()\fR exits in the event of a problem, a test must call
+it \fBbefore\fR performing any operations that would require running a
+cleanup routine.
+.P
+The \fBtst_rmdir()\fR function recursively removes the directory created by
+\fBtst_tmpdir()\fR. This function should be used \fBonly\fR as a companion
+to \fBtst_tmpdir()\fR and should be called immediately prior to the test
+exiting via \fBtst_exit()\fR.
+.P
+\fBtst_rmdir()\fR uses the \fBsystem\fR(3S) library routine (which in turn
+calls \fBfork\fR(2)), so tests that use it \fBcannot\fR treat SIGCLD as an
+unexpected signal.
+.P
+Users may gain access to the name of the temporary directory by declaring the
+external character pointer \fBTESTDIR\fR.
+.SH DIAGNOSTICS
+The \fBtst_rmdir()\fR function will check the \fBTESTDIR\fR global variable
+to ensure that the user is not attempting to remove the root directory or
+some unspecified directories with a "*" parameter. All error/warning
+messages are delivered through \fBtst_res()\fR.
+.SH "SEE ALSO"
+fork(2), system(3S), tst_res(3), tmpnam(3S).
+
diff --git a/doc/man3/usctest.3 b/doc/man3/usctest.3
new file mode 100644
index 0000000..8426b03
--- /dev/null
+++ b/doc/man3/usctest.3
@@ -0,0 +1,171 @@
+.\" $Id: usctest.3,v 1.1 2000/07/27 16:59:03 alaffin Exp $
+.\"
+.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved.
+.\"
+.\" This program is free software; you can redistribute it and/or modify it
+.\" under the terms of version 2 of the GNU General Public License as
+.\" published by the Free Software Foundation.
+.\"
+.\" This program is distributed in the hope that it would be useful, but
+.\" WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+.\"
+.\" Further, this software is distributed without any warranty that it is
+.\" free of the rightful claim of any third person regarding infringement
+.\" or the like. Any license provided herein, whether implied or
+.\" otherwise, applies only to this software file. Patent licenses, if
+.\" any, provided herein do not apply to combinations of this program with
+.\" other software, or any other product whatsoever.
+.\"
+.\" You should have received a copy of the GNU General Public License along
+.\" with this program; if not, write the Free Software Foundation, Inc., 59
+.\" Temple Place - Suite 330, Boston MA 02111-1307, USA.
+.\"
+.\" Contact information: Silicon Graphics, Inc., 1600 Amphitheatre Pkwy,
+.\" Mountain View, CA 94043, or:
+.\"
+.\" http://www.sgi.com
+.\"
+.\" For further information regarding this notice, see:
+.\"
+.\" http://oss.sgi.com/projects/GenInfo/NoticeExplan/
+.\"
+.TH USCTEST 3 07/25/2000 "Linux Test Project"
+.SH NAME
+usctest \- macros and libraries for common functions in system call tests
+.SH SYNOPSIS
+\fBRoutines:\fR
+.br
+.in +1
+char *\fBparse_opts(\fI...\fB)\fR
+.in -1
+.sp
+\fBMacros\fR
+.in +1
+.br
+\fBTEST_PAUSE\fR
+.br
+\fBTEST_PAUSEF(\fIhand\fB)\fR
+.br
+\fBTEST(\fIsyscall\fB)\fR
+.br
+.\"\fBTEST_CALLER(\fIsyscall\fB, \fIpid\fB)\fR
+.\".br
+\fBTEST_VOID(\fIsyscall\fB)\fR
+.br
+\fBTEST_CLEANUP\fR
+.br
+\fBTEST_LOOPING(\fIcounter\fB)\fR
+.br
+\fBTEST_ERROR_LOG(\fIerrno\fB)\fR
+.br
+\fBTEST_EXP_ENOS(\fIarray\fB)\fR
+.in -1
+.sp
+\fBGlobal Variable(s)\fR (see \fBparse_opts(3)\fR for complete list):
+.br
+.in +1
+int \fBTEST_RETURN\fR; /* set by the \fBTEST\fR macro to the return code from \fIsyscall\fR */
+.br
+int \fBTEST_ERRNO\fR; /* set by the \fBTEST\fR macro to the value of \fBerrno\fR after \fIsyscall\fR returns */
+.br
+/* All STD_* variables referenced below are set by the \fBparse_opts(3)\fR routine. */
+.in -1
+
+.SH DESCRIPTION
+The \fBTEST_PAUSE\fR macro checks if the global variable STD_PAUSE is set. If so, it
+pauses for a SIGUSR1 before continuing execution. The signal handler used does nothing.
+After the signal is processed, the previous action is replaced for SIGUSR1.
+.sp
+The \fBTEST_PAUSEF(\fIhand\fB)\fR macro checks if the global variable STD_PAUSE is set. If so, it
+pauses for a SIGUSR1 before continuing execution. The \fIhand\fR argument is a function to be used
+to handle the SIGUSR1 signal when it is received.
+After the signal is processed, the previous action is replaced for SIGUSR1.
+.sp
+The \fBTEST(\fIsyscall\fB)\fR macro executes (\fIsyscall\fR) and times its execution.
+It saves the max time, min time, accumulated time, and
+execution count, if STD_TIMING_ON is set.
+.sp
+.\"The\fBTEST_CALLER(\fIsyscall\fB, \fIpid\fB)\fR macro executes (\fIsyscall\fR) and times its execution.
+.\"It saves the max time, min time, accumulated time, and
+.\"execution count, if STD_TIMING_ON is set and if \fIpid\fR is equal to the current pid.
+.\".sp
+The \fBTEST_VOID(\fIsyscall\fB)\fR macro works exactly the same as the \fBTEST()\fR
+macro except that it does NOT set the global \fBTEST_RETURN\fR. It is intended
+to be used with system calls that do not have a return value.
+.sp
+The \fBTEST_CLEANUP\fR macro prints timing statistics,
+accumulated through the TEST macro, if STD_TIMING_ON is set. Also, prints the \fBerrno\fR return
+counts as logged by the \fBTEST_ERROR_LOG\fR macro, if STD_ERR_LOG is set. \fBTEST_CLEANUP\fR uses
+\fBtst_resm(3)\fR to output this information.
+.sp
+The \fBTEST_LOOPING(\fIcounter\fB)\fR macro checks \fIcounter\fR against
+the global variable STD_LOOP_COUNTER. If \fIcounter\fR is less than STD_LOOP_COUNTER or STD_INFINITE
+is set, it returns TRUE.
+.sp
+The \fBTEST_ERROR_LOG\fR macro records the return of \fIerrno\fR as unexpected, unless the option to
+turn it off is specified on the command line.
+.sp
+The \fBTEST_EXP_ENOS(\fIarray\fB)\fR macro sets an internal flag for each errno in \fIarray\fR, indicating
+that the errno is expected at some point in the test. This is used by the TEST_CLEANUP macro to determine
+which errnos are expected when printing the log. The \fIarray\fR must be zero terminated.
+.sp
+The \fBparse_opts\fR routine parses the command line (see \fBparse_opts(3)\fR). All STD_* global
+variables used are set by the \fBparse_opts(3)\fR routine.
+
+.SH EXAMPLES
+Below is a partial template of a system call test using these routines, macros, and global variables. A complete
+template may be found in the CUTS/sun/skel directory, in the file \fBusctest.c\fR.
+
+.nf
+void
+setup()
+{
+TEST_PAUSE /* Pause if option specified */
+}
+
+void
+cleanup()
+{
+TEST_CLEANUP
+}
+
+main(ac, av)
+{
+int lc; /* loop counter */
+char *msg; /* return from parse_opts */
+
+int exp_enos[]={EACCESS, 0}; /* expected errnos */
+
+
+TEST_EXP_ENOS(exp_enos); /* set expected errnos */
+
+setup(); /* execute setup */
+
+/* parse options */
+msg=parse_opts(ac, av, (option_t *)NULL);
+
+/* Check parse_opts return */
+
+for (lc=0; TEST_LOOPING(lc); lc++) {
+ TEST(open("file", O_RDWR))
+
+ if ( TEST_RETURN == -1) {
+ TEST_ERROR_LOG(TEST_ERRNO)
+ /* BREAK test case, or whatever... */
+ }
+
+}
+
+cleanup();
+}
+.fi
+
+.SH "SEE ALSO"
+parse_opts(3).
+
+.SH "RETURN VALUES"
+The TEST_LOOPING macro evaluates to TRUE (1) or FALSE (0), and is intended for use in while or
+for loops. The TEST macro places the return value from \fIsyscall\fR in the global variable TEST_RETURN
+and the errno in the global variable TEST_ERRNO. The \fBTEST_PAUSE\fR, \fBTEST_PAUSEF\fR,
+\fBTEST_CLEANUP\fR, \fBTEST_ERROR_LOG\fR, and \fBTEST_EXP_ENOS\fR macros do not have any return values.
diff --git a/doc/man3/write_log.3 b/doc/man3/write_log.3
new file mode 100644
index 0000000..c5ceffb
--- /dev/null
+++ b/doc/man3/write_log.3
@@ -0,0 +1,244 @@
+.\"
+.\" $Id: write_log.3,v 1.1 2000/07/27 16:59:03 alaffin Exp $
+.\"
+.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved.
+.\"
+.\" This program is free software; you can redistribute it and/or modify it
+.\" under the terms of version 2 of the GNU General Public License as
+.\" published by the Free Software Foundation.
+.\"
+.\" This program is distributed in the hope that it would be useful, but
+.\" WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+.\"
+.\" Further, this software is distributed without any warranty that it is
+.\" free of the rightful claim of any third person regarding infringement
+.\" or the like. Any license provided herein, whether implied or
+.\" otherwise, applies only to this software file. Patent licenses, if
+.\" any, provided herein do not apply to combinations of this program with
+.\" other software, or any other product whatsoever.
+.\"
+.\" You should have received a copy of the GNU General Public License along
+.\" with this program; if not, write the Free Software Foundation, Inc., 59
+.\" Temple Place - Suite 330, Boston MA 02111-1307, USA.
+.\"
+.\" Contact information: Silicon Graphics, Inc., 1600 Amphitheatre Pkwy,
+.\" Mountain View, CA 94043, or:
+.\"
+.\" http://www.sgi.com
+.\"
+.\" For further information regarding this notice, see:
+.\"
+.\" http://oss.sgi.com/projects/GenInfo/NoticeExplan/
+.\"
+.TH WRITE_LOG 3 07/25/2000 "Linux Test Project"
+.SH NAME
+write_log \- a set of routines for logging writes to a history file
+.SH SYNOPSIS
+.nf
+\fB#include "write_log.h"\fP
+
+\fBint wlog_open(struct wlog_file *\fIwfile\fB, int \fItrunc\fB, int \fImode\fB);\fR
+\fBint wlog_close(struct wlog_file *\fIwfile\fB);\fR
+\fBint wlog_record_write(struct wlog_file *\fIwfile\fB, struct wlog_rec *\fIwrec\fB, long \fIoffset\fB);\fR
+\fBint wlog_scan_backward(struct wlog_file *\fIwfile\fB, int \fInrecs\fB, int (*func)(struct wlog_rec *\fIrec\fB), long \fIdata\fB);\fR
+
+\fBchar *Wlog_Error_String;\fR
+.fi
+.SH DESCRIPTION
+
+The write_log package is a set of routines for creating a history file
+of write operations done to a set of files.
+
+It is assumed that the actual pattern written to the file will be
+repeated occurrences of a string whose length is no greater than
+WLOG_MAX_PATTERN. See the pattern(3) man
+page for routines to conveniently generate buffers of this kind.
+
+wlog_open() initializes the history file contained in wfile->w_file, and
+fills in the wfile structure. If trunc is non-zero, and existing history
+file by the same name will be truncated. If no history file exists, it
+will be created with the specified mode.
+
+wlog_close() releases any resources associated with the given wfile. Use
+of wfile after this point is undefined until it is initialized again with
+wlog_open().
+
+wlog_record_write() is the main routine for putting a wlog_rec into the
+history file. The caller is responsible for supplying a fully initialized
+wlog_rec structure. If offset is < 0, the record will be appended to the
+end of the history file. If offset is >= 0, the record will be written
+at the indicated offset. This, along with the w_done field in the wlog_rec
+structure, provide a mechanism for 'pre-logging' a write, doing the write
+operation, and then overlaying the original record with the w_done flag
+set to 1. This is useful for async writes which may not complete in a
+timely manner. It is also useful for seeing which write operations were
+pending at the time of a system crash - the ones whose w_done flag is 0 have
+not yet been verified as complete.
+The return value from wlog_record_write() is the offset
+in the history file at which the record was written.
+
+wlog_scan_backward() can be used to conveniently scan a write history file.
+The routine scans the file in reverse order (ie. first record written is
+scanned last). For every record found, the user supplied function is called
+with 2 parameters: the read record, and an arbitrary word passed in by the
+user. This word may be interpreted however the user desires. If nrecs is
+greater than 0, up to nrecs will be scanned. The user supplied function should
+return 1 of the following: WLOG_STOP_SCAN, or WLOG_CONTINUE_SCAN.
+WLOG_STOP_SCAN provides a way for the user supplied function to prematurely
+abort the scanning process. WLOG_CONTINUE_SCAN instructs wlog_scan_backward()
+to continue scanning the next record.
+
+In order for the history file to be effective, some basic rules must
+be followed by the programs using the history mechanism:
+
+.in +.5i
+.ll -.5i
+The area of the data file being written must be locked from
+before the write operation, until after the wlog_record_write()
+is complete. This is necessary to 'synchronize' simultaneous
+writes to the same area of a file. Note that the entire file
+does not need to be locked, only the portion being written to.
+If the calling program can guarantee that there will never be more
+than 1 process writing to the same area of a file at the same time,
+locking is not necessary. (Note: UNICOS Shared File Systems do not support
+record locking. The whole file is silently locked.)
+
+Pathnames in the history file (w_path field) should be full
+pathnames if possible. This allows validation tools to be
+able to find the test files without having to take working
+directory considerations into account.
+.ll +.5i
+.in -.5i
+
+.nf
+\fC
+.ta .25i +.5i +1i
+/*
+ * write log file data type. wlog_open() initializes this structure
+ * which is then passed around to the various wlog_xxx routines.
+ */
+
+struct wlog_file {
+ int w_afd; /* append fd */
+ int w_rfd; /* random-access fd */
+ char w_file[1024]; /* name of the write_log */
+};
+\fR
+.DT
+.fi
+
+.nf
+\fC
+.ta .25i +.5i +2.0i
+/*
+ * User view of a history file record. Note that this is not
+ * necessarily how the data is formatted on disk (significant
+ * compression occurs), so don't expect to od(1) the history file and
+ * see things formatted this way. See the file write_log.h for comments
+ * on how the data is actually written to disk.
+ */
+
+struct wlog_rec {
+ int w_pid; /* pid doing the write */
+ int w_offset; /* file offset */
+ int w_nbytes; /* # bytes written */
+ int w_oflags; /* low-order open() flags */
+ int w_done; /* 1 if io confirmed done */
+ int w_async; /* 1 if async write (writea) */
+
+ char w_host[WLOG_MAX_HOST+1]; /* host doing write */
+ int w_hostlen; /* host name length */
+ char w_path[WLOG_MAX_PATH+1]; /* file written to */
+ int w_pathlen; /* file name length */
+ char w_pattern[WLOG_MAX_PATTERN+1]; /* pattern written */
+ int w_patternlen; /* pattern length */
+};
+\fR
+.DT
+.fi
+
+Note: The history files can become very large very quickly if a lot of
+processes are logging writes. This is especially apt to happen if long
+pathnames or patterns are used. This is because the w_host, w_path, and
+w_pattern fields are variable length fields when stored on disk. Thus, use
+short pathnames and patterns to minimize the size of the history file. If
+any of the w_path, w_pattern, or w_host fields are not important to you, set
+the respective length field to 0 in the wlog_rec structure.
+
+.SH EXAMPLES
+This is a simple example of how to initialize a history file, and
+record a write to it.
+
+.nf
+#include "write_log.h"
+
+main()
+{
+ struct wlog_rec wrec;
+ struct wlog_file wfile;
+
+ ...
+ strcpy(wfile.w_file, hisfile);
+ if (wlog_open(&wfile, 1, 0666) < 0) {
+ fprintf("wlog_open failed\n");
+ exit(2);
+ }
+
+ ...
+
+ wrec.w_pid = getpid();
+ wrec.w_offset = write_offset;
+ wrec.w_nbytes = nbytes;
+ wrec.w_oflags = open_flags;
+ wrec.w_done = 0;
+ wrec.w_async = 0;
+ wrec.w_host = 0; /* don't care about host */
+
+ wrec.w_pathlen = sprintf(wrec.w_path, "%s", path);
+ wrec.w_patternlen = sprintf(wrec.w_pattern, "%s", pattern);
+
+ pattern_fill(buf, nbytes, pattern, strlen(pattern), 0);
+
+ ... lock fd here ...
+
+ log_offset = wlog_record_write(&wfile, &wrec, -1);
+ write(fd, buf, nbytes);
+ wrec.w_done = 1;
+ wlog_record_write(&wfile, &wrec, log_offset);
+
+ ... unlock fd here ...
+
+ ...
+
+ /*
+ * Scan the logfile printing records for the file in 'path'.
+ */
+
+ wlog_scan_backward(&wfile, 0, print_log_record, (long)path);
+}
+
+int
+print_log_record(record, data)
+struct wlog_rec *record;
+long data;
+{
+ char *path;
+
+ path = (char *)data;
+ if (strcmp(record->w_path, path) == 0) {
+ printf("write() of %d bytes to %s at offset %d by pid %d\n",
+ record->w_nbytes, record->path, record->w_offset, record->w_pid);
+ }
+
+ return WLOG_CONTINUE_SCAN;
+}
+
+.fi
+.SH "SEE ALSO"
+pattern(3).
+.SH DIAGNOSTICS
+All routines return a value < 0 on failure, and >= 0 on success. Error
+messages can be accessed through Wlog_Error_String.
+.SH BUGS
+None known.