[PATCH 2/6] Use makedoc generated texinfo documentation for reentrant syscalls

[Andre Vieira]

On 23/07/15 13:47, Jon TURNEY wrote:
> We use texinfo nodes beginning with an underscore in several other places, so
> revert this ancient workaround for a no longer existing bug, and use the makedoc
> generated texinfo for reentrant versions of syscalls, rather than handwritten
> documentation.
>
> Also alphabetically sort these functions.
>
> Also add documentation for _execve_r, _getpid_r, _kill_r and _times_r functions,
> whose non-reentrant versions are documented as stubs
>
> v2:
> Keep _open64_r, _lseek64_r and _fstat64_r functions under texinfo conditional STDIO64
> Add _stat64_r function likewise.
>
> Notes:
>
> 1. The handwritten prototypes give the reentrancy structure pointer as of type
> void *, rather than the presumably more correct struct __reent *
>
> 2. The fcntl, gettimeofday, mkdir and rename functions are not documented as
> stubs, so I haven't added the reentrrant versions either
>
> Signed-off-by: Jon TURNEY <jon.turney@dronecode.org.uk>
> ---
>   newlib/libc/sys.tex | 193 +++++++++++++++-------------------------------------
>   1 file changed, 54 insertions(+), 139 deletions(-)
>
> diff --git a/newlib/libc/sys.tex b/newlib/libc/sys.tex
> index 3b04c15..1b3cc32 100644
> --- a/newlib/libc/sys.tex
> +++ b/newlib/libc/sys.tex
> @@ -306,171 +306,86 @@ routines are consistent with the other reentrant subroutines in this
>   library, and achieve reentrancy by using a reserved global data block
>   (@pxref{Reentrancy,,Reentrancy}).
>
> -@c FIXME!!! The following ignored text specifies how this section ought
> -@c to work;  however, both standalone info and Emacs info mode fail when
> -@c confronted with nodes beginning `_' as of 24may93.  Restore when Info
> -@c readers fixed!
> -@ignore
>   @menu
> -* _open_r::	Reentrant version of open
>   * _close_r::	Reentrant version of close
> +* _execve_r::	Reentrant version of execve
> +* _fork_r::	Reentrant version of fork
> +* _fstat64_r::	Reentrant version of fstat64
> +* _fstat_r::	Reentrant version of fstat
> +* _getpid_r::	Reentrant version of getpid
> +* _kill_r::	Reentrant version of kill
> +* _link_r::	Reentrant version of link
> +* _lseek64_r::	Reentrant version of lseek64
>   * _lseek_r::	Reentrant version of lseek
> +* _open64_r::	Reentrant version of open64
> +* _open_r::	Reentrant version of open
>   * _read_r::	Reentrant version of read
> -* _write_r::	Reentrant version of write
> -* _link_r::     Reentrant version of link
> -* _unlink_r::   Reentrant version of unlink
> -* _stat_r::     Reentrant version of stat
> -* _fstat_r::    Reentrant version of fstat
> -* _sbrk_r::     Reentrant version of sbrk
> -* _fork_r::	Reentrant version of fork
> +* _sbrk_r::	Reentrant version of sbrk
> +* _stat64_r::	Reentrant version of stat64
> +* _stat_r::	Reentrant version of stat
> +* _times_r::	Reentrant version of times
> +* _unlink_r::	Reentrant version of unlink
>   * _wait_r::	Reentrant version of wait
> +* _write_r::	Reentrant version of write
>   @end menu
>
> -@down
> -@include reent/filer.def
> -@include reent/execr.def
> -@include reent/statr.def
> -@include reent/fstatr.def
> -@include reent/linkr.def
> -@include reent/unlinkr.def
> -@include reent/sbrkr.def
> -@up
> -@end ignore
> -
> -@ftable @code
> -@item _open_r
> -A reentrant version of @code{open}.  It takes a pointer
> -to the global data block, which holds @code{errno}.
> +@lowersections
> +@page
> +@include reent/closer.def
>
> -@example
> -int _open_r(void *@var{reent},
> -    const char *@var{file}, int @var{flags}, int @var{mode});
> -@end example
> +@page
> +@include reent/execr.def
>
>   @ifset STDIO64
> -@item _open64_r
> -A reentrant version of @code{open64}.  It takes a pointer
> -to the global data block, which holds @code{errno}.
> -
> -@example
> -int _open64_r(void *@var{reent},
> -    const char *@var{file}, int @var{flags}, int @var{mode});
> -@end example
> +@page
> +@include reent/fstat64r.def
>   @end ifset
>
> -@item _close_r
> -A reentrant version of @code{close}.  It takes a pointer to the global
> -data block, which holds @code{errno}.
> -
> -@example
> -int _close_r(void *@var{reent}, int @var{fd});
> -@end example
> -
> -@item _lseek_r
> -A reentrant version of @code{lseek}.  It takes a pointer to the global
> -data block, which holds @code{errno}.
> +@page
> +@include reent/fstatr.def
>
> -@example
> -off_t _lseek_r(void *@var{reent},
> -    int @var{fd}, off_t @var{pos}, int @var{whence});
> -@end example
> +@page
> +@include reent/linkr.def
>
>   @ifset STDIO64
> -@item _lseek64_r
> -A reentrant version of @code{lseek64}.  It takes a pointer to the global
> -data block, which holds @code{errno}.
> -
> -@example
> -off_t _lseek64_r(void *@var{reent},
> -    int @var{fd}, off_t @var{pos}, int @var{whence});
> -@end example
> +@page
> +@include reent/lseek64r.def
>   @end ifset
>
> -@item _read_r
> -A reentrant version of @code{read}.  It takes a pointer to the global
> -data block, which holds @code{errno}.
> -
> -@example
> -long _read_r(void *@var{reent},
> -    int @var{fd}, void *@var{buf}, size_t @var{cnt});
> -@end example
> -
> -@item _write_r
> -A reentrant version of @code{write}.  It takes a pointer to the global
> -data block, which holds @code{errno}.
> -
> -@example
> -long _write_r(void *@var{reent},
> -    int @var{fd}, const void *@var{buf}, size_t @var{cnt});
> -@end example
> -
> -@item _fork_r
> -A reentrant version of @code{fork}.  It takes a pointer to the global
> -data block, which holds @code{errno}.
> -
> -@example
> -int _fork_r(void *@var{reent});
> -@end example
> -
> -@item _wait_r
> -A reentrant version of @code{wait}.  It takes a pointer to the global
> -data block, which holds @code{errno}.
> +@page
> +@include reent/lseekr.def
>
> -@example
> -int _wait_r(void *@var{reent}, int *@var{status});
> -@end example
> +@ifset STDIO64
> +@page
> +@include reent/open64r.def
> +@end ifset
>
> -@item _stat_r
> -A reentrant version of @code{stat}.  It takes a pointer to the global
> -data block, which holds @code{errno}.
> +@page
> +@include reent/openr.def
>
> -@example
> -int _stat_r(void *@var{reent},
> -    const char *@var{file}, struct stat *@var{pstat});
> -@end example
> +@page
> +@include reent/readr.def
>
> -@item _fstat_r
> -A reentrant version of @code{fstat}.  It takes a pointer to the global
> -data block, which holds @code{errno}.
> +@page
> +@include reent/sbrkr.def
>
> -@example
> -int _fstat_r(void *@var{reent},
> -    int @var{fd}, struct stat *@var{pstat});
> -@end example
> +@page
> +@include reent/signalr.def
>
>   @ifset STDIO64
> -@item _fstat64_r
> -A reentrant version of @code{fstat64}.  It takes a pointer to the global
> -data block, which holds @code{errno}.
> -
> -@example
> -int _fstat64_r(void *@var{reent},
> -    int @var{fd}, struct stat *@var{pstat});
> -@end example
> +@page
> +@include reent/stat64r.def
>   @end ifset
>
> -@item _link_r
> -A reentrant version of @code{link}.  It takes a pointer to the global
> -data block, which holds @code{errno}.
> -
> -@example
> -int _link_r(void *@var{reent},
> -    const char *@var{old}, const char *@var{new});
> -@end example
> -
> -@item _unlink_r
> -A reentrant version of @code{unlink}.  It takes a pointer to the global
> -data block, which holds @code{errno}.
> +@page
> +@include reent/statr.def
>
> -@example
> -int _unlink_r(void *@var{reent}, const char *@var{file});
> -@end example
> +@page
> +@include reent/timesr.def
>
> -@item _sbrk_r
> -A reentrant version of @code{sbrk}.  It takes a pointer to the global
> -data block, which holds @code{errno}.
> +@page
> +@include reent/unlinkr.def
>
> -@example
> -char *_sbrk_r(void *@var{reent}, size_t @var{incr});
> -@end example
> -@end ftable
> +@page
> +@include reent/writer.def
> +@raisesections
>

Hi Jon,

This is failing for our 32-bit build. The menu entries for _fstat64_r, 
_lseek64_r, _open64_r and _stat64_r are included regardless of whether 
STDIO64 is set, so if it's not, the nodes they reference will not be 
created. This yields errors such as:

./reent/statr.def:1: Prev reference to nonexistent node `_stat64_r' 
(perhaps incorrect sectioning?).


Kind Regards,