=======
  DIR.H
 =======
 Functions
 =========
  chdir     
  findfirst 
  findnext  
  fnmerge   
  fnsplit   
  getcurdir 
  getcwd    
  getdisk   
  mkdir     
  mktemp    
  rmdir     
  searchpath
  setdisk   

 Constants, data types, and global variables
 ===========================================
  DIRECTORY 
  DRIVE     
  EXTENSIONS
  ffblk     
  FILENAME  
  MAXDIR    
  MAXDRIVE  
  MAXEXT    
  MAXFILE   
  MAXPATH   

 See Also
 ========
  List of all Header files


========== DIRECT.H ========== Functions ========= _chdrive _getdcwd _getdrive
========== DIRENT.H ========== Functions ========= closedir opendir readdir rewinddir
Bit Definitions for fnsplit <DIR.H> ============================= Bit definitions returned from fnsplit to identify which pieces of a file name were found during the split. Flag | Component ------------+---------------------------------------------------------- DIRECTORY | Path includes a directory (and possibly subdirectories) DRIVE | Path includes a drive specification (see dir.h) EXTENSION | Path includes an extension FILENAME | Path includes a file name WILDCARDS | Path contains wildcards (* or ?)
MAXxxxx <DIR.H> ========= These symbols define the maximum number of characters in a file specification for fnsplit (including room for a terminating NULL). Name | Meaning ----------+--------------------------------- MAXPATH | Complete file name with path MAXDRIVE | Disk drive (e.g., "A:") MAXDIR | File subdirectory specification MAXFILE | File name without extension MAXEXT | File extension
ffblk <DIR.H> ======= DOS file control block structure. struct ffblk { char ff_reserved[21]; /* reserved by DOS */ char ff_attrib; /* attribute found */ int ff_ftime; /* file time */ int ff_fdate; /* file date */ long ff_fsize; /* file size */ char ff_name[13]; /* found file name */ }; Remarks: ff_ftime and ff_fdate are 16-bit structures divided into bit fields for referring to the current date and time. ff_ftime |15.....11|10........5|4.......0| ======== |-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-| +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Hours Minutes Seconds/2 ff_fdate |15..........9|8.....5|4.......0| ======== |-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-| +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Years since Month Day 1980 The structure of these fields was established by DOS. See Also: findfirst ftime structure find_t structure
======= chdir <DIR.H> ======= Changes current directory Declaration: int chdir(const char *path); Remarks: chdir causes the directory specified by path to become the current working directory. path must specify an existing directory. You can also specify a drive in the path argument, such as chdir("a:\BC") but this changes only the current directory on that drive; it doesn't change the active drive. Return Value: * On success, returns 0. * Otherwise, returns -1 and sets errno to ENOENT (path or file name not found). Portability: + DOS + UNIX + Windows + ANSI C + C++ Only + | Yes | Yes | Yes | | | +-----+------+---------+--------+----------+ See Also: getcurdir getcwd mkdir rmdir system Example: #include <stdio.h> #include <stdlib.h> #include <dir.h> char old_dir[MAXDIR]; char new_dir[MAXDIR]; int main(void) { if (getcurdir(0, old_dir)) { perror("getcurdir()"); exit(1); } printf("Current directory is: \\%s\n", old_dir); if (chdir("\\")) { perror("chdir()"); exit(1); } if (getcurdir(0, new_dir)) { perror("getcurdir()"); exit(1); } printf("Current directory is now: \\%s\n", new_dir); printf("\nChanging back to original directory: \\%s\n", old_dir); if (chdir(old_dir)) { perror("chdir()"); exit(1); } return 0; }
=========== getcurdir <DIR.H> =========== Gets current directory for specified drive. Declaration: int getcurdir(int drive, char *directory); Remarks: getcurdir gets the name of the current working directory for the drive indicated by drive. Argument | What It Is/Does -----------+------------------------------------------------------------- drive | Specifies a drive number (0 = default, 1 = A, etc.) directory | Points to an area of memory (of length MAXDIR) where the | null-terminated directory name will be placed. The name | does not contain the drive specification and does not begin | with a backslash. Return Value * On success, returns 0 * On error, returns -1 Portability: + DOS + UNIX + Windows + ANSI C + C++ Only + | Yes | | Yes | | | +-----+------+---------+--------+----------+ See Also: chdir getcwd getdisk mkdir rmdir Example: #include <dir.h> #include <stdio.h> #include <string.h> char *current_directory(char *path) { strcpy(path, "X:\\"); /* fill string with form of response: X:\ */ path[0] = 'A' + getdisk(); /* replace X with current drive letter */ getcurdir(0, path+3); /* fill rest of string with current directory */ return(path); } int main(void) { char curdir[MAXPATH]; current_directory(curdir); printf("The current directory is %s\n", curdir); return 0; }
============== mkdir, rmdir <DIR.H> ============== * mkdir creates a directory * rmdir removes a DOS file directory Declaration: * int mkdir(const char *path); * int rmdir(const char *path); Remarks: * mkdir creates a new directory from the given path. * rmdir deletes the directory whose path is given by path. The directory named by path * must be empty * must not be the current working directory * must not be the root directory Return Value: * On success, * mkdir returns 0 if the new directory was created * rmdir returns 0 if the directory was successfully deleted * On error, mkdir and rmdir return -1 and set errno to one of the following: EACCES Permission denied ENOENT Path or file function not found Portability: + DOS + UNIX + Windows + ANSI C + C++ Only + | Yes | Yes | Yes | | | +-----+------+---------+--------+----------+ See Also: chdir getcurdir getcwd Example (for both functions): #include <stdio.h> #include <conio.h> #include <process.h> #include <dir.h> #define DIRNAME "testdir.$$$" int main(void) { int stat; stat = mkdir(DIRNAME); if (!stat) printf("Directory created\n"); else { printf("Unable to create directory\n"); exit(1); } getch(); system("dir/p"); getch(); stat = rmdir(DIRNAME); if (!stat) printf("\nDirectory deleted\n"); else { perror("\nUnable to delete directory\n"); exit(1); } return 0; }
======== mktemp <DIR.H> ======== Makes a unique file name Declaration: char *mktemp(char *template); Remarks: mktemp replaces the string *template with a unique file name and returns template. template should be a null-terminated string with six trailing Xs. The Xs are replaced with a unique collection of letters plus a period, so that the new file name consists of two letters, a period, and three suffix letters. Starting with AA.AAA, mktemp assigns the new file name by looking up that name on the disk and avoiding pre-existing names of the same format. Return Value: * On success (if template is well-formed), returns the address of the template string * Otherwise, returns null. Portability: + DOS + UNIX + Windows + ANSI C + C++ Only + | Yes | Yes | Yes | | | +-----+------+---------+--------+----------+ Example: #include <dir.h> #include <stdio.h> int main(void) { /* fname defines the template for the temporary file. */ char *fname = "TXXXXXX", *ptr; ptr = mktemp(fname); printf("%s\n",ptr); return 0; }
============ searchpath <DIR.H> ============ Searches the DOS path for a file Declaration: char *searchpath(const char *file); Remarks: searchpath attempts to locate the file *file. It searches along the DOS path (the PATH=... string in the environment). searchpath first searches for the file in the current directory of the current drive. If the file is not found there, it fetches the PATH environment variable, and searches each directory in the path in turn until it finds the file, or exhausts the path. When searchpath locates the file, it returns a string containing the full path name. This string can be used in a call to access the file (for example, with fopen or an exec... function). Return Value: * On success (if the file is successfully located), returns a pointer to a file- name string. * Otherwise, returns null. The file-name string is located in a static buffer that is overwritten on each subsequent call to searchpath. Portability: + DOS + UNIX + Windows + ANSI C + C++ Only + | Yes | | Yes | | | +-----+------+---------+--------+----------+ See Also: exec... findfirst findnext spawn... system Example: #include <stdio.h> #include <dir.h> int main(void) { char *p; /* Looks for TLINK and returns a pointer to the path */ p = searchpath("TLINK.EXE"); printf("Search for TLINK.EXE : %s\n", p); /* Looks for non-existent file */ p = searchpath("NOTEXIST.FIL"); printf("Search for NOTEXIST.FIL : %s\n", p); return 0; }
========== _getdcwd <DIRECT.H> getcwd <DIR.H> ========== * _getdcwd gets the current directory for specified drive * getcwd gets the current working directory Declaration: * char *_getdcwd(int drive, char *buffer, int buflen); * char *getcwd(char *buf, int buflen); Remarks: Both functions get the full path name of a working directory and store it in a buffer. * getcwd gets the current working directory * _getdcwd gets a specified drive's working directory. Argument| What It Is/Does --------+--------------------------------------------------------- buf | Buffer where getcwd stores the full path name buffer | Buffer where _getdcwd stores the full path name buflen | Size of the buffer where the full path name is stored drive | Specified drive; 0 = default drive, 1 = A, 2 = B, etc. If the full path name length (including the null terminator) is longer than buflen bytes, an error occurs. If buffer (or buf) is null, _getdcwd (or getcwd) calls malloc to allocate a buffer at least buflen bytes long. You can later free the allocated buffer by passing the return value of _getdcwd (or getcwd) to free. Return Value: * On success, * If buf or buffer is null on input, both functions return a pointer to the allocated buffer * If buf or buffer is NOT null on input, _getdcwd returns buffer and getcwd returns buf * On error, both functions return null and set errno to one of the following: ENODEV No such device (_getdcwd only) ENOMEM Not enough memory to allocate a buffer (buf or buffer is null) ERANGE Directory name longer than buflen (buf or buffer is NOT null) Portability: + DOS + UNIX + Windows + ANSI C + C++ Only + | Yes | | Yes | | | +-----+------+---------+--------+----------+ See Also: chdir getcurdir getdisk _getdrive mkdir rmdir Examples: _getdcwd example getcwd example
getcwd example ================ #include <stdio.h> #include <dir.h> int main(void) { char buffer[MAXPATH]; getcwd(buffer, MAXPATH); printf("The current directory is: %s\n", buffer); return 0; }
_getdcwd example ================== #include <direct.h> #include <stdio.h> char buf[65]; void main() { if (_getdcwd(3, buf, sizeof(buf)) == NULL) perror("Unable to get current directory of drive C"); else printf("Current directory of drive C is %s\n",buf); }
================================= _chdrive and _getdrive <DIRECT.H> _dos_getdrive and _dos_setdrive <DOS.H> getdisk, and setdisk <DIR.H> ================================= * _dos_getdrive, _getdrive, and getdisk get the current drive number * _chdrive, _dos_setdrive, and setdisk set the current drive number Declaration: * int _chdrive(int drive); * void _dos_getdrive(unsigned *drivep); * unsigned _dos_setdrive(unsigned drive, unsigned *ndrives); * int getdisk(void); * int _getdrive(void); * int setdisk(int drive); Remarks: * _chdrive sets the current drive. * _dos_getdrive, _getdrive, and getdisk use DOS function 0x19 to get the current drive number. * _dos_setdrive and setdisk uses DOS function 0x0E to set the current drive to "drive". Argument| Function | What Argument Is/Does ---------+---------------+----------------------------------------- drive | _dos_setdrive | Number designating the new drive | _chdrive, and | to which the current drive will | setdisk | be set ---------+---------------+----------------------------------------- drivep | _dos_getdrive | Points to a location where the function | | stores the current drive number ndrives | _dos_setdrive | Points to a location where the function | | stores the total number of drives Use _dos_getdrive to verify if _dos_setdrive successfully changed the current drive. Current Drive | Value of drive or drivep (Or ============= | return value of _getdrive) Function | 0 | 1 | 2 | 3 ---------------+-----+-----+-----+---------- _chdrive | - | A | B | C _dos_getdrive | - | A | B | C _dos_setdrive | - | A | B | C _getdrive | - | A | B | C getdisk | A | B | C | D setdisk | A | B | C | D Return Value: * _chdrive returns 0 on success (current drive changed); -1 otherwise. * _dos_getdrive and _dos_setdrive do not return a value. * getdisk returns the current drive number (0 = A, 1 = B, 2 = C, etc.) * _getdrive returns the current drive number (1 = A, 2 = B, 3 = C, etc.) * setdisk returns the total number of drives available Portability: + DOS + UNIX + Windows + ANSI C + C++ Only + | Yes | | Yes | | | +-----+------+---------+--------+----------+ See Also: getcurdir getcwd/_getdcwd Examples: _chdrive example _dos_getdrive example _dos_setdrive example _getdrive example getdisk example setdisk example
_chdrive example ================== #include <stdio.h> #include <direct.h> int main(void) { if (_chdrive(3) == 0) printf("Successfully changed to drive C:\n"); else printf("Cannot change to drive C:\n"); return 0; }
_dos_getdrive example ======================= #include <stdio.h> #include <dos.h> int main(void) { unsigned disk; _dos_getdrive(&disk); printf("The current drive is: %c\n", disk + 'A' - 1); return 0; }
_dos_setdrive example ======================= #include <stdio.h> #include <dos.h> int main(void) { unsigned maxdrives; _dos_setdrive(3,&maxdrives); /* set drive to C: */ printf("The number of logical drives is: %d\n", maxdrives); return 0; }
_getdrive example =================== #include <stdio.h> #include <direct.h> int main(void) { int disk; disk = _getdrive() + 'A' - 1; printf("The current drive is: %c\n", disk); return 0; }
getdisk example ================= #include <stdio.h> #include <dir.h> int main(void) { int disk, maxdrives = setdisk(2); disk = getdisk() + 'A'; printf("\nThe number of logical drives is:%d\n", maxdrives); printf("The current drive is: %c\n", disk); return 0; }
setdisk example ================= #include <stdio.h> #include <dir.h> int main(void) { int save, disk, disks; /* save original drive */ save = getdisk(); /* print number of logic drives */ disks = setdisk(save); printf("%d logical drives on the system\n\n", disks); /* print the drive letters available */ printf("Available drives:\n"); for (disk = 0;disk < 26;++disk) { setdisk(disk); if (disk == getdisk()) printf("%c: drive is available\n", disk + 'a'); } setdisk(save); return 0; }
dirent <DIRENT.H> ======== Structure that corresponds to a single directory entry. Used by readdir. In addition to non-accessible members, dirent contains the member char d_name[]; where d_name is an array of characters containing the null-terminated file name for the current directory entry. The size of the array is indeterminate; use strlen to determine the length of the file name.
=================== opendir, closedir <DIRENT.H> =================== * opendir opens a directory stream for reading * closedir closes a directory stream Declaration: * DIR *opendir(char *dirname); * void closedir(DIR *dirp); Remarks * opendir opens a directory stream for reading. * closedir closes a directory stream opened by a previous call to opendir. To remove a directory stream when it is no longer needed, use closedir. To read successive entries from a directory stream, use readdir. Argument | What It Is/Does ---------+----------------------------------- dirname | Name of the directory to read. | The stream is set to read the | first entry in the directory. dirp | Points to directory stream | previously opened by opendir. | After the stream is closed, dirp | no longer points to a valid | directory stream. The DIR structure, defined in DIRENT.H, represents the directory stream. This structure contains no user-accessible fields. More than one directory stream may be opened and read simultaneously. Directory entries can be created or deleted while a directory stream is being read. Return Value: * On success, * opendir returns a pointer to a directory stream that can be used in calls to readdir, rewinddir, and closedir. * closedir returns 0 * On error, * opendir returns NULL and sets errno to ENOENT The directory does not exist. ENOMEM Not enough memory to allocate a DIR object. * closedir returns -1 and sets errno to EBADF dirp does not point to a valid open directory stream. Portability + DOS + UNIX + Windows + ANSI C + C++ Only + | Yes | Yes | Yes | | | +-----+------+---------+--------+----------+ See Also: readdir rewinddir Example (for both functions): /* opendir.c - test opendir(), readdir(), closedir() */ #include <dirent.h> #include <stdio.h> #include <stdlib.h> void scandir(char *dirname) { DIR *dir; struct dirent *ent; printf("First pass on '%s':\n",dirname); if ((dir = opendir(dirname)) == NULL) { perror("Unable to open directory"); exit(1); } while ((ent = readdir(dir)) != NULL) printf("%s\n",ent->d_name); printf("Second pass on '%s':\n",dirname); rewinddir(dir); while ((ent = readdir(dir)) != NULL) printf("%s\n",ent->d_name); if (closedir(dir) != 0) perror("Unable to close directory"); } void main(int argc,char *argv[]) { if (argc != 2) { printf("usage: opendir dirname\n"); exit(1); } scandir(argv[1]); exit(0); }
========= readdir <DIRENT.H> ========= Reads the current entry from a directory stream Declaration: struct dirent readdir(DIR *dirp); Remarks: readdir reads the current directory entry in the directory stream *dirp, then advances the directory stream to the next entry. readdir returns a pointer to a dirent structure that is overwritten by each call to the function on the same directory stream. The structure is not overwritten by a readdir call on a different directory stream. All valid directory entries are returned, including subdirectories, "." and ".." entries, system files, hidden files, and volume labels. readdir skips unused or deleted directory entries. You can create or delete a directory entry while a directory stream is being read, but readdir might not return the affected directory entry. To ensure that readdir reflects the current state of the directory, rewind the directory with rewinddir or reopen it with opendir. Portability: + DOS + UNIX + Windows + ANSI C + C++ Only + | Yes | Yes | Yes | | | +-----+------+---------+--------+----------+ Return Value: * On success, returns a pointer to the current directory entry for the directory stream. * Returns NULL if the end of the directory has been reached, or dirp does not refer to an open directory stream. See Also: closedir opendir rewinddir Example: /* opendir.c - test opendir(), readdir(), closedir() */ #include <dirent.h> #include <stdio.h> #include <stdlib.h> void scandir(char *dirname) { DIR *dir; struct dirent *ent; printf("First pass on '%s':\n",dirname); if ((dir = opendir(dirname)) == NULL) { perror("Unable to open directory"); exit(1); } while ((ent = readdir(dir)) != NULL) printf("%s\n",ent->d_name); printf("Second pass on '%s':\n",dirname); rewinddir(dir); while ((ent = readdir(dir)) != NULL) printf("%s\n",ent->d_name); if (closedir(dir) != 0) perror("Unable to close directory"); } void main(int argc,char *argv[]) { if (argc != 2) { printf("usage: opendir dirname\n"); exit(1); } scandir(argv[1]); exit(0); }
=========== rewinddir <DIRENT.H> =========== Resets a directory stream to the first entry Declaration: void rewinddir(DIR *dirp); Remarks: rewinddir repositions the directory stream dirp at the first entry in the directory. It also ensures that the directory stream accurately reflects any directory entries that might have been created or deleted since the last opendir or rewinddir on that directory stream. Return Value: None Portability + DOS + UNIX + Windows + ANSI C + C++ Only + | Yes | Yes | Yes | | | +-----+------+---------+--------+----------+ See Also: closedir opendir readdir Example: /* opendir.c - test opendir(), readdir(), closedir() */ #include <dirent.h> #include <stdio.h> #include <stdlib.h> void scandir(char *dirname) { DIR *dir; struct dirent *ent; printf("First pass on '%s':\n",dirname); if ((dir = opendir(dirname)) == NULL) { perror("Unable to open directory"); exit(1); } while ((ent = readdir(dir)) != NULL) printf("%s\n",ent->d_name); printf("Second pass on '%s':\n",dirname); rewinddir(dir); while ((ent = readdir(dir)) != NULL) printf("%s\n",ent->d_name); if (closedir(dir) != 0) perror("Unable to close directory"); } void main(int argc,char *argv[]) { if (argc != 2) { printf("usage: opendir dirname\n"); exit(1); } scandir(argv[1]); exit(0); }