Compartilhar via


Função SearchPathA (processenv.h)

Procura 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 a ser pesquisado.

Por padrão, o nome é limitado a caracteres MAX_PATH. Para estender esse limite para 32.767 caracteres largos, preencha "\\?\" para o caminho. Para obter mais informações, confira Nomear arquivos, caminhos e namespaces.

Dica

A partir do Windows 10, versão 1607, você pode optar por remover a limitação de MAX_PATH sem acrescentar "\\?\". Consulte a seção "Limitação máxima de comprimento do caminho" de Arquivos de Nomenclatura, Caminhos e Namespaces para obter detalhes.

[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 ponto (.). 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 (dentro de 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.

Retornar valor

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.

Comentários

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

HKEY_LOCAL_MACHINE\SISTEMA\Currentcontrolset\Controle\Gerenciador de\ SessãoSafeProcessSearchMode

Quando o valor desse REG_DWORD valor do Registro é definido como 1, o SearchPath pesquisa primeiro as pastas especificadas no caminho do sistema e pesquisa a pasta de trabalho atual. Quando o valor desse valor do Registro é definido como 0, o computador pesquisa primeiro a pasta de trabalho atual e 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 Windows Server 2012, essa função é compatível com as tecnologias a seguir.

Tecnologia Com suporte
Protocolo SMB (SMB) 3.0 Sim
TFO (Failover transparente) do SMB 3.0 Sim
SMB 3.0 com compartilhamentos de arquivos de expansão (SO) Sim
Sistema de arquivos de Volume Compartilhado Clusterizado (CsvFS) Sim
ReFS (Sistema de Arquivos Resiliente) Sim
 

Observação

O cabeçalho processenv.h define SearchPath como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows XP [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho processenv.h (inclua Windows.h)
Biblioteca Kernel32.lib
DLL Kernel32.dll

Confira também

Funções de gerenciamento de arquivos

FindFirstFile

FindNextFile

Getsystemdirectory

Getwindowsdirectory

SetSearchPathMode