man/man2/creat.2

   1 .\" Copyright (c) 1980 Regents of the University of California.
   2 .\" All rights reserved.  The Berkeley software License Agreement
   3 .\" specifies the terms and conditions for redistribution.
   4 .\"
   5 .\"     @(#)creat.2     6.6 (Berkeley) 5/22/86
   6 .\"
   7 .TH CREAT 2 "May 22, 1986"
   8 .UC 4
   9 .SH NAME
  10 creat \- create a new file
  11 .SH SYNOPSIS
  12 .nf
  13 .ft B
  14 #include <sys/types.h>
  15 #include <fcntl.h>
  16
  17 int creat(const char *\fIname\fP, mode_t \fImode\fP)
  18 .ft R
  19 .fi
  20 .SH DESCRIPTION
  21 .ft B
  22 This interface is made obsolete by open(2), it is equivalent to
  23 .ft R
  24 .PP
  25 .RS
  26 open(\fIname\fP, O_WRONLY | O_CREAT | O_TRUNC, \fImode\fP)
  27 .RE
  28 .PP
  29 .B Creat
  30 creates a new file or prepares to rewrite an existing
  31 file called
  32 .IR name ,
  33 given as the address of a null-terminated string.
  34 If the file did not exist, it is given
  35 mode
  36 .IR mode ,
  37 as modified by the process's mode mask (see
  38 .BR umask (2)).
  39 Also see
  40 .BR chmod (2)
  41 for the
  42 construction of the
  43 .I mode
  44 argument.
  45 .PP
  46 If the file did exist, its mode and owner remain unchanged
  47 but it is truncated to 0 length.
  48 .PP
  49 The file is also opened for writing, and its file descriptor
  50 is returned.
  51 .SH NOTES
  52 The
  53 .I mode
  54 given is arbitrary; it need not allow
  55 writing.
  56 This feature has been used in the past by
  57 programs to construct a simple, exclusive locking
  58 mechanism.  It is replaced by the O_EXCL open
  59 mode, or the advisory locking of the
  60 .BR fcntl (2)
  61 facility.
  62 .SH "RETURN VALUE
  63 The value \-1 is returned if an error occurs.  Otherwise,
  64 the call returns a non-negative descriptor that only permits
  65 writing.
  66 .SH ERRORS
  67 .I Creat
  68 will fail and the file will not be created or truncated
  69 if one of the following occur:
  70 .TP 15
  71 [ENOTDIR]
  72 A component of the path prefix is not a directory.
  73 .TP 15
  74 [ENAMETOOLONG]
  75 The path name exceeds PATH_MAX characters.
  76 .TP 15
  77 [ENOENT]
  78 The named file does not exist.
  79 .TP 15
  80 [ELOOP]
  81 Too many symbolic links were encountered in translating the pathname.
  82 (Minix-vmd)
  83 .TP 15
  84 [EACCES]
  85 Search permission is denied for a component of the path prefix.
  86 .TP 15
  87 [EACCES]
  88 The file does not exist and the directory
  89 in which it is to be created is not writable.
  90 .TP 15
  91 [EACCES]
  92 The file exists, but it is unwritable.
  93 .TP 15
  94 [EISDIR]
  95 The file is a directory.
  96 .TP 15
  97 [EMFILE]
  98 There are already too many files open.
  99 .TP 15
 100 [ENFILE]
 101 The system file table is full.
 102 .TP 15
 103 [ENOSPC]
 104 The directory in which the entry for the new file is being placed
 105 cannot be extended because there is no space left on the file
 106 system containing the directory.
 107 .TP 15
 108 [ENOSPC]
 109 There are no free inodes on the file system on which the
 110 file is being created.
 111 .ig
 112 .TP 15
 113 [EDQUOT]
 114 The directory in which the entry for the new file
 115 is being placed cannot be extended because the
 116 user's quota of disk blocks on the file system
 117 containing the directory has been exhausted.
 118 .TP 15
 119 [EDQUOT]
 120 The user's quota of inodes on the file system on
 121 which the file is being created has been exhausted.
 122 ..
 123 .TP 15
 124 [EROFS]
 125 The named file resides on a read-only file system.
 126 .TP 15
 127 [ENXIO]
 128 The file is a character special or block special file, and
 129 the associated device does not exist.
 130 .TP 15
 131 [EIO]
 132 An I/O error occurred while making the directory entry or allocating the inode.
 133 .TP 15
 134 [EFAULT]
 135 .I Name
 136 points outside the process's allocated address space.
 137 .SH "SEE ALSO"
 138 .BR open (2),
 139 .BR write (2),
 140 .BR close (2),
 141 .BR chmod (2),
 142 .BR umask (2).