.\"
.\" $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.,
.\" 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 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 SIGCHLD 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_resm()\fR.
.SH "SEE ALSO"
fork(2), system(3S), tst_res(3), tmpnam(3S).