_sopen, _wsopen

Abre um arquivo para compartilhamento. Versões mais seguras dessas funções estão disponíveis: confira _sopen_s, _wsopen_s.

Sintaxe

int _sopen(
   const char *filename,
   int oflag,
   int shflag [,
   int pmode ]
);
int _wsopen(
   const wchar_t *filename,
   int oflag,
   int shflag [,
   int pmode ]
);

Parâmetros

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

Cada uma destas funções mostra um descritor de arquivo do arquivo aberto.

Se filename ou oflag for um ponteiro NULL ou se oflag ou shflag não estiver dentro de um intervalo válido de valores, o manipulador de parâmetro inválido será invocado, conforme descrito em Validação de parâmetros. Se a execução puder continuar, essas funções retornarão -1 e definirão errno como um dos valores a seguir.

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 ou shflag inválido.
EMFILE	Nenhum outro descritor de arquivo disponível.
ENOENT	Arquivo ou caminho não encontrado.

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

Comentários

A função _sopen 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 é uma versão de caractere largo da função _sopen; o argumento filename para _wsopen é uma cadeia de caracteres larga. Caso contrário, _wsopen e _sopen 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	_sopen	_sopen	_wsopen

A expressão de inteiro oflag é formada combinando uma ou mais das constantes de manifesto a seguir, as quais 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 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 de constante composta por uma das seguintes constantes de manifesto, 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 só é necessário quando _O_CREAT é especificada. Caso o arquivo não exista, pmode especifica as configurações de permissão do arquivo, que são definidas quando o novo arquivo é 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 aplica a máscara de permissão do arquivo ao argumento pmode antes da definição das permissões. Para obter mais informações, consulte _umask.

Requisitos

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

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