|< C Run-Time 1 | Main | C Run-Time 3 >| Site Index | Download |

MODULE A1

IMPLEMENTATION SPECIFIC

MICROSOFT C Run-Time Win32 2

What are in this Module?

1. System Calls

2. System Call Functions

3. File Handling

4. File-Handling Functions (Files)

5. File-Handling Functions (Path or Filename)

6. Program examples

System Call Functions

• For example, the _findfirst() function provides information about the first instance of a filename that matches the file specified in the filespec argument.
• Any wildcard combination supported by the host operating system such as the *, can be used in filespec.  File information is returned in a _finddata_t (or _finddata64_t) structure, defined in io.h.
• The _finddata_t structure used in these functions includes the following elements:

• The time_create and time_access fields are always –1L for file systems that do not support the creation and last access times of a file, such as the FAT system.
• You cannot specify target attributes (such as _A_RDONLY) by which to limit the find operation.  This attribute is returned in the attrib field of the _finddata_t structure and can have the following values (defined in io.h).

• _findnext() finds the next name, if any, that matches the filespec argument specified in a prior call to _findfirst().  The fileinfo argument should point to a structure initialized by a previous call to _findfirst().
• If a match is found, the fileinfo structure contents are altered as described above.  _findclose() closes the specified search handle and releases all associated resources for both _findfirst() and _findnext().  The handle returned by either _findfirst() or _findnext() must first be passed to _findclose(), before modification operations, such as deleting, can be performed on the directories that form the paths passed to them.
• The _find() functions allow nested calls.  For example, if the file found by a call to _findfirst() or _findnext() is a subdirectory, a new search can be initiated with another call to _findfirst() or _findnext().
• _wfindfirst() and _wfindnext() are wide-character versions of _findfirst() and _findnext().
• The structure argument of the wide-character versions has the _wfinddata_t data type, which is defined in io.h and in wcahr.h.  The fields of this data type are the same as those of the _finddata_t data type, except that in _wfinddata_t the name field is of type wchar_t rather than type char.
• Otherwise _wfindfirst() and _wfindnext() behave identically to _findfirst() and _findnext().  _findfirsti64(), _findnexti64(), _wfindfirsti64(), and _wfindnexti64() functions also behave identically except they use and return 64-bit file lengths.
• The following is an example of the needed information in order to use the  _findclose() function.

• The following Table lists the needed information in order to use the  _findfirst() family functions.

intptr_t _findfirst(    const char *filespec, struct _finddata_t *fileinfo );

intptr_t _findfirst64( const char *filespec, struct __finddata64_t *fileinfo );

intptr_t _findfirsti64( const char *filespec, struct _finddatai64_t *fileinfo );

intptr_t _wfindfirst( const wchar_t *filespec, struct _wfinddata_t *fileinfo );

intptr_t _wfindfirst64( const wchar_t *filespec, struct __wfinddata64_t *fileinfo );

intptr_t _wfindfirsti64(const wchar_t *filespec, struct _wfinddatai64_t *fileinfo );

• _findfirst64(), which uses the __finddata64_t() structure, and _wfindfirst64(), which use the __wfinddata64_t structure, allows file-creation dates to be expressed up through 23:59:59, December 31, 3000, UTC.
• Whereas the other functions only represent dates through 19:14:07 January 18, 2038, UTC.  Midnight, January 1, 1970, is the lower bound of the date range for all these functions.
• You must call _findclose() after you are finished using either the _findfirst() or _findnext() function.  This will free up resources used by these functions in your application.
• The following Table lists the needed information in order to use the  _findnext() family functions.

int _findnext( intptr_t handle, struct _finddata_t *fileinfo );

int _findnext64( intptr_t handle, struct __finddata64_t *fileinfo );

int _findnexti64( intptr_t handle, struct _finddatai64_t *fileinfo );

int _wfindnext( intptr_t handle, struct _wfinddata_t *fileinfo );

int _wfindnext64( intptr_t handle, struct __wfinddata64_t *fileinfo );

