_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.

errno valor	Condição
EACCES	O caminho determinado é um diretório ou o arquivo é somente leitura, mas foi realizada uma tentativa de operação de abertura para gravação.
EEXIST	Sinalizadores _O_CREAT e _O_EXCL foram especificados, mas filename já existe.
EINVAL	Argumento oflag, shflag ou pmode inválido, ou pfh ou filename é um ponteiro nulo.
EMFILE	Nenhum outro descritor de arquivo disponível.
ENOENT	Arquivo ou caminho não encontrado.

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

Rotina Tchar.h	_UNICODE e _MBCS não definidos	_MBCS definido	_UNICODE definido
_tsopen_s	_sopen_s	_sopen_s	_wsopen_s

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 (|).

Constante oflag	Comportamento
_O_APPEND	Move o ponteiro para o final do arquivo antes de cada operação de gravação.
_O_BINARY	Abre o arquivo no modo binário (sem conversão). (Confira fopen para ver uma descrição do modo binário.)
_O_CREAT	Cria um arquivo e o abre para gravação. Não terá efeito algum se o arquivo especificado por filename já existir. O argumento pmode é necessário quando _O_CREAT é especificada.
_O_CREAT | _O_SHORT_LIVED	Cria um arquivo temporário e, se possível, não libera para o disco. O argumento pmode é necessário quando _O_CREAT é especificada.
_O_CREAT | _O_TEMPORARY	Cria um arquivo temporário, que é excluído quando o último descritor de arquivo é fechado. O argumento pmode é necessário quando _O_CREAT é especificada. Para preservar o comportamento herdado para a compatibilidade do aplicativo, outros processos não são impedidos de excluir esse arquivo.
_O_CREAT | _O_EXCL	Retorna um valor de erro se o arquivo especificado por filename existir. Aplica-se somente quando usado com _O_CREAT.
_O_NOINHERIT	Impede a criação de um descritor de arquivo compartilhado.
_O_RANDOM	Especifica que o cache é otimizado para acesso aleatório do disco, mas não se restringe a isso.
_O_RDONLY	Abre um arquivo somente leitura. Não pode ser especificado com _O_RDWR ou _O_WRONLY.
_O_RDWR	Abre um arquivo para leitura e gravação. Não pode ser especificado com _O_RDONLY ou _O_WRONLY.
_O_SEQUENTIAL	Especifica que o cache é otimizado para acesso sequencial do disco, mas não se restringe a isso.
_O_TEXT	Abre um arquivo no modo de texto ANSI (traduzido). (Para saber mais, confira E/S de arquivo nos modos de texto e binário e fopen.)
_O_TRUNC	Abre um arquivo e o trunca para que ele fique com tamanho zero; o arquivo deve ter permissão de gravação. Não pode ser especificado com _O_RDONLY. A constante _O_TRUNC, usada com a constante _O_CREAT, abre um arquivo existente ou cria um. Observação: o sinalizador _O_TRUNC destrói o conteúdo do arquivo especificado.
_O_WRONLY	Abre um arquivo somente gravação. Não pode ser especificado com _O_RDONLY ou _O_RDWR.
_O_U16TEXT	Abre um arquivo no modo Unicode UTF-16.
_O_U8TEXT	Abre um arquivo no modo Unicode UTF-8.
_O_WTEXT	Abre um arquivo no modo Unicode.

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>.

Constante shflag	Comportamento
_SH_DENYRW	Nega acesso de leitura e gravação a um arquivo.
_SH_DENYWR	Nega acesso de gravação a um arquivo.
_SH_DENYRD	Nega acesso de leitura a um arquivo.
_SH_DENYNO	Permite acesso de leitura e gravação.

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.

pmode	Significado
_S_IREAD	Somente a leitura é permitida.
_S_IWRITE	Gravação permitida. (Na verdade, permite leitura e gravação.)
_S_IREAD | _S_IWRITE	Leitura e gravação permitidas.

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

Função	Cabeçalho necessário	Cabeçalho opcional
_sopen_s	<io.h>	<fcntl.h>, <sys\types.h>, <sys\stat.h>, <share.h>
_wsopen_s	<io.h> ou <wchar.h>	<fcntl.h>, <sys/types.h>, <sys/stat.h>, <share.h>

_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