=======
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);
}