* [PATCH] manual: Improve documentation of get_current_dir_name. [BZ #6889]
@ 2018-02-16 18:10 Rical Jasan
2018-02-16 18:39 ` Carlos O'Donell
0 siblings, 1 reply; 3+ messages in thread
From: Rical Jasan @ 2018-02-16 18:10 UTC (permalink / raw)
To: libc-alpha
This is a minor rewording to clarify the behaviour of
get_current_dir_name. Additionally, the @vindex is moved above the
@deftypefun so that following links give a better result with regard
to context.
[BZ #6889]
* manual/filesys.texi (get_current_dir_name): Clarify
behaviour.
---
manual/filesys.texi | 17 +++++++++--------
1 file changed, 9 insertions(+), 8 deletions(-)
diff --git a/manual/filesys.texi b/manual/filesys.texi
index ca77996902..cc70a6b7ee 100644
--- a/manual/filesys.texi
+++ b/manual/filesys.texi
@@ -147,19 +147,20 @@ necessarily enough space to contain the directory name. That is why
this function is deprecated.
@end deftypefn
+@vindex PWD
@deftypefun {char *} get_current_dir_name (void)
@standards{GNU, unistd.h}
@safety{@prelim{}@mtsafe{@mtsenv{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}}
@c Besides getcwd, which this function calls as a fallback, it calls
@c getenv, with the potential thread-safety issues that brings about.
-@vindex PWD
-This @code{get_current_dir_name} function is basically equivalent to
-@w{@code{getcwd (NULL, 0)}}. The only difference is that the value of
-the @code{PWD} variable is returned if this value is correct. This is a
-subtle difference which is visible if the path described by the
-@code{PWD} value is using one or more symbol links in which case the
-value returned by @code{getcwd} can resolve the symbol links and
-therefore yield a different result.
+The @code{get_current_dir_name} function is basically equivalent to
+@w{@code{getcwd (NULL, 0)}}, except the value of the @env{PWD}
+environment variable is first examined, and if it does in fact
+correspond to the current directory, that value is returned. This is
+a subtle difference which is visible if the path described by the
+value in @env{PWD} is using one or more symbolic links, in which case
+the value returned by @code{getcwd} would resolve the symbolic links
+and therefore yield a different result.
This function is a GNU extension.
@end deftypefun
--
2.16.1
^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: [PATCH] manual: Improve documentation of get_current_dir_name. [BZ #6889]
2018-02-16 18:10 [PATCH] manual: Improve documentation of get_current_dir_name. [BZ #6889] Rical Jasan
@ 2018-02-16 18:39 ` Carlos O'Donell
2018-02-19 10:22 ` Rical Jasan
0 siblings, 1 reply; 3+ messages in thread
From: Carlos O'Donell @ 2018-02-16 18:39 UTC (permalink / raw)
To: Rical Jasan, libc-alpha
On 02/16/2018 08:47 AM, Rical Jasan wrote:
> This is a minor rewording to clarify the behaviour of
> get_current_dir_name. Additionally, the @vindex is moved above the
> @deftypefun so that following links give a better result with regard
> to context.
>
> [BZ #6889]
> * manual/filesys.texi (get_current_dir_name): Clarify
> behaviour.
OK.
I can't express how much I appreciate having someone tidy up the manual
in this way. Thank you.
Reviewed-by: Carlos O'Donell <carlos@redhat.com>
> ---
> manual/filesys.texi | 17 +++++++++--------
> 1 file changed, 9 insertions(+), 8 deletions(-)
>
> diff --git a/manual/filesys.texi b/manual/filesys.texi
> index ca77996902..cc70a6b7ee 100644
> --- a/manual/filesys.texi
> +++ b/manual/filesys.texi
> @@ -147,19 +147,20 @@ necessarily enough space to contain the directory name. That is why
> this function is deprecated.
> @end deftypefn
>
> +@vindex PWD
> @deftypefun {char *} get_current_dir_name (void)
> @standards{GNU, unistd.h}
> @safety{@prelim{}@mtsafe{@mtsenv{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}}
> @c Besides getcwd, which this function calls as a fallback, it calls
> @c getenv, with the potential thread-safety issues that brings about.
> -@vindex PWD
> -This @code{get_current_dir_name} function is basically equivalent to
> -@w{@code{getcwd (NULL, 0)}}. The only difference is that the value of
> -the @code{PWD} variable is returned if this value is correct. This is a
> -subtle difference which is visible if the path described by the
> -@code{PWD} value is using one or more symbol links in which case the
> -value returned by @code{getcwd} can resolve the symbol links and
> -therefore yield a different result.
> +The @code{get_current_dir_name} function is basically equivalent to
> +@w{@code{getcwd (NULL, 0)}}, except the value of the @env{PWD}
> +environment variable is first examined, and if it does in fact
> +correspond to the current directory, that value is returned. This is
> +a subtle difference which is visible if the path described by the
> +value in @env{PWD} is using one or more symbolic links, in which case
> +the value returned by @code{getcwd} would resolve the symbolic links
> +and therefore yield a different result.
>
> This function is a GNU extension.
> @end deftypefun
>
--
Cheers,
Carlos.
^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: [PATCH] manual: Improve documentation of get_current_dir_name. [BZ #6889]
2018-02-16 18:39 ` Carlos O'Donell
@ 2018-02-19 10:22 ` Rical Jasan
0 siblings, 0 replies; 3+ messages in thread
From: Rical Jasan @ 2018-02-19 10:22 UTC (permalink / raw)
To: Carlos O'Donell, libc-alpha
On 02/16/2018 09:10 AM, Carlos O'Donell wrote:
> On 02/16/2018 08:47 AM, Rical Jasan wrote:
>> This is a minor rewording to clarify the behaviour of
>> get_current_dir_name. Additionally, the @vindex is moved above the
>> @deftypefun so that following links give a better result with regard
>> to context.
>>
>> [BZ #6889]
>> * manual/filesys.texi (get_current_dir_name): Clarify
>> behaviour.
> OK.
Committed: 7d15ef84f50a
> I can't express how much I appreciate having someone tidy up the manual
> in this way. Thank you.
It's low-hanging fruit, but also a ten-year-old bug. I was just happy
to see this one and think, "I can squash that." :)
Thank you,
Rical
^ permalink raw reply [flat|nested] 3+ messages in thread
end of thread, other threads:[~2018-02-19 10:12 UTC | newest]
Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2018-02-16 18:10 [PATCH] manual: Improve documentation of get_current_dir_name. [BZ #6889] Rical Jasan
2018-02-16 18:39 ` Carlos O'Donell
2018-02-19 10:22 ` Rical Jasan
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).