Dir
Searches for and returns information about an item in the filesystem; performs a directory search
# Include "dir.bi"
Declare Function Dir ( ByRef item_spec As Const String, ByVal attrib_mask As Integer = fbNormal, ByRef out_attrib As Integer ) As String
Declare Function Dir ( ByRef item_spec As Const String, ByVal attrib_mask As Integer = fbNormal, ByVal p_out_attrib As Integer Ptr = 0 ) As String
Declare Function Dir ( ByVal attrib_mask As Integer = fbNormal, ByRef out_attrib As Integer ) As String
Declare Function Dir ( ByVal attrib_mask As Integer = fbNormal, ByVal p_out_attrib As Integer Ptr = 0 ) As String
result = Dir( item_spec, [ attrib_mask ], out_attrib ] )
result = Dir( item_spec [, [ attrib_mask ] [, p_out_attrib ] ] )
result = Dir( out_attrib )
result = Dir( [ p_out_attrib ] )
item_spec
If no item matching the name item_spec or the attribute mask attrib_mask was found, then out_attrib (or *p_out_attrib) is assigned to zero and an empty string is returned. Otherwise, out_attrib (or *p_out_attrib) is assigned the attribute mask of the item, and the item name, without a path, is returned.
If item_spec contains an absolute path, then the first procedure searches the filesystem for an item that matches the name item_spec and whose attributes are all contained in attrib_mask. Otherwise, it searches relative to the current directory (see CurDir). In any case, if a matching item is not found, out_attrib is assigned to zero and an empty string is returned. Otherwise, out_attrib is assigned with the attribute flags of the item, and the name of the item, without a path, is returned.
item_spec may include an asterisk (*, for matching any adjacent characters) or one or more question marks (?, for matching any individual character). If it does, the procedure searches for the first such item. If found, subsequent calls with item_spec omitted, or set to an empty string, will return the next item matching the name item_spec until no more such items are found. If attrib_mask is omitted from these subsequent calls, the procedure searches for items with the same attributes as in the previous call.
The second syntax behaves the same as Dir( item_spec, attrib_mask, *p_out_attrib ).
The third syntax behaves the same as Dir( "", , out_attrib ).
The fourth syntax behaves the same as Dir( "", , *p_out_attrib ).
File Attributes:
Files and directories and other items can be said to possess so-called file attributes; metadata that describes the item. The meaning of this metadata may vary depending on the operating system and the file system it uses.
The following defined constants are used as bit-flags in attrib_mask and in out_attrib or *p_out_attrib. Their values can be combined to form a mask using Operator Or. These values are the metadata that the returned files are allowed to have. For example, fbDirectory will only allow the directory attribute not to be set, meaning that only files or directories with no other attributes set will be matched. (fbReadOnly Or fbDirectory) will allow read-only directories and files, and writable directories and files.
More powerful filtering can be done by checking the returned out_attrib for specifc flags using Operator And. To access the defined flags, you must #include "dir.bi".
# define fbReadOnly &h01;
Items found having no attributes are always matched, regardless of the value of attrib_mask. An item will not be matched if it has one or more attributes that aren't specified in attrib_mask. For example, fbArchive Or fbDirectory will match against archived files, archived directories, non-archived files and non-archived directories. It will not match against, for example, read-only files.
In general it is not possible to use attrib_mask to include a file/folder with one set of attributes while excluding a file/folder with a different set. For example, it is not possible to scan for read-only directories while excluding read-only files (unless the files also have other attributes). Finer control can be gained by checking the out_attrib value for the desired set of attributes.
Syntax
# Include "dir.bi"
Declare Function Dir ( ByRef item_spec As Const String, ByVal attrib_mask As Integer = fbNormal, ByRef out_attrib As Integer ) As String
Declare Function Dir ( ByRef item_spec As Const String, ByVal attrib_mask As Integer = fbNormal, ByVal p_out_attrib As Integer Ptr = 0 ) As String
Declare Function Dir ( ByVal attrib_mask As Integer = fbNormal, ByRef out_attrib As Integer ) As String
Declare Function Dir ( ByVal attrib_mask As Integer = fbNormal, ByVal p_out_attrib As Integer Ptr = 0 ) As String
Usage
result = Dir( item_spec, [ attrib_mask ], out_attrib ] )
result = Dir( item_spec [, [ attrib_mask ] [, p_out_attrib ] ] )
result = Dir( out_attrib )
result = Dir( [ p_out_attrib ] )
Parameters
item_spec
The pattern to match an item's name against.
attrib_maskThe bit mask to match an item's attributes against.
out_attribReference to a bit mask that's assigned each of the found item's attributes, if any.
p_out_attribPointer to a bit mask that's assigned each of the found item's attributes, if any.
Return Value
If no item matching the name item_spec or the attribute mask attrib_mask was found, then out_attrib (or *p_out_attrib) is assigned to zero and an empty string is returned. Otherwise, out_attrib (or *p_out_attrib) is assigned the attribute mask of the item, and the item name, without a path, is returned.
Description
If item_spec contains an absolute path, then the first procedure searches the filesystem for an item that matches the name item_spec and whose attributes are all contained in attrib_mask. Otherwise, it searches relative to the current directory (see CurDir). In any case, if a matching item is not found, out_attrib is assigned to zero and an empty string is returned. Otherwise, out_attrib is assigned with the attribute flags of the item, and the name of the item, without a path, is returned.
item_spec may include an asterisk (*, for matching any adjacent characters) or one or more question marks (?, for matching any individual character). If it does, the procedure searches for the first such item. If found, subsequent calls with item_spec omitted, or set to an empty string, will return the next item matching the name item_spec until no more such items are found. If attrib_mask is omitted from these subsequent calls, the procedure searches for items with the same attributes as in the previous call.
The second syntax behaves the same as Dir( item_spec, attrib_mask, *p_out_attrib ).
The third syntax behaves the same as Dir( "", , out_attrib ).
The fourth syntax behaves the same as Dir( "", , *p_out_attrib ).
File Attributes:
Files and directories and other items can be said to possess so-called file attributes; metadata that describes the item. The meaning of this metadata may vary depending on the operating system and the file system it uses.
The following defined constants are used as bit-flags in attrib_mask and in out_attrib or *p_out_attrib. Their values can be combined to form a mask using Operator Or. These values are the metadata that the returned files are allowed to have. For example, fbDirectory will only allow the directory attribute not to be set, meaning that only files or directories with no other attributes set will be matched. (fbReadOnly Or fbDirectory) will allow read-only directories and files, and writable directories and files.
More powerful filtering can be done by checking the returned out_attrib for specifc flags using Operator And. To access the defined flags, you must #include "dir.bi".
# define fbReadOnly &h01;
The item cannot be written to or deleted.
DOS & Windows: The item has the "read-only" attribute set.
Linux:The item has no write permissions associated with the current user or group, nor is it globally writable. (Whether or not the user has root permissions is ignored.)
# define fbHidden &h02; DOS & Windows: The item has the "read-only" attribute set.
Linux:The item has no write permissions associated with the current user or group, nor is it globally writable. (Whether or not the user has root permissions is ignored.)
The item is hidden in ordinary directory listings.
DOS & Windows: The item has the "hidden" attribute set.
Linux: The item's name has a period (.) as the first character.
# define fbSystem &h04; DOS & Windows: The item has the "hidden" attribute set.
Linux: The item's name has a period (.) as the first character.
The item is used almost exclusively by the system.
DOS & Windows: The item has the "system" attribute set.
Linux: The item is either a character device, block device, named pipe (FIFO) or Unix socket.
# define fbDirectory &h10; DOS & Windows: The item has the "system" attribute set.
Linux: The item is either a character device, block device, named pipe (FIFO) or Unix socket.
The item is a directory. Includes the current (.) and parent (..) directories as well.
DOS & Windows & Linux: The item is a directory.
# define fbArchive &h20; DOS & Windows & Linux: The item is a directory.
The item may be backed up after some automated operations.
DOS & Windows: The item has the "archive" attribute set (automatically set after every write access to a file).
Linux: The item is not a directory; typical filesystems do not support this metadata.
# define fbNormal (fbReadOnly or fbArchive) DOS & Windows: The item has the "archive" attribute set (automatically set after every write access to a file).
Linux: The item is not a directory; typical filesystems do not support this metadata.
The item is read-only or "archived".
(If attrib_mask does not include fbArchive, then Dir may widen the check to include fbDirectory, but it is recommended to add fbDirectory explicitly, if that is the behaviour sought.)Items found having no attributes are always matched, regardless of the value of attrib_mask. An item will not be matched if it has one or more attributes that aren't specified in attrib_mask. For example, fbArchive Or fbDirectory will match against archived files, archived directories, non-archived files and non-archived directories. It will not match against, for example, read-only files.
In general it is not possible to use attrib_mask to include a file/folder with one set of attributes while excluding a file/folder with a different set. For example, it is not possible to scan for read-only directories while excluding read-only files (unless the files also have other attributes). Finer control can be gained by checking the out_attrib value for the desired set of attributes.
Example
#include "dir.bi" 'provides constants to use for the attrib_mask parameter
Sub list_files (ByRef filespec As String, ByVal attrib As Integer)
Dim As String filename = Dir(filespec, attrib) ' Start a file search with the specified filespec/attrib *AND* get the first filename.
Do While Len(filename) > 0 ' If len(filename) is 0, exit the loop: no more filenames are left to be read.
Print filename
filename = Dir()
Loop
End Sub
Print "directories:"
list_files "*", fbDirectory
Print
Print "archive files:"
list_files "*", fbArchive
Sub list_files (ByRef filespec As String, ByVal attrib As Integer)
Dim As String filename = Dir(filespec, attrib) ' Start a file search with the specified filespec/attrib *AND* get the first filename.
Do While Len(filename) > 0 ' If len(filename) is 0, exit the loop: no more filenames are left to be read.
Print filename
filename = Dir()
Loop
End Sub
Print "directories:"
list_files "*", fbDirectory
Print "archive files:"
list_files "*", fbArchive
Example
'' Example of using DIR function and retrieving attributes
#include "dir.bi" '' provides constants to match the attributes against
'' set input attribute mask to allow files that are normal, hidden, system or directory
Const attrib_mask = fbNormal Or fbHidden Or fbSystem Or fbDirectory ' = &h37
Dim As UInteger out_attr '' unsigned integer to hold retrieved attributes
Dim As String fname '' file/directory name returned with
Dim As Integer filecount, dircount
fname = Dir("*.*", attrib_mask, out_attr) '' Get first file name/attributes, according to supplied file spec and attribute mask
Print "File listing in " & CurDir & ":"
Do Until Len(fname) = 0 '' loop until Dir returns empty string
If (fname <> ".") And (fname <> "..") Then '' ignore current and parent directory entries
Print fname,
If (out_attr And fbDirectory) <> 0 Then
Print "- directory";
dircount += 1
Else
Print "- file";
filecount += 1
End If
If (out_attr And fbReadOnly) <> 0 Then Print ", read-only";
If (out_attr And fbHidden) <> 0 Then Print ", hidden";
If (out_attr And fbSystem) <> 0 Then Print ", system";
If (out_attr And fbArchive) <> 0 Then Print ", archived";
Print
End If
fname = Dir(out_attr) '' find next name/attributes
Loop
Print
Print "Found " & filecount & " files and " & dircount & " subdirs"
#include "dir.bi" '' provides constants to match the attributes against
'' set input attribute mask to allow files that are normal, hidden, system or directory
Const attrib_mask = fbNormal Or fbHidden Or fbSystem Or fbDirectory ' = &h37
Dim As UInteger out_attr '' unsigned integer to hold retrieved attributes
Dim As String fname '' file/directory name returned with
Dim As Integer filecount, dircount
fname = Dir("*.*", attrib_mask, out_attr) '' Get first file name/attributes, according to supplied file spec and attribute mask
Print "File listing in " & CurDir & ":"
Do Until Len(fname) = 0 '' loop until Dir returns empty string
If (fname <> ".") And (fname <> "..") Then '' ignore current and parent directory entries
Print fname,
If (out_attr And fbDirectory) <> 0 Then
Print "- directory";
dircount += 1
Else
Print "- file";
filecount += 1
End If
If (out_attr And fbReadOnly) <> 0 Then Print ", read-only";
If (out_attr And fbHidden) <> 0 Then Print ", hidden";
If (out_attr And fbSystem) <> 0 Then Print ", system";
If (out_attr And fbArchive) <> 0 Then Print ", archived";
End If
fname = Dir(out_attr) '' find next name/attributes
Loop
Print "Found " & filecount & " files and " & dircount & " subdirs"
Platform Differences
- Linux requires the filename case to match the real name of the file. Windows and DOS are case insensitive.
- Path separators in Linux are forward slashes /. Windows uses backslashes \ but it allows for forward slashes. DOS uses backslashes.
- In DOS, the attrib mask value of &h37; (&h3F; usually works also, but &h37; is safer) returns all files and directories, including "." and "..", but no Volume: the value 8 returns the Volume, even if current directory is not the main directory.
Dialect Differences
- Not available in the -lang qb dialect unless referenced with the alias __Dir.
Differences from QB
- Not found in QBasic but present in Visual Basic. The out_attrib parameter is new to FreeBASIC.
See also