Namespaces
Variants
Views
Actions

Difference between revisions of "c/io/tmpnam"

From cppreference.com
< c‎ | io
m (Shorten template names. Use {{lc}} where appropriate.)
m (→‎Example: +POSIX `mkstemp` because users sometimes ask.)
 
(17 intermediate revisions by 9 users not shown)
Line 1: Line 1:
−
{{c/title | tmpnam}}
+
{{c/title|tmpnam|tmpnam_s}}
 
{{c/io/navbar}}
 
{{c/io/navbar}}
−
{{ddcl | header=stdio.h |
+
{{dcl begin}}
 +
{{dcl header|stdio.h}}
 +
{{dcl|num=1|
 
char *tmpnam( char *filename );
 
char *tmpnam( char *filename );
 
}}
 
}}
 +
{{dcl|num=2|since=c11|
 +
errno_t tmpnam_s(char *filename_s, rsize_t maxsize);
 +
}}
 +
{{dcl|
 +
#define TMP_MAX        /*unspecified*/
 +
}}
 +
{{dcl|since=c11|
 +
#define TMP_MAX_S      /*unspecified*/
 +
}}
 +
{{dcl|
 +
#define L_tmpnam      /*unspecified*/
 +
}}
 +
{{dcl|since=c11|
 +
#define L_tmpnam_s    /*unspecified*/
 +
}}
 +
 +
{{dcl end}}
 +
 +
@1@ Creates a unique valid file name (no longer than {{lc|L_tmpnam}} in length) and stores it in character string pointed to by {{c|filename}}. The function is capable of generating up to {{lc|TMP_MAX}} of unique filenames, but some or all of them may be in use in the filesystem and thus not suitable return values.
 +
 +
@2@ Same as {{v|1}}, except that up to {{lc|TMP_MAX_S}} names may be generated, no longer than {{lc|L_tmpnam_s}} in length, and the following errors are detected at runtime and call the currently installed [[c/error/set_constraint_handler_s|constraint handler]] function:
 +
:* {{c|filename_s}} is a null pointer
 +
:* {{c|maxsize}} is greater than {{c|RSIZE_MAX}}
 +
:* {{c|maxsize}} is less than the generated file name string
 +
: {{c/ext1 availability|tmpnam_s}}
  
−
Creates an unique filename and stores it in character string pointed to by {{tt|filename}}. The function is capable of generating up to {{rlpt|TMP_MAX}} of unique filenames, but some or all of them may be in use in the filesystem and thus not suitable return values.  
+
{{c|tmpnam}} and {{c|tmpnam_s}} modify static state (which may be shared between these functions) and are not required to be thread-safe.
  
 
===Parameters===
 
===Parameters===
 
{{par begin}}
 
{{par begin}}
−
{{par | filename | pointer to the character string to be used as a result buffer. If {{tt|NULL}} is passed, a pointer to an internal static buffer is returned.}}
+
{{par|filename|pointer to the character array capable of holding at least {{lc|L_tmpnam}} bytes, to be used as a result buffer. If null pointer is passed, a pointer to an internal static buffer is returned.}}
 +
{{par|filename_s|pointer to the character array capable of holding at least {{lc|L_tmpnam_s}} bytes, to be used as a result buffer.}}
 +
{{par|maxsize|maximum number of characters the function is allowed to write (typically the size of the {{tt|filename_s}} array).}}
 
{{par end}}
 
{{par end}}
  
 
===Return value===
 
===Return value===
−
{{tt|filename}} if {{tt|filename}} was not {{lc|NULL}}. Otherwise a pointer to an internal static buffer is returned. If no suitable filename can be generated, {{lc|NULL}} is returned.
+
@1@ {{c|filename}} if {{c|filename}} was not a null pointer. Otherwise a pointer to an internal static buffer is returned. If no suitable filename can be generated, null pointer is returned.
 +
@2@ Returns zero and writes the file name to {{c|filename_s}} on success. On error, returns non-zero and writes the null character to {{c|filename_s[0]}} (only if {{c|filename_s}} is not null and {{c|maxsize}} is not zero and is not greater than {{lc|RSIZE_MAX}}).
 +
 
 +
===Notes===
 +
