Dir
Searches for and returns information about an item in the filesystem; performs a directory search
Syntax
`
# Include "dir.bi"
Declare Function Dir Overload ( 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_mask`
The bit mask to match an item's attributes against.
`out_attrib`
Reference to a bit mask that's assigned each of the found item's attributes, if any.
`p_out_attrib`
Pointer 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`
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`
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`
The item is a directory. Includes the current (`.`) and parent (`..`) directories as well.
DOS & Windows & Linux: The item is a directory.
`# define fbArchive &h20`
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)`
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
`
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"
`
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

- `Open`
- `CurDir`
- `MkDir`
- `RmDir`