_sopen_s, _wsopen_s

Abre um arquivo para compartilhamento. Essas versões e _wsopentêm aprimoramentos de _sopen segurança, conforme descrito em Recursos de segurança no CRT.

Sintaxe

errno_t _sopen_s(
   int* pfh,
   const char *filename,
   int oflag,
   int shflag,
   int pmode
);
errno_t _wsopen_s(
   int* pfh,
   const wchar_t *filename,
   int oflag,
   int shflag,
   int pmode,
);

Parâmetros

pfh
O identificador de arquivo ou -1 se houver um erro.

filename
Nome do arquivo.

oflag
Os tipos de operações permitidas.

shflag
O tipo de compartilhamento permitido.

pmode
Configuração de permissão.

Valor retornado

Um valor retornado diferente de zero indica um erro; nesse caso, errno é configurado com um dos seguintes valores.

Se um argumento inválido for passado para a função, o manipulador de parâmetro inválido será invocado, como descrito em Validação de parâmetro. Se a execução tiver permissão para continuar, errno será definido como EINVALe EINVAL será retornado.

Para obter mais informações sobre esses e outros códigos de retorno, confira errno, _doserrno, _sys_errlist e _sys_nerr.

Em caso de erro, -1 é retornado por pfh (a menos que pfh seja um ponteiro nulo).

Comentários

A função _sopen_s abre o arquivo especificado por filename e prepara o arquivo para leitura ou gravação compartilhada, como definido por oflag e shflag. A função _wsopen_s é uma versão de caractere largo da função _sopen_s; o argumento filename para _wsopen_s é uma cadeia de caracteres larga. Caso contrário, _wsopen_s e _sopen_s se comportam de forma idêntica.

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

Mapeamentos de rotina de texto genérico

A expressão de número inteiro oflag é formada combinando uma ou mais constantes de manifesto, que são definidas em <fcntl.h>. Quando duas ou mais constantes formam o argumento oflag, elas são combinadas com o operador OR bit a bit (|).

Para especificar o modo de acesso ao arquivo, você deve especificar _O_RDONLY, _O_RDWR ou _O_WRONLY. Não há valor padrão para o modo de acesso.

Quando o arquivo é aberto no modo Unicode com a constante _O_WTEXT, _O_U8TEXT ou _O_U16TEXT, as funções de entrada convertem os dados do arquivo em dados UTF-16 armazenados como tipo wchar_t. Funções que gravam em arquivos abertos no modo Unicode esperam buffers que contenham dados UTF-16 armazenados como tipo wchar_t. Se o arquivo estiver codificado como UTF-8, os dados em UTF-16 serão convertidos em UTF-8 no momento da gravação. O conteúdo codificado em UTF-8 do arquivo é convertido para UTF-16 quando ele é lido. Tentar ler ou gravar uma quantidade ímpar de bytes no modo Unicode gera um erro de validação de parâmetro. Para ler ou gravar dados armazenados em seu programa como UTF-8, use um modo de arquivo de texto ou binário em vez do modo Unicode. Você é responsável por toda a conversão de codificação necessária.

Se _sopen_s for chamado com _O_WRONLY | _O_APPEND (modo de acréscimo) e _O_WTEXT, _O_U16TEXT ou _O_U8TEXT, ele primeiro tentará abrir o arquivo para leitura e gravação, lerá a BOM e, em seguida, reabrirá o arquivo somente para gravação. Se uma falha impedir de abrir o arquivo para leitura e gravação, ele será aberto somente para gravação e usará o valor padrão na configuração do modo Unicode.

O argumento shflag é uma expressão constante formada por uma das constantes de manifesto a seguir, definidas em <share.h>.

O argumento pmode é sempre necessário, ao contrário de _sopen. Ao especificar _O_CREAT, se o arquivo não existir, pmode especificará as configurações de permissão do arquivo, que serão definidas quando o novo arquivo for fechado pela primeira vez. Caso contrário, pmode é ignorado. pmode é uma expressão de inteiro que contém uma ou as duas constantes de manifesto _S_IWRITE e _S_IREAD, que são definidas em <sys\stat.h>. Quando ambas as constantes são fornecidas, elas são combinadas com o operador OR bit a bit. O significado de pmode é o seguinte.

Se a permissão de gravação não for concedida, o arquivo será somente leitura. No sistema operacional Windows, todos os arquivos podem ser lidos, não sendo possível conceder permissão de somente gravação. Portanto, os modos _S_IWRITE e _S_IREAD | _S_IWRITE são equivalentes.

A função _sopen_s aplica a máscara de permissão do arquivo ao argumento pmode antes da definição das permissões. (Consulte _umask.)

Requisitos

_sopen_s e _wsopen_s são extensões da Microsoft. Para obter informações sobre compatibilidade, consulte Compatibilidade.

Exemplo

Confira o exemplo de _locking.

Confira também

E/S de baixo nível
_close
_creat, _wcreat
fopen, _wfopen
_fsopen, _wfsopen
_open, _wopen