1 cfa37a7b 2004-04-10 devnull .TH OPEN 3
3 cfa37a7b 2004-04-10 devnull open, create, close \- open a file for reading or writing, create file
4 cfa37a7b 2004-04-10 devnull .SH SYNOPSIS
5 cfa37a7b 2004-04-10 devnull .B #include <u.h>
7 cfa37a7b 2004-04-10 devnull .B #include <libc.h>
10 cfa37a7b 2004-04-10 devnull int open(char *file, int omode)
13 cfa37a7b 2004-04-10 devnull int create(char *file, int omode, ulong perm)
16 cfa37a7b 2004-04-10 devnull int close(int fd)
17 cfa37a7b 2004-04-10 devnull .SH DESCRIPTION
19 cfa37a7b 2004-04-10 devnull opens the
21 cfa37a7b 2004-04-10 devnull for I/O and returns an associated file descriptor.
23 cfa37a7b 2004-04-10 devnull is one of
24 cfa37a7b 2004-04-10 devnull .BR OREAD ,
25 cfa37a7b 2004-04-10 devnull .BR OWRITE ,
26 cfa37a7b 2004-04-10 devnull .BR ORDWR ,
28 cfa37a7b 2004-04-10 devnull .BR OEXEC ,
29 cfa37a7b 2004-04-10 devnull asking for permission to read, write, read and write, or execute, respectively.
30 cfa37a7b 2004-04-10 devnull In addition, there are three values that can be ORed with the
31 cfa37a7b 2004-04-10 devnull .IR omode :
32 cfa37a7b 2004-04-10 devnull .B OTRUNC
33 cfa37a7b 2004-04-10 devnull says to truncate the file
34 cfa37a7b 2004-04-10 devnull to zero length before opening it;
35 cfa37a7b 2004-04-10 devnull .B OCEXEC
36 cfa37a7b 2004-04-10 devnull says to close the file when an
40 cfa37a7b 2004-04-10 devnull system call is made;
41 cfa37a7b 2004-04-10 devnull .B ORCLOSE
42 d93fca6a 2005-02-11 devnull says to remove the file when it is closed (by everyone who has a copy of the file descriptor);
44 d93fca6a 2005-02-11 devnull .B OAPPEND
45 d93fca6a 2005-02-11 devnull says to open the file in append-only mode, so that writes
46 d93fca6a 2005-02-11 devnull are always appended to the end of the file.
48 cfa37a7b 2004-04-10 devnull fails if the file does not exist or the user does not have
49 cfa37a7b 2004-04-10 devnull permission to open it for the requested purpose
52 cfa37a7b 2004-04-10 devnull for a description of permissions).
53 cfa37a7b 2004-04-10 devnull The user must have write permission on the
56 cfa37a7b 2004-04-10 devnull .B OTRUNC
57 cfa37a7b 2004-04-10 devnull bit is set.
60 cfa37a7b 2004-04-10 devnull system call
61 cfa37a7b 2004-04-10 devnull (unlike the implicit
64 d32deab1 2020-08-16 rsc .MR exec (3) ),
66 cfa37a7b 2004-04-10 devnull is actually identical to
67 cfa37a7b 2004-04-10 devnull .BR OREAD .
69 cfa37a7b 2004-04-10 devnull .I Create
70 cfa37a7b 2004-04-10 devnull creates a new
72 cfa37a7b 2004-04-10 devnull or prepares to rewrite an existing
73 cfa37a7b 2004-04-10 devnull .IR file ,
74 cfa37a7b 2004-04-10 devnull opens it according to
76 cfa37a7b 2004-04-10 devnull (as described for
77 cfa37a7b 2004-04-10 devnull .IR open ),
78 cfa37a7b 2004-04-10 devnull and returns an associated file descriptor.
79 cfa37a7b 2004-04-10 devnull If the file is new,
80 cfa37a7b 2004-04-10 devnull the owner is set to the userid of the creating process group;
81 cfa37a7b 2004-04-10 devnull the group to that of the containing directory;
82 cfa37a7b 2004-04-10 devnull the permissions to
84 cfa37a7b 2004-04-10 devnull ANDed with the permissions of the containing directory.
85 cfa37a7b 2004-04-10 devnull If the file already exists,
86 cfa37a7b 2004-04-10 devnull it is truncated to 0 length,
87 cfa37a7b 2004-04-10 devnull and the permissions, owner, and group remain unchanged.
88 cfa37a7b 2004-04-10 devnull The created file is a directory if the
90 cfa37a7b 2004-04-10 devnull bit is set in
91 cfa37a7b 2004-04-10 devnull .IR perm ,
92 cfa37a7b 2004-04-10 devnull an exclusive-use file if the
93 cfa37a7b 2004-04-10 devnull .B DMEXCL
94 cfa37a7b 2004-04-10 devnull bit is set, and an append-only file if the
95 cfa37a7b 2004-04-10 devnull .B DMAPPEND
96 cfa37a7b 2004-04-10 devnull bit is set.
97 cfa37a7b 2004-04-10 devnull Exclusive-use files may be open for I/O by only one client at a time,
98 cfa37a7b 2004-04-10 devnull but the file descriptor may become invalid if no I/O is done
99 cfa37a7b 2004-04-10 devnull for an extended period; see
100 058b0118 2005-01-03 devnull .IR open (9p).
102 cfa37a7b 2004-04-10 devnull .I Create
103 cfa37a7b 2004-04-10 devnull fails if the path up to the last element of
105 cfa37a7b 2004-04-10 devnull cannot be evaluated, if the user doesn't have write permission
106 cfa37a7b 2004-04-10 devnull in the final directory, if the file already exists and
107 cfa37a7b 2004-04-10 devnull does not permit the access defined by
108 cfa37a7b 2004-04-10 devnull .IR omode ,
109 cfa37a7b 2004-04-10 devnull of if there there are no free file descriptors.
110 cfa37a7b 2004-04-10 devnull In the last case, the file may be created even when
111 cfa37a7b 2004-04-10 devnull an error is returned.
112 058b0118 2005-01-03 devnull .\" If the file is new and the directory in which it is created is
113 058b0118 2005-01-03 devnull .\" a union directory (see
114 058b0118 2005-01-03 devnull .\" .IR intro (3))
115 058b0118 2005-01-03 devnull .\" then the constituent directory where the file is created
116 058b0118 2005-01-03 devnull .\" depends on the structure of the union: see
117 058b0118 2005-01-03 devnull .\" .IR bind (3).
120 cfa37a7b 2004-04-10 devnull .I create
121 cfa37a7b 2004-04-10 devnull may succeed even if the file exists, a special mechanism is necessary
122 cfa37a7b 2004-04-10 devnull for those applications that require an atomic create operation.
124 cfa37a7b 2004-04-10 devnull .B OEXCL
125 cfa37a7b 2004-04-10 devnull .RB ( 0x1000 )
126 cfa37a7b 2004-04-10 devnull bit is set in the
129 cfa37a7b 2004-04-10 devnull .IR create,
130 cfa37a7b 2004-04-10 devnull the call succeeds only if the file does not already exist;
132 058b0118 2005-01-03 devnull .IR open (9p)
133 cfa37a7b 2004-04-10 devnull for details.
135 cfa37a7b 2004-04-10 devnull .I Close
136 cfa37a7b 2004-04-10 devnull closes the file associated with a file descriptor.
137 cfa37a7b 2004-04-10 devnull Provided the file descriptor is a valid open descriptor,
138 cfa37a7b 2004-04-10 devnull .I close
139 cfa37a7b 2004-04-10 devnull is guaranteed to close it; there will be no error.
140 cfa37a7b 2004-04-10 devnull Files are closed automatically upon termination of a process;
141 cfa37a7b 2004-04-10 devnull .I close
142 cfa37a7b 2004-04-10 devnull allows the file descriptor to be reused.
143 cfa37a7b 2004-04-10 devnull .SH SOURCE
144 c3674de4 2005-01-11 devnull .B \*9/src/lib9
145 cfa37a7b 2004-04-10 devnull .SH SEE ALSO
146 d32deab1 2020-08-16 rsc .MR intro (3) ,
147 d32deab1 2020-08-16 rsc .MR stat (3)
148 cfa37a7b 2004-04-10 devnull .SH DIAGNOSTICS
149 cfa37a7b 2004-04-10 devnull These functions set
150 cfa37a7b 2004-04-10 devnull .IR errstr .
151 d93fca6a 2005-02-11 devnull .SH BUGS
152 d93fca6a 2005-02-11 devnull Not all functionality is supported on all systems.
155 d93fca6a 2005-02-11 devnull .B DMAPPEND
156 d93fca6a 2005-02-11 devnull bit is not supported on any systems.
158 d93fca6a 2005-02-11 devnull The implementation of
159 d93fca6a 2005-02-11 devnull .B ORCLOSE
160 d93fca6a 2005-02-11 devnull is to unlink the file after opening it, causing problems
161 d93fca6a 2005-02-11 devnull in programs that try to access the file by name before it is closed.
163 be9e0e98 2005-03-28 devnull To avoid name conflicts with the underlying system,
166 be9e0e98 2005-03-28 devnull .I create
167 be9e0e98 2005-03-28 devnull are preprocessor macros defined as
168 be9e0e98 2005-03-28 devnull .IR p9open
170 be9e0e98 2005-03-28 devnull .IR p9create ;
172 d32deab1 2020-08-16 rsc .MR intro (3) .
