_mktemp, _wmktemp

Create a unique filename.

char*_mktemp(char*template);

wchar_t*_wmktemp(wchar_t*template);

Routine	Required Header	Compatibility
_mktemp	<io.h>	Win 95, Win NTv
_wmktemp	<io.h> or <wchar.h>	Win 95, Win NT

For additional compatibility information, see Compatibility in the Introduction.

Libraries

LIBC.LIB	Single thread static library, retail version
LIBCMT.LIB	Multithread static library, retail version
MSVCRT.LIB	Import library for MSVCRT.DLL, retail version

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.

Parameter

template

Filename pattern

Remarks

The _mktemp function creates a unique filename 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 & _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 filename 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 multi-threaded 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 filenames 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 will be

fnb12345

If FNA12345 does not exist, the next name returned will again be

fna12345

_mktemp can create a maximum of 27 unique filenames for any given combination of base and template values. Therefore, FNZ12345 is the last unique filename _mktemp can create for the base and template values used in this example.

Example

/* MKTEMP.C: The program uses _mktemp to create
 * five unique filenames. It opens each filename
 * to ensure that the next name is unique.
 */

#include <io.h>
#include <string.h>
#include <stdio.h>

char *template = "fnXXXXXX";
char *result;
char names[5][9];

void main( void )
{
   int i;
   FILE *fp;

   for( i = 0; i < 5; i++ )
   {
      strcpy( names[i], template );
      /* Attempt to find a unique filename: */
      result = _mktemp( names[i] );
      if( result == NULL )
         printf( "Problem creating the template" );
      else
      {
         if( (fp = fopen( result, "w" )) != NULL )
            printf( "Unique filename is %s\n", result );
         else
            printf( "Cannot open %s\n", result );
         fclose( fp );
      }
   }
}

Output

Unique filename is fna00141
Unique filename is fnb00141
Unique filename is fnc00141
Unique filename is fnd00141
Unique filename is fne00141

File Handling Routines

See Also   fopen, _getmbcp, _getpid, _open, _setmbcp, _tempnam, tmpfile