Re: function portability documentation

[Ralf Wildenhues]

Hi Bruno,

* Bruno Haible wrote on Mon, May 22, 2006 at 02:13:52PM CEST:
> 
> 2) Who should maintain this section in the future?
> 
> Why does the section currently have only 20 entries, when an up-to-date
> list of portability problems has more than 200 entries? I think the answer
> is that the autoconf maintainers are busy with autoconf, whereas the people
> who write or maintain programs and deal with portability problems on a daily
> basis gather on the bug-gnulib mailing list.

Hmm, I think I'm not the right person to judge this, but I do think
putting it in the Autoconf manual is a great idea.

I'm easier on technical comments; if we want this in Autoconf-2.60, it
should be stabilized quickly, so here we go, quickly:

- Should the entries be indexed?  I would prefer so.  You can probably
take your patch and run the resulting autoconf.texi through a sed script
similar to this one:
  sed '14312,15178{
         /@item/{
           p
           s/address@hidden,1\} \(.*\)/@prindex @code{\1}/
         }
       }'

to produce reasonable indexing, after adjusting the line numbers a bit.
(This script is not portable, but works with GNU sed.)

- It would probably add to the long-term maintainability if the *printf
and similar families of functions would be treated in one place only.
This isn't too important now, though.

- Then, for uniformity with the rest of the manual, please
   s/POSIX/Posix/
   s/\(BSD\|GNU\|IRIX\)/@acronym{\1}/

- The existing section on function portability should be merged with
this one in a suitable way.

More comments inline.  Please take them with a grain of salt, from a
non-native speaker, and apologies for their terse-ness.

> + @code{basename} assumes file names in POSIX syntax; it does not with file
> + names in Windows syntax.

I'd prefer a verb in the second half of the sentence.

> + @item dirname
> + @code{dirname} assumes file names in POSIX syntax; it does not with file
> + names in Windows syntax.

Likewise.

> + @item dlopen
> + If the file name argument is not absolute, the file is searched for.  The
> + search algorithm is system specific.

I think it's system-specific.

> + @item dlsym
> + The visibility of symbols loaded in dependent shared libraries or present
> + in the main executable is system dependent.

Likewise, system-dependent.  Several instances.

> + @item errno
> + On Windows, the socket functions don't set @code{errno}; their error code is
> + available through @code{WSAGetLastError()} instead.

A recent change to GCS suggests not using the parentheses to denote
a function; reserve that for actual function calls instead.

> + @item fnmatch
> + This function is broken in some version of Solaris or glibc.

