_mktemp, _wmktemp
Creates a unique file name. More secure versions of these functions are available; see _mktemp_s, _wmktemp_s.
char *_mktemp(
char *template
);
wchar_t *_wmktemp(
wchar_t *template
);
template <size_t size>
char *_mktemp(
char (&template)[size]
); // C++ only
template <size_t size>
wchar_t *_wmktemp(
wchar_t (&template)[size]
); // C++ only
Parameters
- template
File name pattern.
Return Value
Each of these functions returns a pointer to the modified template. The function returns NULL if template is badly formed or no more unique names can be created from the given template.
Remarks
The _mktemp function creates a unique file name by modifying the template argument. _mktemp automatically handles multibyte-character string arguments as appropriate, recognizing multibyte-character sequences according to the multibyte code page currently in use by the run-time system. _wmktemp is a wide-character version of _mktemp; the argument and return value of _wmktemp are wide-character strings. _wmktemp and _mktemp behave identically otherwise, except that _wmktemp does not handle multibyte-character strings.
Generic-Text Routine Mappings
Tchar.h routine |
_UNICODE and _MBCS not defined |
_MBCS defined |
_UNICODE defined |
|---|---|---|---|
_tmktemp |
_mktemp |
_mktemp |
_wmktemp |
The template argument has the form baseXXXXXX, where base is the part of the new file name that you supply and each X is a placeholder for a character supplied by _mktemp. Each placeholder character in template must be an uppercase X. _mktemp preserves base and replaces the first trailing X with an alphabetic character. _mktemp replaces the following trailing X's with a five-digit value; this value is a unique number identifying the calling process, or in multithreaded programs, the calling thread.
Each successful call to _mktemp modifies template. In each subsequent call from the same process or thread with the same template argument, _mktemp checks for file names that match names returned by _mktemp in previous calls. If no file exists for a given name, _mktemp returns that name. If files exist for all previously returned names, _mktemp creates a new name by replacing the alphabetic character it used in the previously returned name with the next available lowercase letter, in order, from 'a' through 'z'. For example, if base is:
fn
and the five-digit value supplied by _mktemp is 12345, the first name returned is:
fna12345
If this name is used to create file FNA12345 and this file still exists, the next name returned on a call from the same process or thread with the same base for template is:
fnb12345
If FNA12345 does not exist, the next name returned is again:
fna12345
_mktemp can create a maximum of 26 unique file names for any given combination of base and template values. Therefore, FNZ12345 is the last unique file name _mktemp can create for the base and template values used in this example.
On failure, errno is set. If template has an invalid format (for example, fewer than 6 X's), errno is set to EINVAL. If _mktemp is unable to create a unique name because all 26 possible file names already exist, _mktemp sets template to an empty string and returns EEXIST.
In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see Secure Template Overloads.
Requirements
Routine |
Required header |
|---|---|
_mktemp |
<io.h> |
_wmktemp |
<io.h> or <wchar.h> |
For more compatibility information, see Compatibility in the Introduction.
Example
// crt_mktemp.c
// compile with: /W3
/* The program uses _mktemp to create
* unique filenames. It opens each filename
* to ensure that the next name is unique.
*/
#include <io.h>
#include <string.h>
#include <stdio.h>
#include <errno.h>
char *template = "fnXXXXXX";
char *result;
char names[27][9];
int main( void )
{
int i;
FILE *fp;
for( i = 0; i < 27; i++ )
{
strcpy_s( names[i], sizeof( names[i] ), template );
/* Attempt to find a unique filename: */
result = _mktemp( names[i] ); // C4996
// Note: _mktemp is deprecated; consider using _mktemp_s instead
if( result == NULL )
{
printf( "Problem creating the template\n" );
if (errno == EINVAL)
{
printf( "Bad parameter\n");
}
else if (errno == EEXIST)
{
printf( "Out of unique filenames\n");
}
}
else
{
fopen_s( &fp, result, "w" );
if( fp != NULL )
printf( "Unique filename is %s\n", result );
else
printf( "Cannot open %s\n", result );
fclose( fp );
}
}
}
Unique filename is fna03912 Unique filename is fnb03912 Unique filename is fnc03912 Unique filename is fnd03912 Unique filename is fne03912 Unique filename is fnf03912 Unique filename is fng03912 Unique filename is fnh03912 Unique filename is fni03912 Unique filename is fnj03912 Unique filename is fnk03912 Unique filename is fnl03912 Unique filename is fnm03912 Unique filename is fnn03912 Unique filename is fno03912 Unique filename is fnp03912 Unique filename is fnq03912 Unique filename is fnr03912 Unique filename is fns03912 Unique filename is fnt03912 Unique filename is fnu03912 Unique filename is fnv03912 Unique filename is fnw03912 Unique filename is fnx03912 Unique filename is fny03912 Unique filename is fnz03912 Problem creating the template. Out of unique filenames.
.NET Framework Equivalent
Not applicable. To call the standard C function, use PInvoke. For more information, see Platform Invoke Examples.