Compartilhar via

_splitpath_s, _wsplitpath_s

  • Artigo

Divide um nome de caminho em componentes. Estas funções são versões de _splitpath, _wsplitpath com aprimoramentos de segurança, conforme descrito em Recursos de segurança no CRT.

Sintaxe

errno_t _splitpath_s(
   const char * path,
   char * drive,
   size_t driveNumberOfElements,
   char * dir,
   size_t dirNumberOfElements,
   char * fname,
   size_t nameNumberOfElements,
   char * ext,
   size_t extNumberOfElements
);
errno_t _wsplitpath_s(
   const wchar_t * path,
   wchar_t * drive,
   size_t driveNumberOfElements,
   wchar_t *dir,
   size_t dirNumberOfElements,
   wchar_t * fname,
   size_t nameNumberOfElements,
   wchar_t * ext,
   size_t extNumberOfElements
);
template <size_t drivesize, size_t dirsize, size_t fnamesize, size_t extsize>
errno_t _splitpath_s(
   const char *path,
   char (&drive)[drivesize],
   char (&dir)[dirsize],
   char (&fname)[fnamesize],
   char (&ext)[extsize]
); // C++ only
template <size_t drivesize, size_t dirsize, size_t fnamesize, size_t extsize>
errno_t _wsplitpath_s(
   const wchar_t *path,
   wchar_t (&drive)[drivesize],
   wchar_t (&dir)[dirsize],
   wchar_t (&fname)[fnamesize],
   wchar_t (&ext)[extsize]
); // C++ only

Parâmetros

path
Caminho completo.

drive
Letra da unidade, seguida por dois pontos (:). Você pode passar NULL por esse parâmetro se não precisar da letra da unidade.

driveNumberOfElements
O tamanho do buffer drive em caracteres de byte único ou largos. Se drive é NULL, esse valor deve ser 0.

dir
Caminho do diretório, incluindo barra à direita. Barras duplas (/), barras invertidas (\\) ou ambas podem ser usadas. Você pode passar NULL por esse parâmetro se não precisar do caminho do diretório.

dirNumberOfElements
O tamanho do buffer dir em caracteres de byte único ou largos. Se dir é NULL, esse valor deve ser 0.

fname
Nome de arquivo base (sem extensão). Você pode passar NULL para este parâmetro se não precisar do nome do arquivo.

nameNumberOfElements
O tamanho do buffer fname em caracteres de byte único ou largos. Se fname é NULL, esse valor deve ser 0.

ext
Extensão de nome de arquivo, incluindo ponto à esquerda (.). Você pode passar NULL por este parâmetro se não precisar da extensão do nome do arquivo.

extNumberOfElements
O tamanho do buffer ext em caracteres de byte único ou largos. Se ext é NULL, esse valor deve ser 0.

Valor retornado

Zero se for bem-sucedido; um código de erro em caso de falha.

Condições de erro

Condição Valor retornado
path é NULL EINVAL
drive é NULL, driveNumberOfElements é diferente de zero EINVAL
drive é diferente de NULL, driveNumberOfElements é zero EINVAL
dir é NULL, dirNumberOfElements é diferente de zero EINVAL
dir é diferente de NULL, dirNumberOfElements é zero EINVAL
fname é NULL, nameNumberOfElements é diferente de zero EINVAL
fname é diferente de NULL, nameNumberOfElements é zero EINVAL
ext é NULL, extNumberOfElements é diferente de zero EINVAL
ext é diferente de NULL, extNumberOfElements é zero EINVAL

Se qualquer uma das condições acima ocorrer, o manipulador de parâmetro inválido será invocado, conforme descrito em Validação de parâmetro. Se a execução tiver permissão para continuar, essas funções definirão errno como EINVAL e retornarão EINVAL.

Se qualquer um dos buffers é curto demais para conter o resultado, essas funções limpam todos os buffers para cadeias de caracteres vazias, definem errno como ERANGE e retornam ERANGE.

Comentários

A função _splitpath_s divide um caminho em seus quatro componentes. _splitpath_s manipula automaticamente argumentos de cadeia de caracteres multibyte conforme apropriado, reconhecendo sequências de caracteres multibyte de acordo com a página de código multibyte que está sendo usada no momento. _wsplitpath_s é uma versão de caractere largo de _splitpath_s; os argumentos para _wsplitpath_s são cadeias de caracteres largas. Caso contrário, essas funções se comportam de forma idêntica

Por padrão, o estado global dessa função tem como escopo o aplicativo. Para alterar esse comportamento, confira Estado global no CRT.

Mapeamentos de rotina de texto genérico

Rotina TCHAR.H _UNICODE e _MBCS não definidos _MBCS definido _UNICODE definido
_tsplitpath_s _splitpath_s _splitpath_s _wsplitpath_s

Cada componente do caminho completo é armazenado em um buffer separado; as constantes de manifesto _MAX_DRIVE, _MAX_DIR, _MAX_FNAME e _MAX_EXT (definidas em STDLIB.H) especificam o tamanho máximo permitido para cada componente de arquivo. Componentes de arquivo maiores do que as constantes de manifesto correspondentes causam corrupção de heap.

A tabela a seguir lista os valores das constantes do manifesto.

Nome Valor
_MAX_DRIVE 3
_MAX_DIR 256
_MAX_FNAME 256
_MAX_EXT 256

Se o caminho completo não contiver um componente (por exemplo, um nome de arquivo), _splitpath_s atribuirá uma cadeia de caracteres vazia ao buffer correspondente.

No C++, o uso dessas funções é simplificado por sobrecargas de modelo. As sobrecargas podem inferir automaticamente o tamanho do buffer, eliminando a necessidade de especificar um argumento de tamanho. Para obter mais informações, consulte Sobrecargas de modelo seguras.

As versões de biblioteca de depuração dessas funções preenchem o buffer com 0xFE. Para desabilitar esse comportamento, use _CrtSetDebugFillThreshold.

Requisitos

Rotina Cabeçalho necessário
_splitpath_s <stdlib.h>
_wsplitpath_s <stdlib.h> ou <wchar.h>

Para obter informações sobre compatibilidade, consulte Compatibilidade.

Exemplo

Confira o exemplo de _makepath_s, _wmakepath_s.

Confira também

Manipulação de arquivos
_splitpath, _wsplitpath
_fullpath, _wfullpath
_getmbcp
_makepath, _wmakepath
_setmbcp