sys/man/2/open

   1 .TH OPEN 2
   2 .SH NAME
   3 open, create, close \- open a file for reading or writing, create file
   4 .SH SYNOPSIS
   5 .B #include <u.h>
   6 .br
   7 .B #include <libc.h>
   8 .PP
   9 .B
  10 int open(char *file, int omode)
  11 .PP
  12 .B
  13 int create(char *file, int omode, ulong perm)
  14 .PP
  15 .B
  16 int close(int fd)
  17 .SH DESCRIPTION
  18 .I Open
  19 opens the
  20 .I file
  21 for I/O and returns an associated file descriptor.
  22 .I Omode
  23 is one of
  24 .BR OREAD ,
  25 .BR OWRITE ,
  26 .BR ORDWR ,
  27 or
  28 .BR OEXEC ,
  29 asking for permission to read, write, read and write, or execute, respectively.
  30 In addition, there are three values that can be ORed with the
  31 .IR omode :
  32 .B OTRUNC
  33 says to truncate the file
  34 to zero length before opening it;
  35 .B OCEXEC
  36 says to close the file when an
  37 .IR exec (2)
  38 or
  39 .I execl
  40 system call is made;
  41 and
  42 .B ORCLOSE
  43 says to remove the file when it is closed (by everyone who has a copy of the file descriptor).
  44 .I Open
  45 fails if the file does not exist or the user does not have
  46 permission to open it for the requested purpose
  47 (see
  48 .IR stat (2)
  49 for a description of permissions).
  50 The user must have write permission on the
  51 .I file
  52 if the
  53 .B OTRUNC
  54 bit is set.
  55 For the
  56 .I open
  57 system call
  58 (unlike the implicit
  59 .I open
  60 in
  61 .IR exec (2)),
  62 .B OEXEC
  63 is actually identical to
  64 .BR OREAD .
  65 .PP
  66 .I Create
  67 creates a new
  68 .I file
  69 or prepares to rewrite an existing
  70 .IR file ,
  71 opens it according to
  72 .I omode
  73 (as described for
  74 .IR open ),
  75 and returns an associated file descriptor.
  76 If the file is new,
  77 the owner is set to the userid of the creating process group;
  78 the group to that of the containing directory;
  79 the permissions to
  80 .I perm
  81 ANDed with the permissions of the containing directory.
  82 If the file already exists,
  83 it is truncated to 0 length,
  84 and the permissions, owner, and group remain unchanged.
  85 The created file is a directory if the
  86 .B DMDIR
  87 bit is set in
  88 .IR perm ,
  89 an exclusive-use file if the
  90 .B DMEXCL
  91 bit is set, and an append-only file if the
  92 .B DMAPPEND
  93 bit is set.
  94 Exclusive-use files may be open for I/O by only one client at a time,
  95 but the file descriptor may become invalid if no I/O is done
  96 for an extended period; see
  97 .IR open (5).
  98 .PP
  99 .I Create
 100 fails if the path up to the last element of
 101 .I file
 102 cannot be evaluated, if the user doesn't have write permission
 103 in the final directory, if the file already exists and
 104 does not permit the access defined by
 105 .IR omode ,
 106 of if there are no free file descriptors.
 107 In the last case, the file may be created even when
 108 an error is returned.
 109 If the file is new and the directory in which it is created is
 110 a union directory (see
 111 .IR intro (2))
 112 then the constituent directory where the file is created
 113 depends on the structure of the union: see
 114 .IR bind (2).
 115 .PP
 116 Since
 117 .I create
 118 may succeed even if the file exists, a special mechanism is necessary
 119 for those applications that require an atomic create operation.
 120 If the
 121 .B OEXCL
 122 .RB ( 0x1000 )
 123 bit is set in the
 124 .I mode
 125 for a
 126 .IR create,
 127 the call succeeds only if the file does not already exist;
 128 see
 129 .IR open (5)
 130 for details.
 131 .PP
 132 .I Close
 133 closes the file associated with a file descriptor.
 134 Provided the file descriptor is a valid open descriptor,
 135 .I close
 136 is guaranteed to close it; there will be no error.
 137 Files are closed automatically upon termination of a process;
 138 .I close
 139 allows the file descriptor to be reused.
 140 .SH SOURCE
 141 .B /sys/src/libc/9syscall
 142 .SH SEE ALSO
 143 .IR intro (2),
 144 .IR bind (2),
 145 .IR stat (2)
 146 .SH DIAGNOSTICS
 147 These functions set
 148 .IR errstr .