int _wfindnexti64( intptr_t handle, struct _wfinddatai64_t *fileinfo );

• _findnext64(), which uses the __finddata64_t structure, and _wfindnext64(), which use the __wfinddata64_t structure, allow file-creation dates to be expressed up through 23:59:59, December 31, 3000, UTC.
• Whereas the other functions only represent dates through 19:14:07 January 18, 2038, UTC. Midnight, January 1, 1970, is the lower bound of the date range for all these functions.
• The following is a program example that uses some of the functions.

/* the use of the 32-bit _find() functions to print a list of all files (and their attributes) in the current directory. */

#include <stdio.h>

#include <io.h>

#include <time.h>

#include <direct.h>

#include <conio.h>

#include <ctype.h>

int main()

{

// for XP, char path[50] = "C:\\Windows\\System32\\config";

char   path[50] = "C:\\WINNT\\System32\\config";

struct _finddata_t c_file;

long   hFile;

printf("Change to %s\n", path);

if(_chdir(path))

printf("Unable to locate the directory: %s\n", path);

else

/* find first in the current directory */

/* hFile = (long) _findfirst("*.*", &c_file); */

hFile = _findfirst("*.*", &c_file);

/* list the files... */

printf("Listing of files in the directory %s\n\n", path);

printf("\nRDO HID SYS ARC  FILE         DATE %25c SIZE\n", ' ');

printf("--- --- --- ---  ----         ---- %25c ----\n", ' ');

printf((c_file.attrib & _A_RDONLY) ? " Y  " : " N  ");

printf((c_file.attrib & _A_SYSTEM) ? " Y  " : " N  ");

printf((c_file.attrib & _A_HIDDEN) ? " Y  " : " N  ");

printf((c_file.attrib & _A_ARCH)   ? " Y  " : " N  ");

printf(" %-12s %.24s  %9ld\n", c_file.name, ctime(&(c_file.time_write)), c_file.size);

/* find the rest of the files */

while(_findnext(hFile, &c_file) == 0)

{

  printf((c_file.attrib & _A_RDONLY) ? " Y  " : " N  ");

  printf((c_file.attrib & _A_SYSTEM) ? " Y  " : " N  ");

  printf((c_file.attrib & _A_HIDDEN) ? " Y  " : " N  ");

  printf((c_file.attrib & _A_ARCH)   ? " Y  " : " N  ");

  printf(" %-12s %.24s  %9ld\n", c_file.name, ctime(&(c_file.time_write)), c_file.size);

}

_findclose(hFile);

return 0;

}

The output sample:

• The following is output sample tested on Win XP Pro SP2 using Visual C++ Express Edition 2005 with Windows SDK installed.

File Handling

• The functions in this category used to create, delete, and manipulate files and to set and check file-access permissions.
• The C run-time libraries have a 512 limit for the number of files that can be open at any one time.
• Attempting to open more than the maximum number of file handles or file streams causes program failure.  But you can use _setmaxstdio() function to change this number.

File-Handling Functions (Files)

• The following functions operate on files designated by a file handle.  Handle will be explained in C & Win32 programming.

• The following Table is an example of the needed information in order to use the _chsize() function.

#include <io.h>

#include <fcntl.h>

#include <sys/types.h>

#include <sys/stat.h>

#include <stdio.h>

int main()

{

   int fhdl, result;

   char fname[20] = "C:\\data.txt";

   /* open a file */

   if((fhdl = _open(fname, _O_RDWR | _O_CREAT, _S_IREAD | _S_IWRITE)) != -1)

   {

      printf("%s file length before running _chsize(): %ld\n", fname, _filelength(fhdl));

      /* change the file size */

      printf("Executing _chsize(fhdl, 123456)...\n");

      if((result = _chsize(fhdl, 123456)) == 0)

         printf("%s file size successfully changed!\n", fname);

      else

         printf("Problem in changing the %s size\n", fname);

         /* new size */

         printf("%s file length after changing the size: %ld\n", fname, _filelength(fhdl));

       /* close the file handle */

      _close(fhdl);

   }

   return 0;

}

