Dir, Dir$ Functions

---

Named Arguments

No

Syntax

Dir[(pathname[, attributes])]

pathname

Use: Optional

Data Type: String

A string expression that defines a path that may contain a drive name, a folder name, and a filename.

attributes

Use: Optional

Data Type: Numeric or Constant

A constant or numeric expression specifying the file attributes to be matched.

Return Value

Dir returns a variant of subtype string; Dir$ returns a string data type.

Description

Returns the name of a single file or folder matching the pattern or attribute passed to the function.

Rules at a Glance

• A zero-length string ("") is returned if a matching file isn't found.

• Possible values for attributes are:

  Constant	Value	Description
  vbNormal	0	Normal (not hidden and not a system file)
  vbHidden	2	Hidden
  vbSystem	4	System file
  vbVolume	8	Volume label; if specified, all other attributes are ignored
  vbDirectory	16	Directory or folder

  
  

• The object browser and published documentation list several other constants that can be supplied as arguments to the attributes parameter. However, these either don't work on the Win9x/NT platforms (i.e., vbAlias, which is available only on the Macintosh) or have no effect on the operation of the function (vbReadOnly, vbArchive).

• The attributes constants can be added together to create combinations of attributes to match; e.g., vbHidden + vbDirectory matches hidden directories.

• If attributes isn't specified, files matching pathname are returned regardless of attributes.

• You can use the wildcard characters * and ? within pathname to return multiple files.

• Although pathname is optional, the first call you make to Dir must include pathname. pathname must also be specified if you are specifying attri-butes. In addition, once Dir returns a zero-length string, subsequent calls to Dir must specify pathname or runtime error 5 ("Invalid procedure call or argument") results.

Example

Private Sub CommandButton1_Click()

Dim sFileName As String
Dim sPath As String
    
sPath = "c:windows*.txt"
sFileName = Dir$(sPath)
    
Do While sFileName > ""
    ListBox1.AddItem sFileName
    sFileName = Dir$
Loop

End Sub

Programming Tips and Gotchas

• Dir can return only one filename at a time. To create a list of more than one file that matches pathname, you must first call the function using the required parameters, then make subsequent calls using no parameters. When there are no more files matching the initial specification, a zero-length string is returned. Once Dir has returned a zero-length string, you must specify a pathname in a subsequent call or an error is generated. The example for the Dir function shows how to do this in a VBA application using a UserForm with a command button and a list box control. (Note: to get the example to run under VB rather than VBA, the references to ListBox1 should simply be replaced with List1. Also note that the above example doesn't work with the vbDirectory attribute.)

• The Dir function is the only method of determining if a file exists without having to create elaborate error-handling routines. Quite simply, pass the function the name of the file you wish to check. If Dir returns a zero-length string, you know that the file doesn't exist, as the following example shows:

  Public Function FileExists(sPath As String) As Boolean
  
      If Dir(sPath) > "" Then
          FileExists = True
      Else
          FileExists = False
      End If
      
  End Function

  
  

• The Dir function returns filenames in the order in which they appear in the file allocation table. If you need the files in a particular order, you should first store the names in an array before sorting.

• The Dir function saves its state between invocations, which means that the function can't be called recursively. For example, if the function returns the name of the directory, you can't then call the Dir function to iterate the files in that directory and then return to the original directory.

• If attributes is set to vbDirectory only, the function behaves somewhat differently. If wildcard characters are used in pathname, the function returns only the first directory that matches the search criteria. Subsequent calls to the function without providing a new pathname argument return the names of ordinary files.

• If you are calling the Dir function to return the names of one or more files, you must provide an explicit file specification. In other words, if you want to retrieve the names of all files in the Windows directory, for instance, the function call:

  strFile = Dir("C:Windows", vbNormal)

  
  

• necessarily fails. Instead, the Dir function must be called with the pathname defined as follows:

  strFile = Dir("C:Windows*.*", vbNormal)

  
  

• A major limitation of the Dir and Dir$ functions is that they return only the filename; they don't provide other information, such as the size, date and time stamp, or attributes of a file. These are most easily accessible by using the File object's Attributes property in the File System object model.

• Many difficulties with the Dir function result from not fully understanding how various attributes constants affect the file or files returned by the function. By default, Dir returns a "normal" file (i.e., a file whose hidden or system attributes aren't set). vbHidden returns a normal file or a hidden file, but not a system file and not a system file that is hidden. vbSystem returns a normal file or a system file, but not a hidden file, including a system file that is hidden. vbSystem + vbHidden returns any file, regardless of whether it's normal, hidden, system, or system and hidden.

• Using the new File System object model in VB6 overcomes all the limitations of Dir and Dir$.

See Also

CurDir Statement, File System Objects