Message ID | 20180216164720.1151-1-ricaljasan@pacific.net |
---|---|
State | New |
Headers | show |
Series | manual: Improve documentation of get_current_dir_name. [BZ #6889] | expand |
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 >
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
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