Although the names generated by {{tt|tmpnam}} are difficult to guess, it is possible that a file with that name is created by another process between the moment {{tt|tmpnam}} returns and the moment this program attempts to use the returned name to create a file. The standard function {{lc|tmpfile}} and the POSIX function [https://pubs.opengroup.org/onlinepubs/9699919799/functions/mkdtemp.html {{tt|mkstemp}}] do not have this problem (creating a unique directory using only the standard C library still requires the use of {{tt|tmpnam}}).
 +
 
 +
POSIX systems additionally define the similarly named function [https://pubs.opengroup.org/onlinepubs/9699919799/functions/tempnam.html {{tt|tempnam}}], which offers the choice of a directory (which defaults to the optionally defined macro [https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/stdio.h.html {{tt|P_tmpdir}}]).
  
 
===Example===
 
===Example===
 
{{example
 
{{example
−
| code=#include <stdlib.h>
+
|code=
 
#include <stdio.h>
 
#include <stdio.h>
−
#include <stdint.h>
+
#include <stdlib.h>
−
#include <stdbool.h>
+
#include <string.h>
  
−
int main(int argc, char *argv[])
+
int main(void)
 
{
 
{
−
     printf("Welcome to %s\n", argv[0]);
+
     // Note, the compiler/linker may issue a security warning, e.g. GCC:
−
     printf("Called with %u arguments\n", argc - 1);
+
    // "warning: the use of `tmpnam' is dangerous, better use `mkstemp'"
 +
    char* name1 = tmpnam(NULL);
 +
     printf("temporary file name: %s\n", name1);
  
−
     char buffer[L_tmpnam] = {'\0'};
+
     char name2[L_tmpnam];
−
     tmpnam(buffer);
+
     if (tmpnam(name2))
−
    printf(buffer);
+
        printf("temporary file name: %s\n", name2);
−
    printf("\n");
+
  
−
     printf("Goodbye!\n");
+
     // POSIX offers mkstemp. The following declaration might be
−
     exit(EXIT_SUCCESS);
+
    // necessary as mkstemp is absent in the standard C <stdlib.h>.
 +
    int mkstemp(char*);
 +
 
 +
    char name3[] = "/tmp/fileXXXXXX"; // at least six 'X' required ^_^
 +
    int file_descriptor = mkstemp(name3);
 +
    if (file_descriptor != -1)
 +
        printf("temporary file name: %s\n", name3);
 +
     else
 +
        perror("mkstemp");
 
}
 
}
−
| output=Welcome to ./main_release
+
|p=true
−
Called with 0 arguments
+
|output=
−
/tmp/file6HADua
+
temporary file name: /tmp/file90dLlR
−
Goodbye!
+
temporary file name: /tmp/fileY9LWAg
 +
temporary file name: /tmp/filexgv8PF
 
}}
 
}}
 +
 +
===References===
 +
{{ref std c23}}
 +
{{ref std|section=7.21.4.4|title=The tmpnam function|p=TBD}}
 +
{{ref std|section=K.3.5.1.2|title=The tmpnam_s function|p=TBD}}
 +
{{ref std end}}
 +
{{ref std c17}}
 +
{{ref std|section=7.21.4.4|title=The tmpnam function|p=222}}
 +
{{ref std|section=K.3.5.1.2|title=The tmpnam_s function|p=427-428}}
 +
{{ref std end}}
 +
{{ref std c11}}
 +
{{ref std|section=7.21.4.4|title=The tmpnam function|p=303-304}}
 +
{{ref std|section=K.3.5.1.2|title=The tmpnam_s function|p=587-588}}
 +
{{ref std end}}
 +
{{ref std c99}}
 +
{{ref std|section=7.19.4.4|title=The tmpnam function|p=269-270}}
 +
{{ref std end}}
 +
{{ref std c89}}
 +
{{ref std|section=4.9.4.4|title=The tmpnam function}}
 +
{{ref std end}}
  
 
===See also===
 
===See also===
 
{{dsc begin}}
 
{{dsc begin}}
−
{{dsc inc | c/io/dcl list tmpfile}}
+
{{dsc inc|c/io/dsc tmpfile}}
−
{{dsc see cpp | cpp/io/c/tmpnam}}
+
{{dsc see cpp|cpp/io/c/tmpnam}}
 
{{dsc end}}
 
{{dsc end}}
  
−
[[de:c/io/tmpnam]]
+
{{langlinks|ar|cs|de|es|fr|it|ja|ko|pl|pt|ru|tr|zh}}
−
[[es:c/io/tmpnam]]
+
−
[[fr:c/io/tmpnam]]
+
−
[[it:c/io/tmpnam]]
+
−
[[ja:c/io/tmpnam]]
+
−
[[pt:c/io/tmpnam]]
+
−
[[ru:c/io/tmpnam]]
+
−
[[zh:c/io/tmpnam]]
+

Latest revision as of 07:47, 4 April 2023

 
C
 
File input/output
Types and objects
Functions
File access
Direct input/output
Unformatted input/output
(C95)(C95)
(C95)
(C95)(C95)
(C95)
(C95)
(C95)
(C95)
Formatted input
(C99)(C99)(C99)(C11)(C11)(C11)
(C99)(C99)(C99)(C11)(C11)(C11)     
Formatted output
File positioning
Error handling
Operations on files
(C11)
tmpnamtmpnam_s
(C11)
 
Defined in header <stdio.h>
char *tmpnam( char *filename );
 (1)
errno_t tmpnam_s(char *filename_s, rsize_t maxsize);
 (2) (since C11)
#define TMP_MAX        /*unspecified*/
#define TMP_MAX_S      /*unspecified*/
 (since C11)
#define L_tmpnam       /*unspecified*/
#define L_tmpnam_s     /*unspecified*/
 (since C11)
1) Creates a unique valid file name (no longer than L_tmpnam in length) and stores it in character string pointed to by filename. The function is capable of generating up to TMP_MAX of unique filenames, but some or all of them may be in use in the filesystem and thus not suitable return values.
2) Same as (1), except that up to TMP_MAX_S names may be generated, no longer than L_tmpnam_s in length, and the following errors are detected at runtime and call the currently installed constraint handler function:
  • filename_s is a null pointer
  • maxsize is greater than RSIZE_MAX
  • maxsize is less than the generated file name string
