Re: mkstemp

[Andreas Jaeger <aj@arthur.rhein-neckar.de>]

Hi Andries,

thanks for pointing out the discrepancies.  The appended patch
addresses the first two bugs in the documentation.  I'm CC'ing
libc-alpha for further comment and in the hope that Andreas Schwab
or Ulrich add the patch to glibc 2.1.


>>>>> Andries Brouwer writes:

 > Preparing man-pages-1.23 I updated mktemp.3 and mkstemp.3 with text like
 > -----------------------------------------------------------------------------
 > MKSTEMP(3)          Linux Programmer's Manual          MKSTEMP(3)

 > NAME
 >        mkstemp - create a unique temporary file

 > SYNOPSIS
 >        #include <stdlib.h>

 >        int mkstemp(char *template);

 > DESCRIPTION
 >        The  mkstemp()  function generates a unique temporary file
 >        name from template.  The last six characters  of  template
 >        must  be  XXXXXX and these are replaced with a string that
 >        makes the filename unique. The file is then  created  with
 >        mode read/write and permissions 0666 (glibc 2.0.6 and ear­
 >        lier), 0600 (glibc 2.0.7 and later).   Since  it  will  be
 >        modified,  template  must  not  be  a string constant, but
 >        should be declared as a  character  array.   The  file  is
 >        opened  with  the  O_EXCL  flag,  guaranteeing  that  when
 >        mkstemp returns successfully we are the only user.

 > RETURN VALUE
 >        The mkstemp() function returns the file descriptor  fd  of
 >        the temporary file or -1 on error.

 > ERRORS
 >        EINVAL The  last  six  characters  of  template  were  not
 >               XXXXXX.  Now template is unchanged.

 >        EEXIST Could not create a unique temporary filename.   Now
 >               the contents of template are undefined.

 > BUGS
 >        The  old behaviour (creating a file with mode 0666) may be
 >        a security risk, especially since other Unix flavours  use
 >        0600, and somebody might overlook this detail when porting
 >        programs.

 > CONFORMING TO
 >        BSD 4.3

 > NOTE
 >        The prototype is in <unistd.h> for libc4,  libc5,  glibc1;
 >        glibc2  follows  the Single Unix Specification and has the
 >        prototype in <stdlib.h>.

 > SEE ALSO
 >        mktemp(3), tmpnam(3), tempnam(3), tmpfile(3)
 > -----------------------------------------------------------------------------


 > I write this because you prompted me to update these pages,
 > but it seems that the glibc manual is incomplete and incorrect
 > (but maybe I am not looking at the most recent version).
The last version comes with glibc 2.1 (or 2.1.1pre1) and you seem to
have looked at a recent enough version;-).
 > Differences: (i) #include <stdlib.h> instead of <unistd.h>
 > (ii) You wrote "If `mkstemp' cannot create a uniquely-named file,
 >      it makes TEMPLATE an empty string and returns `-1'."
 > but that seems to be false.

 > Moreover, the glibc manual does not seem to document the values
 > for errno.

I'm not sure if we should document the errno values.  EEXIST and
EINVAL are currently returned - but also any other error value
produced by open.  Unix98 doesn't specify the error values.


Best regards,
Andreas



1999-03-29  Andreas Jaeger  <aj@arthur.rhein-neckar.de>

	* manual/filesys.texi (Temporary Files): mktemp and mkstemp are
	declared in stdlib.h, correct return value of mkstemp.
	Reported by Andries Brouwer <Andries.Brouwer@cwi.nl>.

--- manual/filesys.texi.~1~	Tue Jan 12 07:09:50 1999
+++ manual/filesys.texi	Mon Mar 29 08:05:29 1999
@@ -2852,7 +2852,7 @@
 would crash when @code{mktemp} or @code{mkstemp} tried to modify the
 string.
 
-@comment unistd.h
+@comment stdlib.h
 @comment Unix
 @deftypefun {char *} mktemp (char *@var{template})
 The @code{mktemp} function generates a unique file name by modifying
@@ -2870,7 +2870,7 @@
 @code{mkstemp} is a safe way to avoid this problem.
 @end deftypefun
 
-@comment unistd.h
+@comment stdlib.h
 @comment BSD
 @deftypefun int mkstemp (char *@var{template})
 The @code{mkstemp} function generates a unique file name just as
@@ -2878,9 +2878,9 @@
 (@pxref{Opening and Closing Files}).  If successful, it modifies
 @var{template} in place and returns a file descriptor open on that file
 for reading and writing.  If @code{mkstemp} cannot create a
-uniquely-named file, it makes @var{template} an empty string and returns
-@code{-1}.  If @var{template} does not end with @samp{XXXXXX},
-@code{mkstemp} returns @code{-1} and does not modify @var{template}.
+uniquely-named file, it returns @code{-1}.  If @var{template} does not
+end with @samp{XXXXXX}, @code{mkstemp} returns @code{-1} and does not
+modify @var{template}.
 
 The file is opened using mode @code{0600}.  If the file is meant to be
 used by other users the mode must explicitly changed.

-- 
 Andreas Jaeger   aj@arthur.rhein-neckar.de    jaeger@informatik.uni-kl.de
  for pgp-key finger ajaeger@aixd1.rhrk.uni-kl.de