_splitpath_s, _wsplitpath_s

Artigo
06/09/2015

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

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

[entrada] path
Caminho completo.
[saída] drive
Letra de unidade, seguido por dois-pontos (:). Você pode passar NULL para este parâmetro se você não precisar mais da letra da unidade.
[entrada] driveNumberOfElements
O tamanho do buffer de drive em um byte ou em caracteres amplos. Se drive é NULL, este valor deve ser 0.
[saída] dir
Caminho de diretório, inclusive a barra à direita. As barras ( / ), as barras invertidas ( \ ), ou ambos podem ser usadas. Você pode passar NULL para este parâmetro se você não precisa do caminho de diretório.
[entrada] dirNumberOfElements
O tamanho do buffer de dir em um byte ou em caracteres amplos. Se dir é NULL, este valor deve ser 0.
[saída] fname
Nome de arquivo base (sem a extensão). Você pode passar NULL para este parâmetro se você não precisa do nome de arquivo.
[entrada] nameNumberOfElements
O tamanho do buffer de fname em um byte ou em caracteres amplos. Se fname é NULL, este valor deve ser 0.
[saída] ext
Extensão de nome de arquivo, incluindo período principal (.). Você pode passar NULL para este parâmetro se você não precisar mais da extensão de nome de arquivo.
[entrada] extNumberOfElements
O tamanho do buffer de ext em um byte ou em caracteres amplos. Se ext é NULL, este valor deve ser 0.

Valor de retorno

Zero se tiver êxito; um código de erro em falha.

Condições de erro

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

Se qualquer uma das condições anteriores ocorrerem, o manipulador inválido do parâmetro será chamado, conforme descrito em Validação do parâmetro . Se a execução puder continuar, essas funções definirão errno como EINVAL e retornarão EINVAL.

Se algum dos buffers são muito curtos manter o resultado, essas funções desmarque todos os buffers em cadeias de caracteres vazias, definem errno a ERANGE, e o retorno ERANGE.

Comentários

A função de _splitpath_s interrompe um caminho nos quatro componentes. _splitpath_s controla automaticamente argumentos de cadeia de caracteres de multibyte- caracteres conforme apropriado, confirmando sequências de multibyte- caractere de acordo com a página de código de multibyte atualmente em uso. _wsplitpath_s é uma versão de ampla caractere de _splitpath_s; os argumentos a _wsplitpath_ssão cadeias de caracteres de ampla caractere. Essas funções se comportam de outra forma idêntica

Mapeamentos da rotina de texto genérico

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

Cada componente do caminho completo é armazenado em um buffer separado; as constantes manifestas _MAX_DRIVE, _MAX_DIR, _MAX_FNAME, e _MAX_EXT () definido em STDLIB.H especificar o tamanho máximo permitido para cada componente do arquivo. Arquivo dos componentes maiores que o dano manifesto correspondente do heap da causa das constantes.

A tabela a seguir lista os valores de constantes manifestas.

Nome	Valor
_MAX_DRIVE	3
_MAX_DIR	256
_MAX_FNAME	256
_MAX_EXT	256

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

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

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