usr/src/man/man3c/tmpnam.3c

   1 '\" te
   2 .\" Copyright 1989 AT&T.  Copyright (c) 2004, Sun Microsystems, Inc.  All Rights Reserved.
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH TMPNAM 3C "May 18, 2004"
   7 .SH NAME
   8 tmpnam, tmpnam_r, tempnam \- create a name for a temporary file
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <stdio.h>
  13
  14 \fBchar *\fR\fBtmpnam\fR(\fBchar *\fR\fIs\fR);
  15 .fi
  16
  17 .LP
  18 .nf
  19 \fBchar *\fR\fBtmpnam_r\fR(\fBchar *\fR\fIs\fR);
  20 .fi
  21
  22 .LP
  23 .nf
  24 \fBchar *\fR\fBtempnam\fR(\fBconst char *\fR\fIdir\fR, \fBconst char *\fR\fIpfx\fR);
  25 .fi
  26
  27 .SH DESCRIPTION
  28 .sp
  29 .LP
  30 These functions generate file names that can be used safely for a temporary
  31 file.
  32 .SS "\fBtmpnam()\fR"
  33 .sp
  34 .LP
  35 The \fBtmpnam()\fR function always generates a file name using the path prefix
  36 defined as \fBP_tmpdir\fR in the <\fBstdio.h\fR> header. On Solaris systems,
  37 the default value for \fBP_tmpdir\fR is  \fB/var/tmp\fR. If \fIs\fR is
  38 \fINULL\fR, \fBtmpnam()\fR leaves its result in a thread-specific data area and
  39 returns a pointer to that area. The next call to \fBtmpnam()\fR by the same
  40 thread will destroy the contents of the area. If \fIs\fR is not \fINULL\fR, it
  41 is assumed to be the address of an array of at least \fBL_tmpnam\fR bytes,
  42 where \fBL_tmpnam\fR is a constant defined through inclusion of
  43 <\fBstdio.h\fR>. The \fB tmpnam()\fR function places its result in that array
  44 and returns \fIs\fR.
  45 .SS "\fBtmpnam_r()\fR"
  46 .sp
  47 .LP
  48 The \fBtmpnam_r()\fR function has the same functionality as \fBtmpnam()\fR
  49 except that if \fIs\fR is a null pointer, the function returns \fINULL\fR.
  50 .SS "\fBtempnam()\fR"
  51 .sp
  52 .LP
  53 The \fBtempnam()\fR function allows the user to control the choice of a
  54 directory. The argument \fIdir\fR points to the name of the directory in which
  55 the file is to be created. If \fIdir\fR is \fINULL\fR or points to a string
  56 that is not a name for an appropriate directory, the path prefix defined as
  57 \fBP_tmpdir\fR in the <\fBstdio.h\fR> header is used. If that directory is not
  58 accessible, \fB/tmp\fR is used. If, however, the \fBTMPDIR\fR environment
  59 variable is set in the user's environment, its value is used as the
  60 temporary-file directory.
  61 .sp
  62 .LP
  63 Many applications prefer that temporary files have certain initial character
  64 sequences in their names. The \fIpfx\fR argument may be \fINULL\fR or point to
  65 a string of up to five characters to be used as the initial characters of the
  66 temporary-file name.
  67 .sp
  68 .LP
  69 Upon successful completion, \fBtempnam()\fR uses \fBmalloc\fR(3C) to allocate
  70 space for a string, puts the generated pathname in that space, and returns a
  71 pointer to it. The pointer is suitable for use in a subsequent call to
  72 \fBfree()\fR. If \fBtempnam()\fR cannot return the expected result for any
  73 reason (for example, \fBmalloc()\fR failed), or if none of the above-mentioned
  74 attempts to find an appropriate directory was successful, a null pointer is
  75 returned and \fBerrno\fR is set to indicate the error.
  76 .SH ERRORS
  77 .sp
  78 .LP
  79 The \fBtempnam()\fR function will fail if:
  80 .sp
  81 .ne 2
  82 .na
  83 \fB\fBENOMEM\fR\fR
  84 .ad
  85 .RS 10n
  86 Insufficient storage space is available.
  87 .RE
  88
  89 .SH USAGE
  90 .sp
  91 .LP
  92 These functions generate a different file name each time they are called.
  93 .sp
  94 .LP
  95 Files created using these functions and either \fBfopen\fR(3C) or
  96 \fBcreat\fR(2) are temporary only in the sense that they reside in a directory
  97 intended for temporary use, and their names are unique. It is the user's
  98 responsibility to remove the file when its use is ended.
  99 .sp
 100 .LP
 101 If called more than \fBTMP_MAX\fR (defined in <\fBstdio.h\fR>) times in a
 102 single process, these functions start recycling previously used names.
 103 .sp
 104 .LP
 105 Between the time a file name is created and the file is opened, it is possible
 106 for some other process to create a file with the same name. This can never
 107 happen if that other process is using these functions or \fBmktemp\fR(3C) and
 108 the file names are chosen to render duplication by other means unlikely.
 109 .sp
 110 .LP
 111 The \fBtmpnam()\fR function is safe to use in multithreaded applications
 112 because it employs thread-specific data if it is passed a NULL pointer.
 113 However, its use is discouraged. The \fBtempnam()\fR function is safe in
 114 multithreaded applications and should be used instead.
 115 .sp
 116 .LP
 117 When compiling multithreaded applications, the  \fB_REENTRANT\fR flag must be
 118 defined on the compile line.  This flag should be used only with multithreaded
 119 applications.
 120 .SH ATTRIBUTES
 121 .sp
 122 .LP
 123 See \fBattributes\fR(5) for descriptions of the following attributes:
 124 .sp
 125
 126 .sp
 127 .TS
 128 box;
 129 c | c
 130 l | l .
 131 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 132 _
 133 Interface Stability     \fBtmpnam()\fR and \fBtempnam()\fR are Standard.
 134 _
 135 MT-Level        Safe
 136 .TE
 137
 138 .SH SEE ALSO
 139 .sp
 140 .LP
 141 \fBcreat\fR(2), \fBunlink\fR(2), \fBfopen\fR(3C), \fBfree\fR(3C),
 142 \fBmalloc\fR(3C), \fBmktemp\fR(3C), \fBmkstemp\fR(3C), \fBtmpfile\fR(3C),
 143 \fBattributes\fR(5), \fBstandards\fR(5)