Dir Function

Dir Function

---

Class

Microsoft.VisualBasic.FileSystem

Syntax

 Dir[(   pathname   [,   attributes   ])] 

pathname (optional; String)

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

attributes (optional; Numeric or Constant of the FileAttribute enumeration)

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

Return Value

String

Description

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

Rules at a Glance

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

• Possible values for attributes are:

FileAttribute enumeration	Value	Description
Normal		Normal (not hidden and not a system file)
ReadOnly	1	Read-only file
Hidden	2	Hidden
System	4	System file
Volume	8	Volume label; if specified, all other attributes are ignored
Directory	16	Directory or folder
Archive	32	Archive
Alias	64	Alias or link

• The attributes constants can be Or ed together to create combinations of attributes to match; e.g., FileAttribute.Hidden Or FileAttribute. Directory will match hidden directories.

• If attributes is not 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 it. pathname must also be specified if you are specifying attributes . 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.

• A call to Dir with no arguments continues the search for a file matching the last used pathname argument (and attribute argument, if it was supplied).

Example

 Private Sub Button1_Click(ByVal sender As System.Object, _                              ByVal e As System.EventArgs) _                Handles Button1.Click       Dim sFileName As String       Dim sPath As String = "c:\windows\*.txt"       sFileName = Dir(sPath)       Do While sFileName > ""          ListBox1.Items.Add(sFileName)          sFileName = Dir(  )       Loop    End Sub 

Programming Tips and Gotchas

• Dir can only return 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 the next call, or an error is generated.

• In previous versions of Visual Basic, the Dir function was commonly employed to determine whether a particular file existed. Although it can still be used for this purpose, the use of the BCL System.IO namespace's File.Exists method is more straightforward. Since Exists is a shared public member of the File class, it can be called as follows :

   If File.Exists("c:\windows\network.txt") 

• 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. Note that an array can be easily sorted using the Array object's Sort method; the Array class is part of the BCL's System namespace.

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

• 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", FileAttribute.Normal) 

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

   strFile = Dir("C:\Windows\*.*", FileAttribute.Normal) 

• A major limitation of Dir is that it returns only the filename; it does not provide other information, such as the size , date, and timestamp, or attributes of a file.

• 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 are not set). Hidden returns a normal file or a hidden file, but not a system file and not a system file that is hidden. System returns a normal file or a system file, but not a hidden file, including a system file that is hidden. FileAttribute.System Or FileAttribute.Hidden returns any file, regardless of whether it is normal, hidden, system, or system and hidden.