The output sample:

• Another example run on VC++ 2005 with SDK installed.

#include <io.h>

#include <fcntl.h>

#include <sys/types.h>

#include <sys/stat.h>

#include <share.h> // _SH_DENYNO

#include <stdio.h>

#include <windows.h> // GetLastError()

 

int main()

{

    int fhdl, result;

    /* make sure this file is there, else change accordingly */

    char fname[20] = "C:\\data.txt";

 

    /* open a file */

    if(_sopen_s( &fhdl, fname, _O_RDWR, _SH_DENYNO, _S_IREAD | _S_IWRITE ) == 0)

    {

        printf("%s file length before running _chsize(): %ld\n", fname, _filelength(fhdl));

        /* change the file size */

        printf("Executing _chsize(fhdl, 123456)...\n");

        if((result = _chsize(fhdl, 123456)) == 0)

            printf("%s file size successfully changed!\n", fname);

        else

            printf("Problem in changing the %s size. Error %d\n", fname, GetLastError());

        /* new size */

        printf("%s file length after changing the size: %ld\n", fname, _filelength(fhdl));

        /* close the file handle */

        _close(fhdl);

    }

    return 0;

}

 

A sample output:

File-Handling Functions (Path or Filename)

• The following Table is a list of functions that operate on files specified by a path or filename.

• The following Table is an example of the needed information for _chmod() function.

• The following Table lists the needed information for _fullpath(), _wfullpath() functions.

