Função SearchPathA (processenv.h)

Pesquisa um arquivo especificado em um caminho especificado.

Sintaxe

DWORD SearchPathA(
  [in, optional]  LPCSTR lpPath,
  [in]            LPCSTR lpFileName,
  [in, optional]  LPCSTR lpExtension,
  [in]            DWORD  nBufferLength,
  [out]           LPSTR  lpBuffer,
  [out, optional] LPSTR  *lpFilePart
);

Parâmetros

[in, optional] lpPath

O caminho a ser pesquisado para o arquivo.

Se esse parâmetro for NULL, a função procurará um arquivo correspondente usando um caminho de pesquisa do sistema dependente do registro. Para obter mais informações, consulte a seção Comentários.

[in] lpFileName

O nome do arquivo para o qual pesquisar.

Por padrão, o nome é limitado a MAX_PATH caracteres. Para estender esse limite para 32.767 caracteres de largura, acrescente "\\?\" ao caminho. Para obter mais informações, consulte Arquivos de Nomenclatura, Caminhos e Namespaces.

[in, optional] lpExtension

A extensão a ser adicionada ao nome do arquivo ao pesquisar o arquivo. O primeiro caractere da extensão de nome de arquivo deve ser um período (.). A extensão será adicionada somente se o nome do arquivo especificado não terminar com uma extensão.

Se uma extensão de nome de arquivo não for necessária ou se o nome do arquivo contiver uma extensão, esse parâmetro poderá ser NULL.

[in] nBufferLength

O tamanho do buffer que recebe o caminho válido e o nome do arquivo (incluindo o caractere nulo de terminação), em TCHARs.

[out] lpBuffer

Um ponteiro para o buffer para receber o caminho e o nome do arquivo encontrado. A cadeia de caracteres é uma cadeia de caracteres terminada em nulo.

[out, optional] lpFilePart

Um ponteiro para a variável para receber o endereço (em lpBuffer) do último componente do caminho válido e do nome do arquivo, que é o endereço do caractere imediatamente após a barra invertida final (\) no caminho.

Valor de retorno

Se a função for bem-sucedida, o valor retornado será o comprimento, em TCHARs, da cadeia de caracteres copiada para o buffer, não incluindo o caractere nulo de terminação. Se o valor retornado for maior que nBufferLength, o valor retornado será o tamanho do buffer necessário para manter o caminho, incluindo o caractere nulo de terminação.

Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError.

Observações

Se o parâmetro lpPath for NULL, SearchPath procurará um arquivo correspondente com base no valor atual do seguinte valor do Registro:

HKEY_LOCAL_MACHINECurrentControlSetSession ManagerSafeProcessSearchMode

Quando o valor desse REG_DWORD valor do Registro é definido como 1, SearchPath primeiro pesquisa as pastas especificadas no caminho do sistema e, em seguida, pesquisa a pasta de trabalho atual. Quando o valor desse valor do Registro é definido como 0, o computador primeiro pesquisa a pasta de trabalho atual e, em seguida, pesquisa as pastas especificadas no caminho do sistema. O valor padrão do sistema para essa chave do Registro é 0.

O modo de pesquisa usado pela função SearchPath também pode ser definido por processo chamando a função SetSearchPathMode.

A função SearchPath não é recomendada como um método de localizar um arquivo .dll se o uso pretendido da saída estiver em uma chamada para a função LoadLibrary. Isso pode resultar na localização do arquivo de .dll errado porque a ordem de pesquisa da função SearchPath difere da ordem de pesquisa usada pela função LoadLibrary. Se você precisar localizar e carregar um arquivo .dll, use a função LoadLibrary.

No Windows 8 e no Windows Server 2012, essa função é compatível com as tecnologias a seguir.

Requisitos

Consulte também

Funções de gerenciamento de arquivos

FindFirstFile

FindNextFile

GetSystemDirectory

GetWindowsDirectory

SetSearchPathMode