1
0

open 3.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148
  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 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 .