bug-autoconf
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: function portability documentation


From: Ben Pfaff
Subject: Re: function portability documentation
Date: Mon, 22 May 2006 09:06:09 -0700
User-agent: Gnus/5.110004 (No Gnus v0.4) Emacs/21.4 (gnu/linux)

Bruno, that's great work.  I did some proofreading and found some
minor things to point out.

Bruno Haible <address@hidden> writes:

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

"...does not" work "with file..."

> + @item btowc
> + On Windows systems, @code{wchar_t} is a 16-bit type and therefore cannot
> + accomodate all Unicode characters.

"accommodate"

> + @item chown
> + When applied to a symbolic link, some implementations don't dereference
> + the symlink, i.e. they behave like @code{lchown}.

i.e.@:

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

"...does not" work "with file..."

> + @item fgetwc
> + @itemx fgetws
> + On Windows systems, @code{wchar_t} is a 16-bit type and therefore cannot
> + accomodate all Unicode characters.

"accommodate"

> + @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;
> + this means that it translates '\n' to CR/LF by default.  Use the "b" flag
> + if you need reliable binary I/O.

"text" => ``text''

Should "b" be @samp{b}?

> + @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
> + @file{<libintl.h>} from GNU gettext; it redefines this function so that it 
> is
> + POSIX compliant.
> + 
> + On Windows, this function doesn't support the @code{'} flag and the 
> @code{hh},
> + @code{ll}, @code{j}, @code{t}, @code{z} size specifiers.

The Texinfo manual says @samp{} should be used for single
characters, for what it's worth.  Dunno if you care.

> + @item fputwc
> + @itemx fputws
> + On Windows systems, @code{wchar_t} is a 16-bit type and therefore cannot
> + accomodate all Unicode characters.

"accommodate"

Several other misspellings of this same word that I won't point
out separately.

> + @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
> + the option arguments precede the non-option arguments.  This is something to
> + watch out in your program's testsuite.

enfore => enforce

Is "testsuite" one word?

> + @item getpeername
> + Some systems don't have a @code{socklen_t} type; in this case this 
> function's
> + third argument type is @samp{int *}.

Gnulib has a socklen module that should perhaps be mentioned here
(and in other references to socklen_t).

> + @item getsockopt
> + Some systems don't have a @code{socklen_t} type; in this case this 
> function's
> + fifth argument type is @samp{int *}.
> + 
> + Many socket options are not available on all systems.

Is it worth listing which socket options are specified in
the Unix standards, or can even those not be depended upon?

> + @item iconv
> + This function was not correctly implemented in glibc versions before 2.2.
> + 
> + 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.

"can not" => "cannot"

> + @item iconv_open
> + The set of supported encodings and conversions is system dependent.
> + 
> + @item index
> + This function is marked as ``legacy'' in POSIX.  Better use @code{strchr}
> + instead.
> + 
> + @item inet_addr
> + On some old systems, this function returns a @samp{struct in_addr} rather
> + than a scalar type such as @samp{unsigned int} or @samp{unsigned long}.
> + 
> + @item ioctl
> + Most @code{ioctl} requests are platform and hardware specific.
> + 
> + @item isatty
> + On Windows, @code{isatty} also returns true for character devices such as
> + "NUL".

Should "NUL" be @file{NUL}?

> + @item mkdir
> + When the argument ends in a slash, the function call fails on some systems.
> + 
> + On Windows systems (excluding Cygwin), this function is called @code{_mkdir}
> + and takes only one argument.  The fix is to define a macro like this:
> + @smallexample
> + #define mkdir ((int (*)()) _mkdir)
> + @end smallexample

Is that better than this?
        #define mkdir(a,b,c) _mkdir(a,b)

> + @item mktime
> + Some implementations of @code{mktime} may go into an endless loop.

Ouch.  Is there a workaround?

> + @item nanosleep

This entry is empty.

> + @item open
> + On Windows, this function returns a file handle in @code{O_TEXT} mode by
> + default; this means that it translates '\n' to CR/LF by default.  Use the
> + @code{O_BINARY} flag if you need reliable binary I/O.

It seems slightly odd to mix C and character name notation.
Perhaps "translates '\n' to '\r\n'" or "adds a carriage return
before every new-line"?

> + @item poll
> + On MacOS X 10.4.0 and AIX 5.3, this function doesn't work on special files
> + like @file{/dev/null} and ttys like @file{/dev/tty}.

How does it fail?

> + @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.

It would be nice to be more specific, if possible naming kernel
or glibc versions as prerequisites for correct behavior.

> + @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.

In other entries, errno is written inside @code{}.  Actually
there are more inconsistencies of this type that I won't point
out.

> + @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.

" - " should be "---", to form an em dash.

> + @item signal
> + On System V systems, when the signal is triggered, the kernel uninstalls the
> + handler (i.e. resets the signal's action to SIG_DFL) before invoking the

i.e.@:

> + @item unlink
> + Removing an open file is unportable: On Unix this allows the programs that
> + have the file already open to continue working with it; the file's storage
> + is only freed when the no process has the file open any more.  On Windows,
> + the attempt to remove an open file fails.

I usually see the word "non-portable" used, instead of "unportable".

> + @item va_copy
> + Some platforms don't provide this macro.  You can use __va_copy where
> + available instead, or otherwise an assignment or @code{memcpy} call.

You could mention the Gnulib stdarg module here.
-- 
"Premature optimization is the root of all evil."
--D. E. Knuth, "Structured Programming with go to Statements"





reply via email to

[Prev in Thread] Current Thread [Next in Thread]