_creat、_wcreat_creat, _wcreat

新建文件。Creates a new file. 已不推荐使用 _creat_wcreat ;改用_sopen_s、_wsopen_s_creat and _wcreat have been deprecated; use _sopen_s, _wsopen_s instead.

语法Syntax

int _creat(
   const char *filename,
   int pmode
);
int _wcreat(
   const wchar_t *filename,
   int pmode
);

参数Parameters

filenamefilename
新文件的名称。Name of new file.

pmodepmode
权限设置。Permission setting.

返回值Return Value

如果成功,则这些函数将文件描述符返回到已创建文件。These functions, if successful, return a file descriptor to the created file. 否则,函数将返回-1 并设置errno ,如下表所示。Otherwise, the functions return -1 and set errno as shown in the following table.

errno设置errno setting 描述Description
EACCESEACCES filename指定现有的只读文件,或者指定目录而不是文件。filename specifies an existing read-only file or specifies a directory instead of a file.
EMFILEEMFILE 没有更多可用的文件描述符。No more file descriptors are available.
ENOENTENOENT 找不到指定的文件。Specified file could not be found.

如果filenameNULL,则这些函数将调用无效参数处理程序,如参数验证中所述。If filename is NULL, these functions invoke the invalid parameter handler, as described in Parameter Validation. 如果允许执行继续, 则这些函数会将errno设置为EINVAL , 并返回-1。If execution is allowed to continue, these functions set errno to EINVAL and return -1.

有关这些属性和其他的更多信息返回代码示例,请参见 _doserrno、errno、_sys_errlist 和 _sys_nerrFor more information about these and other return codes, see _doserrno, errno, _sys_errlist, and _sys_nerr.

备注Remarks

_Creat函数将创建一个新文件,或者打开并截断现有文件。The _creat function creates a new file or opens and truncates an existing one. _wcreat_creat的宽字符版本; _wcreatfilename参数是宽字符字符串。_wcreat is a wide-character version of _creat; the filename argument to _wcreat is a wide-character string. 否则, _wcreat_creat的行为相同。_wcreat and _creat behave identically otherwise.

一般文本例程映射Generic-Text Routine Mappings

Tchar.h 例程Tchar.h routine 未定义 _UNICODE 和 _MBCS_UNICODE and _MBCS not defined 已定义 _MBCS_MBCS defined 已定义 _UNICODE_UNICODE defined
_tcreat_tcreat _creat_creat _creat_creat _wcreat_wcreat

如果filename指定的文件不存在,则将使用给定的权限设置创建一个新文件,并打开该文件以进行写入。If the file specified by filename does not exist, a new file is created with the given permission setting and is opened for writing. 如果该文件已存在并且其权限设置允许写入,则 _creat会将该文件截断到 length 0,销毁以前的内容,然后将其打开以进行写入。If the file already exists and its permission setting allows writing, _creat truncates the file to length 0, destroying the previous contents, and opens it for writing. 权限设置pmode仅适用于新创建的文件。The permission setting, pmode, applies to newly created files only. 新文件第一次关闭后收到指定的权限设置。The new file receives the specified permission setting after it is closed for the first time. 整数表达式pmode包含一个或两个清单常量 _S_IWRITE_S_IREAD,在 sys\stat.h 中定义。The integer expression pmode contains one or both of the manifest constants _S_IWRITE and _S_IREAD, defined in SYS\Stat.h. 当同时提供两个常量时,它们将与按位 or 运算符 | ()联接。When both constants are given, they are joined with the bitwise or operator ( | ). Pmode参数设置为以下值之一。The pmode parameter is set to one of the following values.

Value 定义Definition
_S_IWRITE_S_IWRITE 允许写入。Writing permitted.
_S_IREAD_S_IREAD 允许读取。Reading permitted.
_S_IREAD | _S_IWRITE_S_IREAD | _S_IWRITE 允许读取和写入。Reading and writing permitted.

如果未授予写入权限,则该文件为只读。If write permission is not given, the file is read-only. 所有文件始终具有可读性;不能提供只写权限。All files are always readable; it is impossible to give write-only permission. _S_IWRITE_S_IREAD | _S_IWRITE模式是等效的。The modes _S_IWRITE and _S_IREAD | _S_IWRITE are then equivalent. 使用 _creat打开的文件始终以兼容模式打开(请参阅_Sopen)和 _SH_DENYNOFiles opened using _creat are always opened in compatibility mode (see _sopen) with _SH_DENYNO.

在设置权限之前, _creat会将当前文件权限掩码应用到pmode (请参阅_umask)。_creat applies the current file-permission mask to pmode before setting the permissions (see _umask). 提供 _creat主要是为了与以前的库兼容。_creat is provided primarily for compatibility with previous libraries. oflag参数中对 _open使用 _O_CREAT_O_TRUNC的调用等效于 _creat ,并且更适用于新代码。A call to _open with _O_CREAT and _O_TRUNC in the oflag parameter is equivalent to _creat and is preferable for new code.

要求Requirements

例程所返回的值Routine 必需的标头Required header 可选标头Optional header
_creat_creat <io.h><io.h> <sys/types.h>、<sys/stat.h>、<errno.h><sys/types.h>, <sys/stat.h>, <errno.h>
_wcreat_wcreat <io.h> 或 <wchar.h><io.h> or <wchar.h> <sys/types.h>、<sys/stat.h>、<errno.h><sys/types.h>, <sys/stat.h>, <errno.h>

有关更多兼容性信息,请参阅 兼容性For more compatibility information, see Compatibility.

示例Example

// crt_creat.c
// compile with: /W3
// This program uses _creat to create
// the file (or truncate the existing file)
// named data and open it for writing.

#include <sys/types.h>
#include <sys/stat.h>
#include <io.h>
#include <stdio.h>
#include <stdlib.h>

int main( void )
{
   int fh;

   fh = _creat( "data", _S_IREAD | _S_IWRITE ); // C4996
   // Note: _creat is deprecated; use _sopen_s instead
   if( fh == -1 )
      perror( "Couldn't create data file" );
   else
   {
      printf( "Created data file.\n" );
      _close( fh );
   }
}
Created data file.

请参阅See also

低级别 I/OLow-Level I/O
_chmod、_wchmod_chmod, _wchmod
_chsize_chsize
_close_close
_dup、_dup2_dup, _dup2
_open、_wopen_open, _wopen
_sopen、_wsopen_sopen, _wsopen
_umask_umask