_makepath_s, _wmakepath_s

Cria um nome de caminho com base nos componentes. Estas funções são versões de _makepath, _wmakepath com aprimoramentos de segurança, conforme descrito em Recursos de segurança no CRT.

Sintaxe

errno_t _makepath_s(
   char *path,
   size_t sizeInBytes,
   const char *drive,
   const char *dir,
   const char *fname,
   const char *ext
);
errno_t _wmakepath_s(
   wchar_t *path,
   size_t sizeInWords,
   const wchar_t *drive,
   const wchar_t *dir,
   const wchar_t *fname,
   const wchar_t *ext
);
template <size_t size>
errno_t _makepath_s(
   char (&path)[size],
   const char *drive,
   const char *dir,
   const char *fname,
   const char *ext
); // C++ only
template <size_t size>
errno_t _wmakepath_s(
   wchar_t (&path)[size],
   const wchar_t *drive,
   const wchar_t *dir,
   const wchar_t *fname,
   const wchar_t *ext
); // C++ only

Parâmetros

path
Buffer de caminho completo.

sizeInWords
O tamanho do buffer em palavras.

sizeInBytes
O tamanho do buffer em bytes.

drive
Contém uma letra (A, B e assim por diante) correspondente à unidade desejada e um sinal de dois pontos opcional à direita. _makepath_s insere os dois-pontos automaticamente no caminho composto se estiver ausente. Se drive for NULL ou apontar para uma cadeia de caracteres vazia, nenhuma letra da unidade aparecerá na cadeia de caracteres de composição path.

dir
Contém o caminho de diretórios, excluindo o designador da unidade ou o nome de arquivo real. A barra à direita é opcional e uma barra (/) ou uma barra invertida (\) ou ambas podem ser usadas em um único dir argumento. Se nenhuma barra final (/ ou \) for especificada, ela será inserida automaticamente. Se dir for NULL ou apontar para uma cadeia de caracteres vazia, nenhum caminho de diretório será inserido na cadeia de caracteres de composição path.

fname
Contém o nome de arquivo base sem qualquer extensão de nome de arquivo. Se fname for NULL ou apontar para uma cadeia de caracteres vazia, nenhum nome de arquivo será inserido na cadeia de caracteres de composição path.

ext
Contém a extensão de nome de arquivo real, com ou sem um ponto à esquerda (.). _makepath_s insere o ponto automaticamente se ele não aparecer em ext. Se ext for NULL ou apontar para uma cadeia de caracteres vazia, nenhuma extensão será inserida na cadeia de caracteres de composição path.

Valor retornado

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

Condições de erro

Se ocorrer qualquer uma das condições de erro acima, essas funções invocarão o manipulador de parâmetro inválido, conforme descrito em Validação de parâmetro. Se a execução tiver permissão para continuar, errno será definido como EINVAL e as funções retornarão EINVAL. NULL tem permissão para os parâmetros drive, fname e ext. Para obter informações sobre o comportamento quando esses parâmetros são ponteiros nulos ou cadeias de caracteres vazias, consulte a seção de Comentários.

Comentários

A função _makepath_s cria uma cadeia de caracteres de caminho de composição com base em componentes individuais e armazena o resultado em path. O path pode incluir uma letra da unidade, caminho de diretório, nome de arquivo e extensão de nome de arquivo. _wmakepath_s é uma versão de caractere largo de _makepath_s; os argumentos para _wmakepath_s são cadeias de caracteres largas. Caso contrário, _wmakepath_s e _makepath_s 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

O argumento path deve apontar para um buffer vazio grande o suficiente para conter o caminho completo. A composição path não deve ser maior do que a constante _MAX_PATH, definida em Stdlib.h.

Se path for NULL, o manipulador de parâmetro inválido será invocado, conforme descrito em Validação de parâmetro. Além disso, errno é definido como EINVAL. Valores NULL são permitidos para todos os outros parâmetros.

Em C++, o uso dessas funções é simplificado pelas sobrecargas de modelo; as sobrecargas podem inferir o tamanho do buffer automaticamente (eliminando a necessidade de especificar um argumento de tamanho) e podem substituir automaticamente funções mais antigas e não seguras por suas equivalentes mais recentes e seguras. 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

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

Exemplo

// crt_makepath_s.c

#include <stdlib.h>
#include <stdio.h>

int main( void )
{
   char path_buffer[_MAX_PATH];
   char drive[_MAX_DRIVE];
   char dir[_MAX_DIR];
   char fname[_MAX_FNAME];
   char ext[_MAX_EXT];
   errno_t err;

   err = _makepath_s( path_buffer, _MAX_PATH, "c", "\\sample\\crt\\",
                      "crt_makepath_s", "c" );
   if (err != 0)
   {
      printf("Error creating path. Error code %d.\n", err);
      exit(1);
   }
   printf( "Path created with _makepath_s: %s\n\n", path_buffer );
   err = _splitpath_s( path_buffer, drive, _MAX_DRIVE, dir, _MAX_DIR, fname,
                       _MAX_FNAME, ext, _MAX_EXT );
   if (err != 0)
   {
      printf("Error splitting the path. Error code %d.\n", err);
      exit(1);
   }
   printf( "Path extracted with _splitpath_s:\n" );
   printf( "   Drive: %s\n", drive );
   printf( "   Dir: %s\n", dir );
   printf( "   Filename: %s\n", fname );
   printf( "   Ext: %s\n", ext );
}

Path created with _makepath_s: c:\sample\crt\crt_makepath_s.c

Path extracted with _splitpath_s:
   Drive: c:
   Dir: \sample\crt\
   Filename: crt_makepath_s
   Ext: .c

Confira também

Manipulação de arquivos
_fullpath, _wfullpath
_splitpath_s, _wsplitpath_s
_makepath, _wmakepath