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 |