Topic       : The ATARI Compendium
Author      : Scott Sanders / JAY Software
Version     : 1.25 (20/6/2003)
Subject     : Documentation
Nodes       : 1117
Index Size  : 32614
HCP-Version : 6
Compiled on : Atari
@charset    : UTF-8
@lang       : en
@default    : 
@help       : %About
@options    : +g -i -t4 +y +z
@width      : 100
View Ref-FileFsnext()
Fgetdta()
Fsetdta()
Fsfirst()                                                            GEMDOS

Syntax

WORD Fsfirst( fspec, attribs )
char *fspec;
WORD attribs;

Function      Fsfirst() searches the file/pathspec given for the first
              occurrence of a file or subdirectory with named attributes
              and if found, fill in the current DTA with that file's
              information.

Opcode        78 (0x4E)

Availability  All GEMDOS versions.

Parameters    fspec is the GEMDOS file specification of the file or
              subdirectory to search for. This specification may use
              wildcard characters (? or *) within the filename, however
              they may not be used within the pathname. This function is
              the only GEMDOS function which accepts wildcard characters in
              the path specification. attribs is a bit mask which can
              combine several file characteristics that further narrows the
              search as follows:

              Name         Bit     Meaning
                           Mask

              FA_READONLY  0x01    Include files which are read-only.

              FA_HIDDEN    0x02    Include hidden files.

              FA_SYSTEM    0x04    Include system files.

              FA_VOLUME    0x08    Include volume labels.

              FA_DIR       0x10    Include subdirectories.

              FA_ARCHIVE   0x20    Include files with archive bit set.

Binding       move.w   attribs,-(sp)
              pea      fspec
              move.w   #$4E,-(sp)
              trap     #1
              addq.l   #8,sp

Return Value  Fsfirst() returns E_OK (0) if a file was found and the DTA
              was successfully filled in with the file information.
              Otherwise, it returns a negative GEMDOS error code. The DTA
              structure is defined as:

              typedef struct
              {
                BYTE  d_reserved[21];
                BYTE  d_attrib;
                UWORD d_time;
                UWORD d_date;
                LONG  d_length;
                char  d_fname[14];
              } DTA;

Comments      This function uses the application's DTA which is initially
              located in the same memory location as the processes' command
              line. Using this function without first assigning a new DTA
              will corrupt the command line. When running in the MiNT domain
              (see Pdomain()), Fsfirst() and Fsnext() will fill in the DTA
              with lowercase filenames rather than the standard TOS
              uppercase.

See Also      Fsnext(), Fgetdta(), Fsetdta()