This is the mail archive of the
libc-alpha@sourceware.org
mailing list for the glibc project.
Re: Consensus on MT-, AS- and AC-Safety docs.
- From: Alexandre Oliva <aoliva at redhat dot com>
- To: "Joseph S. Myers" <joseph at codesourcery dot com>
- Cc: Torvald Riegel <triegel at redhat dot com>, "Carlos O'Donell" <carlos at redhat dot com>, GNU C Library <libc-alpha at sourceware dot org>, Rich Felker <dalias at aerifal dot cx>
- Date: Fri, 22 Nov 2013 12:35:30 -0200
- Subject: Re: Consensus on MT-, AS- and AC-Safety docs.
- Authentication-results: sourceware.org; auth=none
- References: <528A7C8F dot 8060805 at redhat dot com> <Pine dot LNX dot 4 dot 64 dot 1311182312130 dot 8831 at digraph dot polyomino dot org dot uk> <orob5fv8nl dot fsf at livre dot home> <Pine dot LNX dot 4 dot 64 dot 1311201555320 dot 28804 at digraph dot polyomino dot org dot uk> <orli0itbm5 dot fsf at livre dot home> <Pine dot LNX dot 4 dot 64 dot 1311211322040 dot 14539 at digraph dot polyomino dot org dot uk> <or4n75t4b7 dot fsf at livre dot home> <Pine dot LNX dot 4 dot 64 dot 1311221324200 dot 5029 at digraph dot polyomino dot org dot uk>
On Nov 22, 2013, "Joseph S. Myers" <joseph@codesourcery.com> wrote:
> On Fri, 22 Nov 2013, Alexandre Oliva wrote:
>> > I think we should generally go for longer text that makes sense on its own
>> > rather than non-English keywords. (Although having a cross-reference to
>> > the detailed definitions *also* makes sense.)
>>
>> These come across as contradictory requirements.
>>
>> If keywords make sense on their own, readers won't look up their
>> detailed definitions, and miss out on the details you regard as
>> essential for them to be aware of.
> I'd like extended names, which are links to their definitions.
Do you acknowledge that this will not get users to follow the links so
as to look at the precise definitions?
> In the absence of being able to do that in Texinfo, follow the list of
> keywords (which should still be extended names) with something like
> "See [ref] for detailed definitions.".
Do you acknowledge that this will make some parts of the manual, such as
users.texi, nearly unusable, because of the amount of noise you're
forcing into them?
Please confirm you hate our users so much ;-) that you want to impose
the following abomination on them. Can you even find the original
documentation in this horribly noisy haystack? Do you realize this
wouldn't even be the worst part of the manual in this regard? :-(
-- Function: void setpwent (void)
| MT-Unsafe uses-a-static-buffer-overwritten-by-other-calls,
may-read-from-the-global-locale-object || AS-Unsafe
calls-the-dynamic-loader,
calls-functions-from-plugins-external-to-libc,
calls-memory-allocation-functions,
may-deadlock-with-itself-in-asynchronous-signal-handlers
|| AC-Unsafe
may-leave-data-structures-in-an-inconsistent-state-if-cancelled-asynchronously,
may-leave-locks-held-if-cancelled-asynchronously,
may-leak-file-descriptors-upon-asynchronous-cancellation,
may-leak-memory-upon-asynchronous-cancellation |
For detailed definitions, see also *note Safety Keywords::.
This function initializes a stream which `getpwent' and
`getpwent_r' use to read the user database.
-- Function: struct passwd * getpwent (void)
| MT-Unsafe uses-a-static-buffer-overwritten-by-other-calls,
may-read-from-the-global-locale-object || AS-Unsafe
calls-the-dynamic-loader,
calls-functions-from-plugins-external-to-libc,
calls-memory-allocation-functions,
may-deadlock-with-itself-in-asynchronous-signal-handlers
|| AC-Unsafe
may-leave-data-structures-in-an-inconsistent-state-if-cancelled-asynchronously,
may-leave-locks-held-if-cancelled-asynchronously,
may-leak-file-descriptors-upon-asynchronous-cancellation,
may-leak-memory-upon-asynchronous-cancellation |
For detailed definitions, see also *note Safety Keywords::.
The `getpwent' function reads the next entry from the stream
initialized by `setpwent'. It returns a pointer to the entry. The
structure is statically allocated and is rewritten on subsequent
calls to `getpwent'. You must copy the contents of the structure
if you wish to save the information.
A null pointer is returned when no more entries are available.
-- Function: int getpwent_r (struct passwd *RESULT_BUF, char *BUFFER,
size_t BUFLEN, struct passwd **RESULT)
| MT-Unsafe uses-a-static-buffer-overwritten-by-other-calls,
may-read-from-the-global-locale-object || AS-Unsafe
calls-the-dynamic-loader,
calls-functions-from-plugins-external-to-libc,
calls-memory-allocation-functions,
may-deadlock-with-itself-in-asynchronous-signal-handlers
|| AC-Unsafe
may-leave-data-structures-in-an-inconsistent-state-if-cancelled-asynchronously,
may-leave-locks-held-if-cancelled-asynchronously,
may-leak-file-descriptors-upon-asynchronous-cancellation,
may-leak-memory-upon-asynchronous-cancellation |
For detailed definitions, see also *note Safety Keywords::.
This function is similar to `getpwent' in that it returns the next
entry from the stream initialized by `setpwent'. Like
`fgetpwent_r', it uses the user-supplied buffers in RESULT_BUF and
BUFFER to return the information requested.
The return values are the same as for `fgetpwent_r'.
-- Function: void endpwent (void)
| MT-Unsafe uses-a-static-buffer-overwritten-by-other-calls,
may-read-from-the-global-locale-object || AS-Unsafe
calls-the-dynamic-loader,
calls-functions-from-plugins-external-to-libc,
calls-memory-allocation-functions,
may-deadlock-with-itself-in-asynchronous-signal-handlers
|| AC-Unsafe
may-leave-data-structures-in-an-inconsistent-state-if-cancelled-asynchronously,
may-leave-locks-held-if-cancelled-asynchronously,
may-leak-file-descriptors-upon-asynchronous-cancellation,
may-leak-memory-upon-asynchronous-cancellation |
For detailed definitions, see also *note Safety Keywords::.
This function closes the internal stream used by `getpwent' or
`getpwent_r'.
Would you mind if I introduced the short names as macros that expanded
to themselves, and so that you could then turn them into this mess, so
that I don't have my name associated with it? Yeah, I really feel that
strongly about how horrible the above looks. I can only imagine you
didn't think it through, but if you like the way that looks, we'll have
to agree to disagree.
--
Alexandre Oliva, freedom fighter http://FSFLA.org/~lxoliva/
You must be the change you wish to see in the world. -- Gandhi
Be Free! -- http://FSFLA.org/ FSF Latin America board member
Free Software Evangelist Red Hat Brazil Compiler Engineer