_splitpath_s, _wsplitpath_s

Artigo
02/25/2013

Divide um nome de caminho em componentes.Estas são as versões do _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

[in]path
Caminho completo.
[out]drive
Letra, seguida de dois pontos da unidade (:).Você pode passar NULL para esse parâmetro se você não precisar a letra da unidade.
[in]driveNumberOfElements
O tamanho da drive buffer em caracteres de byte único ou de longa distância.Se drive é NULL, esse valor deve ser 0.
[out]dir
Caminho do diretório, incluindo a barra à direita.Barras ( / ), barras invertidas ( \ ), ou ambos podem ser usados.Você pode passar NULL para esse parâmetro se você não precisar o caminho do diretório.
[in]dirNumberOfElements
O tamanho da dir buffer em caracteres de byte único ou de longa distância.Se dir é NULL, esse valor deve ser 0.
[out]fname
Nome do arquivo base (sem extensão).Você pode passar NULL para esse parâmetro se você não precisar o nome do arquivo.
[in]nameNumberOfElements
O tamanho da fname buffer em caracteres de byte único ou de longa distância.Se fname é NULL, esse valor deve ser 0.
[out]ext
Extensão de nome de arquivo, incluindo líderes de período (.).Você pode passar NULL para esse parâmetro se você não precisar a extensão de nome de arquivo.
[in]extNumberOfElements
O tamanho do ext buffer em caracteres de byte único ou de longa distância.Se ext é NULL, esse valor deve ser 0.

Valor de retorno

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

Condições de erro

Condição	Valor de retorno
pathé NULL	EINVAL
driveis NULL, driveNumberOfElements is non-zero	EINVAL
driveis non-NULL, driveNumberOfElements is zero	EINVAL
diris NULL, dirNumberOfElements is non-zero	EINVAL
diris non-NULL, dirNumberOfElements is zero	EINVAL
fnameis NULL, nameNumberOfElements is non-zero	EINVAL
fnameis non-NULL, nameNumberOfElements is zero	EINVAL
extis NULL, extNumberOfElements is non-zero	EINVAL
extis non-NULL, extNumberOfElements is zero	EINVAL

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

Se qualquer um dos buffers for muito pequeno para reter o resultado, essas funções limpar todos os buffers para esvaziar as cadeias de caracteres, defina errno para ERANGEe retornar ERANGE.

Comentários

O _splitpath_s função divide um caminho em quatro componentes._splitpath_s manipula automaticamente os argumentos de seqüência de caracteres multibyte conforme apropriado, reconhecendo as seqüências de caracteres multibyte de acordo com para a página de código multibyte atualmente em uso._wsplitpath_s é uma versão de caractere largo de _splitpath_s; os argumentos para _wsplitpath_ssão seqüências de caracteres largos.Essas funções se comportam exatamente caso contrário

Mapeamentos de rotina de texto genérico

TCHAR.Rotina H	_ Unicode & _ MBCS do arquivo não definido	_ MBCS do arquivo 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 (definido em STDLIB.H) Especifica o tamanho máximo permitido para cada componente do arquivo.Componentes de arquivo maior do que as constantes de manifesto correspondentes causam corrupção de heap.

A tabela a seguir lista os valores das constantes 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 atribui uma seqüência vazia para o buffer correspondente.

No C++, a utilização dessas funções é simplificado pela sobrecargas do modelo; os métodos sobrecarregados podem inferir comprimento do buffer automaticamente, eliminando a necessidade de especificar um argumento de tamanho.Para obter mais informações, consulte Proteger Overloads de modelo.

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