# NNS_McsFindFirstFile

## C Specification

      #include <nnsys/mcs.h>

      u32 NNS_McsFindFirstFile(
      NNSMcsFile* pFile,
      NNSMcsFileFindData* pFindData,
      const char*         pattern);

## Arguments

pFile | Pointer to the file information structure
pFindData | Pointer to the structure storing the information relating to the found file
pattern | Filename pattern for the search

## Return Values

0 if the file search succeeded. A non-zero value otherwise. The return value is one of the following:

## Description

Searches inside the directory for a file that matches the specified filename pattern. If a matching file is found, the information relating to the first-found match is stored in the `NNSMcsFileFindData` structure variable specified by `pFindData`. To search among remaining files, call the `NNS_McsFindNextFile` function. To end the search, call the `NNS_McsCloseFind` function.

You may include the wildcards "`*`" and "`?`" in the file name pattern. You may also include a PC environment variable enclosed in "`%`" characters, such as `%NITROSYSTEM_ROOT%\include\*.h`.

The `NNSMcsFileFindData` structure is defined as shown below.

      #define NNS_MCS_FILEIO_PATH_MAX 260

      typedef struct NNSMcsFileFindData NNSMcsFileFindData;
      struct NNSMcsFileFindData
      {
      u32         attribute;
      u32                 size;
      char        name[NNS_MCS_FILEIO_PATH_MAX
      };

The contents of each member is shown below:

attribute | The file's attribute For details, see the following:
size | The file's size (in bytes)
`name` | The filename

The file attributes are the combinations of the following values:

NNS_MCS_FILEIO_ATTRIBUTE_DIRECTORY | Directory
NNS_MCS_FILEIO_ATTRIBUTE_ARCHIVE | Archive
NNS_MCS_FILEIO_ATTRIBUTE_READONLY | Read only
NNS_MCS_FILEIO_ATTRIBUTE_HIDDEN | Hidden file
NNS_MCS_FILEIO_ATTRIBUTE_SYSTEM | System file
NNS_MCS_FILEIO_ATTRIBUTE_NORMAL | File without attribute

The return value takes one of the following values:

`NNS_MCS_FILEIO_ERROR_SUCCESS` (0) | The function was successful.
NNS_MCS_FILEIO_ERROR_COMERROR | A communications error occurred.
NNS_MCS_FILEIO_ERROR_NOTCONNECT | Not connected to the mcs server.
NNS_MCS_FILEIO_ERROR_SERVERERROR | A error has occurred due to a file operation on the mcs server side. The error code is a Win32 system error code that can be obtained using the `NNS_McsGetServerErrorCode` function.
NNS_MCS_FILEIO_ERROR_NOMOREFILES | File that matches the pattern cannot be found.

## See Also

`NNS_McsFindNextFile, NNS_McsCloseFind`

## Revision History

01/24/2005 Added the description regarding file attribute and error code.
10/28/2004 Added a description concerning file name patterns.
10/19/2004 Corrected the link to `NNS_McsCloseFind`
07/01/2004 Initial version.