Searches for and returns information about an item in the filesystem, performs a directory search.
Syntax
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
The address of 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 equal 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 procedure behaves the same as
Dir( item_spec, attrib_mask, *p_out_attrib ).
The third procedure behaves the same as
Dir( "", , out_attrib ).
The fourth procedure 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 item. The meaning of this metadata varies with operating system and the file system it uses. The following macros are used as bit-flags with
attrib_mask,
out_attrib and
*p_out_attrib. Their values can be combined to form a mask using
Operator Or. To access them,
Include "dir.bi".
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. Further, if
attrib_mask And fbArchive is zero, then
attrib_mask is assigned to
attrib_mask Or fbDirectory before checking the file for matching attributes.
# 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: The item has the "directory" attribute set.
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.
Linux: The item is not a directory; typical filesystems do not support this metadata.
# define fbNormal (fbReadOnly or fbArchive)
The item is a file or directory.
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 filename As String
filename = Dir( filespec, attrib )
Do
Print filename
filename = Dir( )
Loop While Len( filename ) > 0
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 Then
Print "- directory";
dircount += 1
Else
Print "- file";
filecount += 1
End If
If out_attr And fbReadOnly Then Print ", read-only";
If out_attr And fbHidden Then Print ", hidden";
If out_attr And fbSystem Then Print ", system";
If out_attr And fbArchive 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