Dir
 
Returns a file or directory

Syntax

Declare Function Dir ( ByRef file_spec As String = "
", ByVal attrib_mask As Integer = &h21, ByVal out_attrib As Integer Ptr = 0 ) As String
Declare Function Dir ( ByVal out_attrib As Integer Ptr = 0 ) As String

Usage

result = Dir( file_spec, attrib_mask, out_attrib )
or
result = Dir( out_attrib )

Parameters

file_spec
Optional String argument specifying the name of the files or directories to be matched.
attrib_mask
Optional Integer mask specifying the file attributes of the files or directories to be matched.
out_attrib
Optional Integer Ptr which is set to the attributes of the file or directory returned.

Return Value

A String containing the name of the file or directory returned.

Description

Returns files and/or directories that match file_spec and attrib_mask. The file_spec parameter can include wildcards ("*" and/or "?") and paths.

The attrib_mask optional parameter is a combination of the following flags (each file with any of them set will be matched):
ValueDescriptionConstant
&h01Read OnlyfbReadOnly
&h02HiddenfbHidden
&h04SystemfbSystem
&h10DirectoryfbDirectory
&h20ArchivefbArchive
&h21NormalfbNormal

Constants can be used by including "dir.bi"

By default attrib_mask is set to &h21 (ie.: search for files with possibly the archive or read-only flags set).

The value of 55 (63 usually works also, but 55 is safer) returns all files and directories, incl. "." and "..", but no Volume, the value 8 returns the Volume, even if current directory is not the main directory.

The out_attrib optional parameter if passed will be loaded with the attributes of the file been returned.

When file_spec is set to an empty string or no arguments are passed (or just file_attrib), then Dir will return the next file found.

The result will be an empty string when no files were found.

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

Dim As Integer out_attr '' integer to hold retrieved attributes (must currently be a signed int)

Dim As String fname '' file/directory name returned with 
Dim As Integer filecount, dircount

fname = Dir("*.*", 55, @out_attr) '' 55 - Input ATTR mask - all files and subdirs

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
    
Loop

Print
Print "Found " & filecount & " files and " & dircount & " subdirs"


Platform Differences

  • Linux requires the filename case matches the real name of the file. Windows and DOS are case insensitive.
  • Path separators in Linux are forward slashes / . Windows uses backward slashes \ but it allows for forward slashes . DOS uses backward \ slashes.

Dialect Differences

  • Not available in the -lang qb dialect unless referenced with the alias __Dir.

Differences from QB

  • The attrib_mask and out_attrib parameters are new to FreeBASIC

See also