From 7d15ef84f50a80cb170f8ce3457010f59e221cb8 Mon Sep 17 00:00:00 2001 From: Rical Jasan Date: Fri, 16 Feb 2018 08:47:20 -0800 Subject: manual: Improve documentation of get_current_dir_name. [BZ #6889] 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. --- ChangeLog | 5 +++++ manual/filesys.texi | 17 +++++++++-------- 2 files changed, 14 insertions(+), 8 deletions(-) diff --git a/ChangeLog b/ChangeLog index d6262e5746..35bf20ac11 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +2018-02-19 Rical Jasan + + [BZ #6889] + * manual/filesys.texi (get_current_dir_name): Clarify behaviour. + 2018-02-18 Aurelien Jarno [BZ #22818] 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 -- cgit 1.4.1