logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

mkdtemp.3p (6513B)

    

  1. '\" et
  2. .TH MKDTEMP "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. mkdtemp, mkstemp
  12. \(em create a unique directory or file
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <stdlib.h>
  17. .P
  18. char *mkdtemp(char *\fItemplate\fP);
  19. int mkstemp(char *\fItemplate\fP);
  20. .fi
  21. .SH DESCRIPTION
  22. The
  23. \fImkdtemp\fR()
  24. function shall create a directory with a unique name derived from
  25. .IR template .
  26. The application shall ensure that the string provided in
  27. .IR template
  28. is a pathname ending with at least six trailing
  29. .BR 'X' 
  30. characters. The
  31. \fImkdtemp\fR()
  32. function shall modify the contents of
  33. .IR template
  34. by replacing six or more
  35. .BR 'X' 
  36. characters at the end of the pathname with the same number of
  37. characters from the portable filename character set. The characters
  38. shall be chosen such that the resulting pathname does not duplicate
  39. the name of an existing file at the time of the call to
  40. \fImkdtemp\fR().
  41. The
  42. \fImkdtemp\fR()
  43. function shall use the resulting pathname to create the new directory
  44. as if by a call to:
  45. .sp
  46. .RS 4
  47. .nf
  49. mkdir(pathname, S_IRWXU)
  50. .fi
  51. .P
  52. .RE
  53. .P
  54. The
  55. \fImkstemp\fR()
  56. function shall create a regular file with a unique name derived from
  57. .IR template
  58. and return a file descriptor for the file open for reading and
  59. writing. The application shall ensure that the string provided in
  60. .IR template
  61. is a pathname ending with at least six trailing
  62. .BR 'X' 
  63. characters. The
  64. \fImkstemp\fR()
  65. function shall modify the contents of
  66. .IR template
  67. by replacing six or more
  68. .BR 'X' 
  69. characters at the end of the pathname with the same number of
  70. characters from the portable filename character set. The characters
  71. shall be chosen such that the resulting pathname does not duplicate
  72. the name of an existing file at the time of the call to
  73. \fImkstemp\fR().
  74. The
  75. \fImkstemp\fR()
  76. function shall use the resulting pathname to create the file, and
  77. obtain a file descriptor for it, as if by a call to:
  78. .sp
  79. .RS 4
  80. .nf
  82. open(pathname, O_RDWR|O_CREAT|O_EXCL, S_IRUSR|S_IWUSR)
  83. .fi
  84. .P
  85. .RE
  86. .P
  87. By behaving as if the O_EXCL flag for
  88. \fIopen\fR()
  89. is set, the function prevents any possible race condition between
  90. testing whether the file exists and opening it for use.
  91. .SH "RETURN VALUE"
  92. Upon successful completion, the
  93. \fImkdtemp\fR()
  94. function shall return the value of
  95. .IR template .
  96. Otherwise, it shall return a null pointer and shall set
  97. .IR errno
  98. to indicate the error.
  99. .P
  100. Upon successful completion, the
  101. \fImkstemp\fR()
  102. function shall return an open file descriptor. Otherwise, it shall
  103. return \-1 and shall set
  104. .IR errno
  105. to indicate the error.
  106. .SH ERRORS
  107. The
  108. \fImkdtemp\fR()
  109. function shall fail if:
  110. .TP
  111. .BR EACCES
  112. Search permission is denied on a component of the path prefix, or write
  113. permission is denied on the parent directory of the directory to be
  114. created.
  115. .TP
  116. .BR EINVAL
  117. The string pointed to by
  118. .IR template
  119. does not end in
  120. .BR \(dqXXXXXX\(dq .
  121. .TP
  122. .BR ELOOP
  123. A loop exists in symbolic links encountered during resolution of the
  124. path of the directory to be created.
  125. .TP
  126. .BR EMLINK
  127. The link count of the parent directory would exceed
  128. {LINK_MAX}.
  129. .TP
  130. .BR ENAMETOOLONG
  131. .br
  132. The length of a component of a pathname is longer than
  133. {NAME_MAX}.
  134. .TP
  135. .BR ENOENT
  136. A component of the path prefix specified by the
  137. .IR template
  138. argument does not name an existing directory.
  139. .TP
  140. .BR ENOSPC
  141. The file system does not contain enough space to hold the contents of
  142. the new directory or to extend the parent directory of the new
  143. directory.
  144. .TP
  145. .BR ENOTDIR
  146. A component of the path prefix names an existing file that is neither
  147. a directory nor a symbolic link to a directory.
  148. .TP
  149. .BR EROFS
  150. The parent directory resides on a read-only file system.
  151. .P
  152. The
  153. \fImkdtemp\fR()
  154. function may fail if:
  155. .TP
  156. .BR ELOOP
  157. More than
  158. {SYMLOOP_MAX}
  159. symbolic links were encountered during resolution of the path of the
  160. directory to be created.
  161. .TP
  162. .BR ENAMETOOLONG
  163. .br
  164. The length of a pathname exceeds
  165. {PATH_MAX},
  166. or pathname resolution of a symbolic link produced an intermediate
  167. result with a length that exceeds
  168. {PATH_MAX}.
  169. .P
  170. The error conditions for the
  171. \fImkstemp\fR()
  172. function are defined in
  173. .IR "\fIopen\fR\^(\|)".
  174. .LP
  175. .IR "The following sections are informative."
  176. .SH EXAMPLES
  177. .SS "Generating a Pathname"
  178. .P
  179. The following example creates a file with a 10-character name beginning
  180. with the characters
  181. .BR \(dqfile\(dq 
  182. and opens the file for reading and writing. The value returned as the
  183. value of
  184. .IR fd
  185. is a file descriptor that identifies the file.
  186. .sp
  187. .RS 4
  188. .nf
  190. #include <stdlib.h>
  191. \&...
  192. char template[] = "/tmp/fileXXXXXX";
  193. int fd;
  194. .P
  195. fd = mkstemp(template);
  196. .fi
  197. .P
  198. .RE
  199. .SH "APPLICATION USAGE"
  200. It is possible to run out of letters.
  201. .P
  202. Portable applications should pass exactly six trailing
  203. .BR 'X' s
  204. in the template and no more; implementations may treat any additional
  205. trailing
  206. .BR 'X' s
  207. as either a fixed or replaceable part of the template. To be sure of
  208. only passing six, a fixed string of at least one non-\c
  209. .BR 'X' 
  210. character should precede the six
  211. .BR 'X' s.
  212. .P
  213. Since
  214. .BR 'X' 
  215. is in the portable filename character set, some of the replacement
  216. characters can be
  217. .BR 'X' s,
  218. leaving part (or even all) of the template effectively unchanged.
  219. .SH RATIONALE
  220. None.
  221. .SH "FUTURE DIRECTIONS"
  222. None.
  223. .SH "SEE ALSO"
  224. .IR "\fIgetpid\fR\^(\|)",
  225. .IR "\fImkdir\fR\^(\|)",
  226. .IR "\fIopen\fR\^(\|)",
  227. .IR "\fItmpfile\fR\^(\|)",
  228. .IR "\fItmpnam\fR\^(\|)"
  229. .P
  230. The Base Definitions volume of POSIX.1\(hy2017,
  231. .IR "\fB<stdlib.h>\fP"
  232. .\"
  233. .SH COPYRIGHT
  234. Portions of this text are reprinted and reproduced in electronic form
  235. from IEEE Std 1003.1-2017, Standard for Information Technology
  236. -- Portable Operating System Interface (POSIX), The Open Group Base
  237. Specifications Issue 7, 2018 Edition,
  238. Copyright (C) 2018 by the Institute of
  239. Electrical and Electronics Engineers, Inc and The Open Group.
  240. In the event of any discrepancy between this version and the original IEEE and
  241. The Open Group Standard, the original IEEE and The Open Group Standard
  242. is the referee document. The original Standard can be obtained online at
  243. http://www.opengroup.org/unix/online.html .
  244. .PP
  245. Any typographical or formatting errors that appear
  246. in this page are most likely
  247. to have been introduced during the conversion of the source files to
  248. man page format. To report such errors, see
  249. https://www.kernel.org/doc/man-pages/reporting_bugs.html .