Re: Clarification for mkostemp/mkostemps man page

["Michael Kerrisk (man-pages)" <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>]

Hello Janne,

On 12/17/13 20:56, Janne Blomqvist wrote:
> Hello,
> 
> currently the man page for mkostemp/mkostemps says
> 
> """The mkostemp() function is like mkstemp(), with the difference that
> flags as for open(2) may be specified in flags (e.g., O_APPEND,
> O_SYNC)."""
> 
> To be more precise, the implementation massages the flags argument as follows:
> 
> (flags & ~O_ACCMODE) | O_RDWR | O_CREAT | O_EXCL
> 
> That is, there is no need to explicitly include O_RDWR | O_CREAT |
> O_EXCL in flags, as it's added implicitly.
> 
> So I suggest that the manpage should instead state that *additional*
> flags may be specified in the flags argument.
> 
> This issue is a potential portability problem. FreeBSD 10+ also has
> mkostemp{s}, but generates an error if O_RDWR | O_CREAT | O_EXCL is
> present instead of silently accepting it. While annoying, this
> difference in behavior seems Ok by the proposed addition of mkostemp
> to some future POSIX standard, see
> 
> http://austingroupbugs.net/view.php?id=411
> 
> """
> The mkostemp( ) function shall be equivalent to the mkstemp( )
> function, except that the flag argument may contain additional flags
> (from <fcntl.h>) to be used as if by open( ). Behavior is unspecified
> if the flag argument contains more than the following flags:
> 
> O_APPEND Set append mode.
> 
> O_CLOEXEC Set the FD_CLOEXEC file descriptor flag.
> 
> <SIO>O_DSYNC Write according to the synchronized I/O data integrity
> completion.</SIO>
> 
> <SIO>O_RSYNC Synchronized read I/O operations.</SIO>
> 
> <XSI|SIO>O_SYNC Write according to synchronized I/O file integrity
> completion.</XSI|SIO>
> """

Thank you for the very detailed report. I applied the patch below. Okay?

Cheers,

Michael

diff --git a/man3/mkstemp.3 b/man3/mkstemp.3
index 40cd7e6..d2367bb 100644
--- a/man3/mkstemp.3
+++ b/man3/mkstemp.3
@@ -101,13 +101,32 @@ The
 .BR mkostemp ()
 function is like
 .BR mkstemp (),
-with the difference that flags as for
-.BR open (2)
-may be specified in
-.IR flags
-(e.g.,
+with the difference that the following bits\(emwith the same meaning as for
+.BR open (2)\(emmay
+be specified in
+.IR flags :
 .BR O_APPEND ,
-.BR O_SYNC ).
+.BR O_CLOEXEC ,
+and
+.BR O_SYNC .
+Note that when creating the file,
+.BR mkostemp ()
+includes the values
+.BR O_RDWR ,
+.BR O_CREAT ,
+and
+.BR O_EXCL
+in the
+.I flags
+argument given to
+.BR open (2);
+including these values in the
+.I flags
+argument given to
+.BR mkostemp ()
+is unnecessary, and produces errors on some
+.\" Reportedly, FreeBSD
+systems.
 
 The
 .BR mkstemps ()


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html