• The _fullpath() function expands the relative path name in relPath to its fully qualified or "absolute" path, and stores this name in absPath.
• A relative path name specifies a path to another location from the current location (such as the current working directory, ".").
• An absolute path name is the expansion of a relative path name that states the entire path required to reach the desired location from the root of the filesystem.
• Unlike _makepath(), _fullpath() can be used to obtain the absolute path name for relative paths (relPath) that include "./" or "../" in their names.
• For example, to use C run-time routines, the application or program must include the header files that contain the declarations for the routines.
• Each header file include statement references the location of the file in a relative manner (from the application's working directory):

#include <stdlib.h>

• When the absolute path (actual file system location) of the file may be:

\\machine\shareName\msvcSrc\crt\headerFiles\stdlib.h

• _fullpath() automatically handles multibyte-character string arguments as appropriate, recognizing multibyte-character sequences according to the multibyte code page currently in use.

• _wfullpath() is a wide-character version of _fullpath().  The string arguments to _wfullpath() are wide-character strings.

• _wfullpath() and _fullpath() behave identically except that _wfullpath() does not handle multibyte-character strings.

• If the absPath buffer is NULL, _fullpath() calls malloc() to allocate a buffer of size _MAX_PATH and ignores the maxLength argument.

• It is the caller's responsibility to de-allocate this buffer (using free) as appropriate.  If the relPath argument specifies a disk drive, the current directory of this drive is combined with the path.

• The following is a simple program example using the _fullpath() function.

#include <stdio.h>

#include <conio.h>

#include <stdlib.h>

#include <direct.h>

void DisplayFullPath(char *relPath)

{

   /* a buffer */

   char full[_MAX_PATH];

   if(_fullpath(full, relPath, _MAX_PATH) != NULL)

      printf("The full path is: %s\n", full);

   else

      printf("Invalid path\n");

}

int main()

{

   // you need to create those files at those locations else

   // change accordingly

   DisplayFullPath("test.txt");

   DisplayFullPath("\\test.txt");

   DisplayFullPath("..\\test.txt");

   return 0;

}

The output sample:

The full path is: g:\vcnetprojek\win32prog\test.txt

The full path is: g:\test.txt

The full path is: g:\vcnetprojek\test.txt

Press any key to continue

• The following is a sample output run using VC++ Express Edition 2005.

• The following Table lists the needed information for _splitpath(), _wsplitpath() functions.

void _splitpath( const char *path, char *drive, char *dir, char *fname, char *ext);

void _wsplitpath( const wchar_t *path, wchar_t *drive, wchar_t *dir, wchar_t *fname, wchar_t *ext);

• The _splitpath() function breaks a path into its four components.  _splitpath() automatically handles multibyte-character string arguments as appropriate, recognizing multibyte-character sequences according to the multibyte code page currently in use.
• _wsplitpath() is a wide-character version of _splitpath().  The arguments to _wsplitpath() are wide-character strings.

• Each argument is stored in a buffer; the manifest constants _MAX_DRIVE, _MAX_DIR, _MAX_FNAME, and _MAX_EXT (defined in stdlib.h) specify the maximum size necessary for each buffer.

• The other arguments point to buffers used to store the path elements.  After a call to _splitpath() is executed, these arguments contain empty strings for components not found in path.  You can pass a NULL pointer to _splitpath() for any component you don't need.

• The following Table lists the needed information for _makepath(), _wmakepath() functions.

• The _makepath() function creates a single path and stores it in path.  The path may include a drive letter, directory path, filename, and filename extension.
• _wmakepath() is a wide-character version of _makepath().  The arguments to _wmakepath() are wide-character strings.  _wmakepath() and _makepath() behave identically otherwise.
• The path argument must point to an empty buffer large enough to hold the complete path.  Although there are no size limits on any of the fields that constitute path, the composite path must be no larger than the _MAX_PATH constant, defined in stdlib.h.
• _MAX_PATH may be larger than the current operating-system version will handle.
• The following arguments point to buffers containing the path elements:

1. drive - Contains a letter (A, B, and so on) corresponding to the desired drive and an optional trailing colon. _makepath() inserts the colon automatically in the composite path if it is missing.  If drive is a null character or an empty string, no drive letter and colon appear in the composite path string.

2. dir - Contains the path of directories, not including the drive designator or the actual filename.  The trailing slash is optional, and either a forward slash (/) or a backslash (\) or both may be used in a single dir argument.  If a trailing slash (/ or \) is not specified, it is inserted automatically.  If dir is a null character or an empty string, no slash is inserted in the composite path string.

3. fname - Contains the base filename without any extensions.  If fname is NULL or points to an empty string, no filename is inserted in the composite path string.

4. ext - Contains the actual filename extension, with or without a leading period (.).  _makepath() inserts the period automatically if it does not appear in ext.  If ext is a null character or an empty string, no period is inserted in the composite path string.

#include <stdlib.h>

#include <stdio.h>

int main()

{

   char path_buffer[_MAX_PATH];

   char drive[_MAX_DRIVE];

   char dir[_MAX_DIR];

   char fname[_MAX_FNAME];

   char ext[_MAX_EXT];

    // change the path accordingly to yours

   _makepath(path_buffer, "g", "\\Testdir\\myexample\\", "testfile", "txt");

   printf("Path created with _makepath(): %s\n", path_buffer);

   _splitpath(path_buffer, drive, dir, fname, ext);

   printf("Path extracted with _splitpath():\n");

   printf("  Drive: %s\n", drive);

   printf("  Dir: %s\n", dir);

   printf("  Filename: %s\n", fname);

   printf("  Ext: %s\n", ext);

   return 0;

}

The output sample:

The full path is: g:\vcnetprojek\win32prog\test.txt

The full path is: g:\test.txt

The full path is: g:\vcnetprojek\test.txt

Press any key to continue

Further reading and digging:

1. Check the best selling C, C++ and Windows books at Amazon.com.
2. Microsoft Visual C++, online MSDN.
3. For Multibytes, Unicode characters and Localization please refer to Locale, Wide Character & Unicode (Story) and Windows Users & Groups tutorial (Implementation).
4. Notation used in MSDN is Hungarian Notation instead of CamelCase and is discussed in C & C++ Notations.

|< C Run-Time 1 | Main | C Run-Time 3 >| Site Index | Download |

Some Old Part of the C-Run Time: Part 1 | Part 2 | Part 3 | Part 4

C & C++ Programming Tutorial | C Programming Practice