Shouldn't this be `and' instead of `or'?

> + @item fopen
> + On Windows systems (excluding Cygwin), this function does not set 
> @code{errno}
> + upon failure.
> + 
> + On Windows, this function returns a file stream in "text" mode by default;

FWIW, I'd just write text mode.

> + this means that it translates '\n' to CR/LF by default.  Use the "b" flag
> + if you need reliable binary I/O.

Please use @samp{\n}, and @samp{"b"}; more generally, I'd put most
double-quoted values in the section in @samp{}, or @code{} when they
specify code literals, they look nicer that way in the DVI output.

> + @item fprintf
> + On NetBSD and Windows, this function doesn't support format directives that
> + access arguments in an arbitrary order, such as "%2$s".  The fix is to 
> include

Likewise.  Several instances.

> + @file{<libintl.h>} from GNU gettext; it redefines this function so that it 
> is
> + POSIX compliant.

Wouldn't @file{libintl.h}, or `The fix is to @samp{#include <libintl.h>}'
look nicer?  Several instances.

> + @item fstat
> + On platforms where @code{off_t} is a 32-bit type, @code{stat} may not report
> + correctly the size of files or block devices larger than 2 GB.  The fix is 
> to
> + use the @code{AC_SYS_LARGEFILE} macro.

s/report correctly/correctly report/

If integrated into Autoconf, it'd be nice to cross-reference
AC_SYS_LARGEFILE.  Cross-referencing could be a problem with
"inclusion from Gnulib CVS".

> + @item getgroups
> + On Ultrix 4.3, @code{getgroups (0, 0)} always fails.  See macro
> + @samp{AC_FUNC_GETGROUPS}.

Likewise.

> + @item getopt
> + The glibc implementation of @code{getopt} by default allows mixing option 
> and
> + non-option arguments on the command line in any order.  Other 
> implementations,
> + such as the one in Cygwin, enfore strict POSIX compliance: they require that

s/enfore/enforce/;  I'd move `by default' to the beginning or end of the
sentence.

> + the option arguments precede the non-option arguments.  This is something to
> + watch out in your program's testsuite.


> + When @code{iconv} encounters an input character that is valid but that can
> + not be converted to the output character set, glibc's and GNU libiconv's
> + @code{iconv} stop the conversion.  Some other implementations put an
> + implementation-defined character in the output buffer.

s/in/into/ ?

> + @item ioctl
> + Most @code{ioctl} requests are platform and hardware specific.

Probably need hyphens as well, dunno for sure.

> + @item isatty
> + On Windows, @code{isatty} also returns true for character devices such as
> + "NUL".

See above.

> + On platforms where @code{off_t} is a 32-bit type, @code{lseek} does not work
> + correctly with files larger than 2 GB.  The fix is to use the
> + @code{AC_SYS_LARGEFILE} macro.

See above.

> + @item lstat
> + When the argument ends in a slash, some systems don't dereference the
> + argument.
> + 
> + On platforms where @code{off_t} is a 32-bit type, @code{lstat} may not 
> report
> + correctly the size of files or block devices larger than 2 GB.  The fix is 
> to
> + use the @code{AC_SYS_LARGEFILE} macro.

Likewise.

> + @item mkdir
> + When the argument ends in a slash, the function call fails on some systems.

Do we know which?

> + @item mkstemp
> + On some systems (HP-UX 10.20, SunOS 4.1.4, Solaris 2.5.1), mkstemp has a 
> silly
> + limit that it can create no more than 26 files from a given template.  On
> + OSF/1 4.0f, it can create only 32 files per process.
> + 
> + On systems other than glibc 2.0.7 or newer, @code{mkstemp} can create a
> + world or group writable or readable file, if you haven't set the process'
> + umask to 077.  This is a security risk.

world- or group-writable or -readable ???
I'd write `the process umask', unsure about that.

> + @item mmap
> + To get anonymous memory, on some systems, you can use the flags
> + @code{MAP_ANONYMOUS | MAP_PRIVATE} and @code{-1} instead of a file 
> descriptor;
> + on others you have to use a read-only file descriptor of @file{/dev/zero}.
> + 
> + On HP-UX, passing a non-NULL first argument, as a hint for the address (even
> + without @code{MAP_FIXED}, often causes @code{mmap} to fail.  Better pass 
> NULL
> + in this case.
> + 
> + On HP-UX, @code{MAP_FIXED} basically never works.  On other systems, it 
> depends
> + on the circumstances whether memory can be returned at a given address.

Refer to AC_FUNC_MMAP?

> + @item nanosleep

TODO?  :-)

> + @item pthread_create
> + On Linux/glibc systems before the advent of NPTL, signals could only be
> + executed in one particular thread, not by any thread of the process.

Can we get this more precisely (whether they can only be created by one
thread, or only delivered to the same thread)?

> + @item readlink
> + When @code{readlink} is called on a directory: In the case of NFS mounted
> + directories, Cygwin sets errno to ENOENT or EIO instead of EINVAL.  To avoid
> + this problem, check for a directory before calling @code{readlink}.
> + 
> + When @code{readlink} is called on a file that is not a symbolic link:
> + Irix may set errno to ENXIO instead of EINVAL.  Cygwin may set errno to
> + EACCES instead of EINVAL.

@code{ENOENT} for all the error codes?  More instances in the text.

> + @item realpath
> + This function does not allow to determine the required size of output 
> buffer;
> + PATH_MAX - if it is defined - is nothing more than a guess.

I think two or three hyphens in a row for this usage.
@code{PATH_MAX}?

> + @item shmat
> + Attempts to @code{shmat} into a previously malloc-ed region fail on SunOS 4,
> + with errno set to EINVAL, even if there is an @code{munmap} call in between.

See above @code{EINVAL}

> + except that @code{SIG_IGN} for @code{SIGCHLD} has the effect that the 
> children
> + execution times are not accounted in the @code{times} function.
> + On some systems (BSD? SystemV? Linux?), you need to use the @code{sigaction}
> + flag @code{SA_NOCLDWAIT} in order to obtain this behaviour.

It's be good to answer these questions before it goes in.

> + @item va_arg
> + The second argument of @code{va_arg} must be a type that is invariant under
> + the ``default argument promotions'' (ISO C 99 6.5.2.2 paragraph 6).  This
> + means that the following are not valid here:
> + @table @asis
> + @item @samp{float}
> + Use @samp{double} instead.
> + @item @samp{bool}
> + Use @samp{int} instead.
> + @item Integer types smaller than @samp{int}.

Would `Integer types with a lower conversion rank than that of @samp{int}.'
be better?  (As in: even if, on your system, short int and int have the
same representation, you still should not use short int here, because
that is not portable.)

> + Use @samp{int} or @samp{unsigned int} instead.
> + @end table

Last but not least: Wow, thank you for doing all this work!

Cheers,
Ralf