As with all bounds-checked functions, tmpnam_s is only guaranteed to be available if __STDC_LIB_EXT1__ is defined by the implementation and if the user defines __STDC_WANT_LIB_EXT1__ to the integer constant 1 before including <stdio.h>.

tmpnam and tmpnam_s modify static state (which may be shared between these functions) and are not required to be thread-safe.

Contents

[edit] Parameters

filename - pointer to the character array capable of holding at least L_tmpnam bytes, to be used as a result buffer. If null pointer is passed, a pointer to an internal static buffer is returned.
filename_s - pointer to the character array capable of holding at least L_tmpnam_s bytes, to be used as a result buffer.
maxsize - maximum number of characters the function is allowed to write (typically the size of the filename_s array).

[edit] Return value

1) filename if filename was not a null pointer. Otherwise a pointer to an internal static buffer is returned. If no suitable filename can be generated, null pointer is returned.
2) Returns zero and writes the file name to filename_s on success. On error, returns non-zero and writes the null character to filename_s[0] (only if filename_s is not null and maxsize is not zero and is not greater than RSIZE_MAX).

[edit] Notes

Although the names generated by tmpnam are difficult to guess, it is possible that a file with that name is created by another process between the moment tmpnam returns and the moment this program attempts to use the returned name to create a file. The standard function tmpfile and the POSIX function mkstemp do not have this problem (creating a unique directory using only the standard C library still requires the use of tmpnam).

POSIX systems additionally define the similarly named function tempnam, which offers the choice of a directory (which defaults to the optionally defined macro P_tmpdir).

[edit] Example

Run this code
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
 
int main(void)
{
    // Note, the compiler/linker may issue a security warning, e.g. GCC:
    // "warning: the use of `tmpnam' is dangerous, better use `mkstemp'"
    char* name1 = tmpnam(NULL);
    printf("temporary file name: %s\n", name1);
 
    char name2[L_tmpnam];
    if (tmpnam(name2))
        printf("temporary file name: %s\n", name2);
 
    // POSIX offers mkstemp. The following declaration might be
    // necessary as mkstemp is absent in the standard C <stdlib.h>.
    int mkstemp(char*);
 
    char name3[] = "/tmp/fileXXXXXX"; // at least six 'X' required ^_^
    int file_descriptor = mkstemp(name3);
    if (file_descriptor != -1)
        printf("temporary file name: %s\n", name3);
    else
        perror("mkstemp");
}

Possible output: 

temporary file name: /tmp/file90dLlR
temporary file name: /tmp/fileY9LWAg
temporary file name: /tmp/filexgv8PF

[edit] References

  • C23 standard (ISO/IEC 9899:2024):
  • 7.21.4.4 The tmpnam function (p: TBD)
  • K.3.5.1.2 The tmpnam_s function (p: TBD)
  • C17 standard (ISO/IEC 9899:2018):
  • 7.21.4.4 The tmpnam function (p: 222)
  • K.3.5.1.2 The tmpnam_s function (p: 427-428)
  • C11 standard (ISO/IEC 9899:2011):
  • 7.21.4.4 The tmpnam function (p: 303-304)
  • K.3.5.1.2 The tmpnam_s function (p: 587-588)
  • C99 standard (ISO/IEC 9899:1999):
  • 7.19.4.4 The tmpnam function (p: 269-270)
  • C89/C90 standard (ISO/IEC 9899:1990):
  • 4.9.4.4 The tmpnam function

[edit] See also

(C11)
 returns a pointer to a temporary file
(function) [edit]
C++ documentation for tmpnam
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=c/io/tmpnam&oldid=150073"