# Include "dir.bi"

Declare Function Dir Overload ( ByRef item_spec As Const String, ByVal attrib_mask As Integer = fbNormal, ByRef out_attrib As Integer ) As String
Declare Function 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 Integer = fbNormal, ByVal p_out_attrib As Integer Ptr = 0 ) As String

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 ] )

item_spec
attrib_mask
out_attrib
p_out_attrib

Если ни один элемент с именем item_spec или атрибутом маски attrib_mask не был найден, тогда в out_attrib (или *p_out_attrib) присваивается нуль и пустая строка возвращается. В противном случае, в out_attrib (или *p_out_attrib) назначается атрибут маски элемента, и возвращается имя элемента без пути.

Если item_spec содержит абсолютный путь, тогда первая процедура ищет в файловой системе для элемента, который совпадает с именем item_spec и атрибутами, содержащимися в attrib_mask. В противном случае, он ищет относительно текущего каталога (см. CurDir). В любом случае если соответствующий элемент не найден, в out_attrib присваивается нуль и пустая строка возвращается. В противном случае, в out_attrib присваиваются флаги атрибута элемента, и возвращается имя элемента, без пути.

item_spec может включать в себя звездочку (*, для сопоставления любому соседнему символу) или один или несколько знаков вопроса (?, для сопоставления любому индивидуальному символу). Если это так, процедура ищет первый такой пункт. Если найдено, последующие вызовы с item_spec равным пустой строке, вернет следующий пункт, соответствующий имени item_spec до тех пор, пока есть возможность найти такие пункты. Если attrib_mask исключается из последующих вызовов, процедура поиска для элементов происходит с теми же атрибутами, как и в предыдущем вызове.

Вторая процедура ведет себя так же, как Dir( item_spec, attrib_mask, *p_out_attrib ).

Третья процедура ведет себя так же, как Dir( "", , out_attrib ).

Четвертая процедура действует так же, как Dir( "", , *p_out_attrib ).

Атрибуты файла:
Файлы , каталоги и другие элементы, можно сказать, обладают так называемыми атрибутами файла; метаданные, описывающие элемент. Смысл этих метаданных зависит от операционной системы и файловой системы. Следующие макросы используются как битовые флаги с attrib_mask, out_attrib и *p_out_attrib. Их значения могут быть объединенной маской, с помощью Оператора Or, или отдельные значения, которые могут быть проверены с помощью Оператора And. Для доступа к ним нужно подключить Include "dir.bi".

# define fbReadOnly &h01
# define fbHidden &h02
# define fbSystem &h04
# define fbDirectory &h10
# define fbArchive &h20
# define fbNormal (fbReadOnly or fbArchive)
(Если attrib_mask не включает fbArchive, тогда Dir может расширить проверку , включив fbDirectory, но рекомендуется добавлять явно fbDirectory , если данное поведение нужно для поиска.)

Количество элементов, не имеющих атрибутов , всегда совпадают, независимо от значения attrib_mask. Элемент не будет соответствовать, если он имеет один или несколько атрибутов, не указанных в attrib_mask. Для примера, fbArchive Or fbDirectory будет соответствовать архивным файлам, архивным каталогам, не-архивным файлам и не-архивным каталогам. Это не будет соответствовать например для файлов "только для чтения".

В общем, не возможно использовать attrib_mask чтобы включить файл/папку с одним набором атрибутов, исключая файл/папку с другим набором. К примеру не возможно сканировать каталоги только для чтения, исключая файлы, доступные только для чтения (за исключением случаев, если файлы также имеют другие атрибуты). Более точного управления можно получить путем проверки значения out_attrib для нужного набора атрибутов.

#include "dir.bi" 'предоставляет константы для использования для параметра attrib_mask

Sub list_files (ByRef filespec As String, ByVal attrib As Integer)
    Dim As String filename = Dir(filespec, attrib) ' Начать поиск файла с указанным filespec/attrib и получить имя первого файла.
    Do While Len(filename) > 0 ' Если len(filename) является 0, выход из цикла: нет больше , оставшихся имен для чтения.
        Print filename
        filename = Dir()
    Loop
End Sub

Print "directories:"
list_files "*", fbDirectory

Print
Print "archive files:"
list_files "*", fbArchive

'' Пример использования функции DIR и получения атрибутов

#include "dir.bi" '' предоставляет константы для сопоставления атрибутов

'' задать маску входного атрибута, разрешить нормальный, скрытый, системный или каталог
Const attrib_mask = fbNormal Or fbHidden Or fbSystem Or fbDirectory ' = &h37

Dim As UInteger out_attr '' целое число без знака для хранения проверяемых атрибутов

Dim As String fname '' имя возвращаемого файла/директории
Dim As Integer filecount, dircount

fname = Dir("*.*", attrib_mask, out_attr) '' Получить имя первого файла/атрибутов, согласно прилагаемого файла и маски атрибута

Print "File listing in " & CurDir & ":"

Do Until Len(fname) = 0 '' цикл до тех пор, пока функция Dir не вернет пустую строку

    If (fname <> ".") And (fname <> "..") Then '' игнорировать текущий и родительский каталоги

        Print fname,

        If (out_attr And fbDirectory) <> 0 Then
            Print "- directory";
            dircount += 1
        Else
            Print "- file";
            filecount += 1
        End If
        If (out_attr And fbReadOnly) <> 0 Then Print ", read-only";
        If (out_attr And fbHidden) <> 0 Then Print ", hidden";
        If (out_attr And fbSystem) <> 0 Then Print ", system";
        If (out_attr And fbArchive) <> 0 Then Print ", archived";
        Print

    End If

    fname = Dir(out_attr) '' найти следующее имя\атрибуты

Loop

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

• Linux требует, чтобы filename соответствовало реальному имени файла. Windows и DOS регистронезависимы.
  
• Разделителями пути в Linux являются прямые слэши / . Windows использует обратный слэш \ ,  но позволяет и прямой слэш. DOS использует обратный слэш \.
  
• В DOS, значение атрибута маски &h37 (&h3F работает также, но &h37 безопаснее) возвращает все файлы и каталоги, включая "." и "..", но не Volume(переводите как желаете: том, объем, вместительность): значение 8 вернет Volume, даже если текущий каталог не является основным каталогом.
  
  

• Не доступно в диалекте -lang qb , но есть псевдоним __Dir.
  
  

• Не было в QBasic, но присутствовало в Visual Basic. Параметр out_attrib является новым в FreeBASIC.
  
  

• Open
  
• CurDir
  
• MkDir
  
• RmDir