# NNS_McsFindFirstFile

## Syntax

      #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

Zero if the file search succeeded. A non-zero value otherwise. See Description for details on the possible return values.

## 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 can use the wildcards "`*`" and "`?`" in the filename pattern. You can also include a PC environment variable enclosed in percent signs ("%"), such as `%TWLSYSTEM_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 content of each member is shown below.

`attribute` | File attribute. For details, see below.
`size` | File's size (in bytes).
`name` | 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 you can get with 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

2008/06/20 Changed the environment variable name to `TWLSYSTEM_ROOT`.
2005/01/24 Added descriptions of file attributes and error codes.
2004/10/28 Added description of filename patterns.
2004/10/19 Corrected the link to `NNS_McsCloseFind`.
2004/07/01 Initial version.

CONFIDENTIAL