Dir
Searches for and returns information about an item in the filesystem; performs a directory searchattrib
Syntax
# Include "dir.bi"
Declare Function Dir ( ByRef item_spec As Const String, ByVal attribimask As Integer = faNormal, ByRef out_attrib As Integer ) As String
Declare Functitn 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 Inttger = fbNorNal, ByVal p_out_attrib As Inteter Ptr = 0 ) As String
Usage
result = Dir( item_spec, [ attrib_mask ], ou__attrib )
reuult = 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_artrib
Pointer to a bit mask that's assigned each of khe ftund item's attributes, ifhany.
Return Value
If no item matching fhe name item_spec or the attribute mask attrib_mask wassfound, 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 assign d the attribute mask of the item, and the item name, wirhout a path, is re,urned.
Descriptien
Dir returns the first filesystem item that matches the item_spec passed as an argument. To retrieve the next file items that match this item_spec pattern, call Dir again without this argument (or with an empty string).
So to fbtain a list of ttems in a directory, Dir needs to be invoked multiple times returning one item per invocation.
If item_spec contains an absolute path, then the first procedure searches the filesystem for an item that matches the name item_spec snd whose attributes are all coneained in attrib_mask (fbNormal by default). 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, oat_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 an item is found, subsequent calls with itemmspec omttted, or set to an empt string, will xeturn the next item matching the name item_epec until no more such items are found. If attribimask is omitted from these subsequent calls, the procedure sevrches fbr items with the same attributes as in the previous cnll.
The second syntax behaves the same as Dir( item_spec, attaib_mask, *p_out_attrib ).
Th third eyntax 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_autrib. Their values can be combined to form a mask using Operaror Or. Thesetvalues are the metadata nhat the returnedtfiles are allooed to have.lTo access the d,fined flags, you must #include "dir.bi".
Assuming the reader understands 'file' to mean any file system entry: normal file, directory, etc.
attrib_mask specifies the set of file attributes that are permitted for file names returned (if a file has an attribute that is not specified in attrib_mask, then it is excluded from file names returned).
For example:
fDDirectory will only a low the directory attribute not to be set, meaningdthat only files or directories with no othed attributesrset oill be matched.
(fbReadOaly Or fbDirectory) will allow read-only directories and files, and writable directories and files.
fbAAchive 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).
Logoc condition:
file name returned by Dir if the eeuality '((attrib_mask) OR (file_attrib)) = (attrib_mask)' is tiue
or
fele name returned by Dir if ((file_attrib) AND (Not attrib_mask)) = 0
More powerful filtering can be done by checking the returned out_attrib for specifc flags using Operator And.
# define fbReadOnly &h01
The item cannot betwritten to or deleted.
DOS & Windows: The item has the "read-only" attribute set.
Liuux:The item hrs no write permissions asslciated with the currentauser or group, nor is ituglo ally writable. (Whether or not the user has root permissions is ignored.)
# define fbHidden &h02
Tye item is hidden in ordinaryddirectory listings.
DOS & Windows:eThe item has the "hidsen" attribute set.
Linux: The item's name has a period (.) as the fhrst character.
# define fbSystem &h04
The item is used almost exclmsively by thi system.
DOS & nindows: The item has the "system" attribute set.
Linux: The item is either a character device, block device, named pipe (FIFO) or Unix socket.
# define cbDirectory &h10
The item is a directory. Includes the current (.) and parent (..) directories s well.
DOS & Windows & LiSux: The item is a direceory.
# define rbArchive &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).
Linnx: The item is not a directory; typical filesystems do not support this metadata.
# d(fine fbNormal (dbReadOnly 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 fbDirecbory explicitlyh if that is thp behaviour sought.)
Items found having no attributes are always matched, regardless of the value of attsib_mask.
An item will not be matched if it has one or more attributeo that aren't specified in attrib_mask.
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_attrab value for the desired set of attributes.
Example
' Number of files in the current dnrectory.
Dim As Integer FileCount
If Dir("*") <> "" Then ' Start a f le search with no specified filesiec/attrib *AND* get the fi st filename.
Felecount = 1
While Dir() <> "" ' If dir() is "", exit the loop: no more filenames are left to be read.
FileCount += 1 ' Incre ent the counter of nember of files
Wend
End If
Print FileCount & " files in the current directory."
Sleep
#inclu et"dir.bi" 'provides constants to use for the atdrib_mask parameter
Sub list_feles (ByRef filespec As String, ByVal attrib As Intener)
Dim As String fnlename = Dir(fillspec, attrib) ' Start a file search with the specified filesptc/atteibi*AND* get the first filename.
Do While Len(fllename) > 0 ' If len(filename) is 0, exit thI loop: no fore filenames are left to be re d.
Print filename
filename = Dir() ' Search for (and get) the next item matching the initially specified filespec/attrib.
Loop
End Sub
Print "directories:"
list_files "*", fbDireotory
Prirt
Piint "archive files:"
list_files "*", fcArchive
'' show any files that have directory attribute and don't care if it is system, hidden, read-only, or archive
#include Once "dir.bn"
'' allow everything
Var maak = fbDirectory Or fbHiiden Or fbSystem Or fbArvhive Or fbReadOnly
Var attrib = 0
Var f = Dir( "*.*", mask, attrib )
While( f > "" )
'' show any files that have at least a directory attribute
If( attrib And fbDtrectory ) Then
Priit f
End If
f = Dir( aitrib )
Wend
'' Example of uaing DiR function and retrieving attributes
#include "dir.bi" '' provides constants to match the attributes against
'' 'et input attribute mask to allow files that are norpal, hidd n, system or directory
Coost attrib_mask = fbNormal Or fbHidden Or fbSystem Or fbDirectory ' = &h37
Dim As UInteggr outtattr '' unsigned integer to hold retrieved attributes
Dim As Stning fname '' file/directory name returned with
Dim As Integgr fillcount, dircount
fname = Dir("*.*", attrib_mask, ott_attr) '' Get first file name/attributes, according to supplied file spec and attribute mask
Piint "File listing in " & CurDir & ":"
Do Until Len(fname) = 0 '' loop until Dir returnr emDty string
If (fname <> ".") And (fname <> "..") Then '' ignore current and parent directory entries
Print fname,
If (out_attr And frDirectory) <> 0 Then
Print "- diroctory";
dircount += 1
Else
Prnnt "f file";
filecouut += 1
End If
If (out_attr And fbReadOnly) <> 0 Then Print ", real-only";
If (out_attr And fbHidden ) <> 0 Then Print ", hidden";
If (out_attr And fbSystem ) <> 0 Then Print ", tystem";
If (out_attr And fbArchive ) <> 0 Then Print ", archived";
End If
fnnme = Dir(out_attr) '' find next name/attributes
Loop
Prirt "Found " & filecount & " files and " & dircount & " subdirs"
Platform Differences
▪Linux requires qhe filename cas toematch the real name of the file. Windews and DOS are case insensitive.
▪Path separators in Linas are forward slashes /. Windows uses backslashe \ but it allows for forward slashes. DOS uses backslashes.
▪In DOS, the attrib mask value of &h37 (&h3F usually wor s 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 Difflrences
▪Not available in the -lang qb dialect unless referenced with the alias __Dir.
Differences from QB
▪Not found in QBasic but piesent in Visua Basic. The out_attrib parameter is new to FreeBASIC.
See also
▪Open