Merged PR 17061: Clarify current directory and relative path warnings

Existing text erroneously implied that the current directory is not thread safe. It also went too far in saying that relative path usage in multithreaded apps is "not supported". It is supported, but the results may not be what apps expect. Provide new guidance.

Author: oldnewthing

sdk-api-src/content/fileapi/nf-fileapi-getfullpathnamea.md

@@ -66,8 +66,9 @@ To perform this operation as a transacted operation, use the
 
 For more information about file and path names, see 
     <a href="/windows/desktop/FileIO/naming-a-file">File Names, Paths, and Namespaces</a>.
-<div class="alert"><b>Note</b>  The <b>GetFullPathName</b> function is not recommended for 
-    multithreaded applications or shared library code. For more information, see the Remarks section.</div><div> </div>
+<div class="alert"><b>Note</b> See the Remarks section for discussion of
+    the use of relative paths with the <b>GetFullPathName</b> function
+    in multithreaded applications or shared library code.</div>
 
 ## -parameters
 
@@ -155,19 +156,22 @@ If the return value is greater than or equal to the value specified in
 
 <div class="alert"><b>Note</b>  Although the return value in this case is a length that includes the terminating null character, the return 
      value on success does not include the terminating null character in the count.</div>
-<div> </div>
-Multithreaded applications and shared library code should not use the 
-    <b>GetFullPathName</b> function and should avoid using relative 
-    path names. The current directory state written by the 
-    <a href="/windows/desktop/api/winbase/nf-winbase-setcurrentdirectory">SetCurrentDirectory</a> function is stored as a global 
-    variable in each process, therefore multithreaded applications cannot reliably use this value without possible 
-    data corruption from other threads that may also be reading or setting this value. This limitation also applies 
-    to the <b>SetCurrentDirectory</b> and 
-    <a href="/windows/desktop/api/winbase/nf-winbase-getcurrentdirectory">GetCurrentDirectory</a> functions. The exception being 
-    when the application is guaranteed to be running in a single thread, for example parsing file names from the 
-    command line argument string in the main thread prior to creating any additional threads. Using relative path 
-    names in multithreaded applications or shared library code can yield unpredictable results and is not 
-    supported.
+
+Relative paths passed to the <b>GetFullPathName</b> function are
+interpreted as relative to the process's current directory.
+The current directory state written by the
+<a href="/windows/desktop/api/winbase/nf-winbase-setcurrentdirectory">SetCurrentDirectory</a>
+function is global to the process and can be changed by any thread at any time.
+Applications should be aware that
+consecutive calls to the <b>GetFullPathName</b> function with a relative path
+may produce different results if the current directory changes between the two calls.
+
+To avoid problems caused by inconsistent results,
+multithreaded applications and shared library code should avoid using relative paths.
+If a relative path is received, it should be consumed exactly once,
+either by passing the relative path directly to a function like <b>CreateFile</b>,
+or by converting it to an absolute path and using the absolute path
+from that point forward.
 
 In Windows 8 and Windows Server 2012, this function is supported by the following technologies.
 

sdk-api-src/content/fileapi/nf-fileapi-getfullpathnamew.md

@@ -66,8 +66,9 @@ To perform this operation as a transacted operation, use the
 
 For more information about file and path names, see 
     <a href="/windows/desktop/FileIO/naming-a-file">File Names, Paths, and Namespaces</a>.
-<div class="alert"><b>Note</b>  The <b>GetFullPathName</b> function is not recommended for 
-    multithreaded applications or shared library code. For more information, see the Remarks section.</div><div> </div>
+<div class="alert"><b>Note</b> See the Remarks section for discussion of
+    the use of relative paths with the <b>GetFullPathName</b> function
+    in multithreaded applications or shared library code.</div>
 
 ## -parameters
 
@@ -155,19 +156,22 @@ If the return value is greater than or equal to the value specified in
 
 <div class="alert"><b>Note</b>  Although the return value in this case is a length that includes the terminating null character, the return 
      value on success does not include the terminating null character in the count.</div>
-<div> </div>
-Multithreaded applications and shared library code should not use the 
-    <b>GetFullPathName</b> function and should avoid using relative 
-    path names. The current directory state written by the 
-    <a href="/windows/desktop/api/winbase/nf-winbase-setcurrentdirectory">SetCurrentDirectory</a> function is stored as a global 
-    variable in each process, therefore multithreaded applications cannot reliably use this value without possible 
-    data corruption from other threads that may also be reading or setting this value. This limitation also applies 
-    to the <b>SetCurrentDirectory</b> and 
-    <a href="/windows/desktop/api/winbase/nf-winbase-getcurrentdirectory">GetCurrentDirectory</a> functions. The exception being 
-    when the application is guaranteed to be running in a single thread, for example parsing file names from the 
-    command line argument string in the main thread prior to creating any additional threads. Using relative path 
-    names in multithreaded applications or shared library code can yield unpredictable results and is not 
-    supported.
+
+Relative paths passed to the <b>GetFullPathName</b> function are
+interpreted as relative to the process's current directory.
+The current directory state written by the
+<a href="/windows/desktop/api/winbase/nf-winbase-setcurrentdirectory">SetCurrentDirectory</a>
+function is global to the process and can be changed by any thread at any time.
+Applications should be aware that
+consecutive calls to the <b>GetFullPathName</b> function with a relative path
+may produce different results if the current directory changes between the two calls.
+
+To avoid problems caused by inconsistent results,
+multithreaded applications and shared library code should avoid using relative paths.
+If a relative path is received, it should be consumed exactly once,
+either by passing the relative path directly to a function like <b>CreateFile</b>,
+or by converting it to an absolute path and using the absolute path
+from that point forward.
 
 In Windows 8 and Windows Server 2012, this function is supported by the following technologies.
 

sdk-api-src/content/winbase/nf-winbase-setcurrentdirectory.md

@@ -90,8 +90,17 @@ Each process has a single current directory made up of two parts:
 <li>A disk designator that is either a drive letter followed by a colon, or a server name and share name (&#92;&#92;<i>servername</i>&#92;<i>sharename</i>)</li>
 <li>A directory on the disk designator</li>
 </ul>
-Multithreaded applications and shared library code should not use the   
-    <b>SetCurrentDirectory</b> function and should avoid using relative path names. The current directory state written by the <b>SetCurrentDirectory</b> function is stored as a global variable in each process, therefore multithreaded applications cannot reliably use this value without possible data corruption from other threads that may also be reading or setting this value. This limitation also applies to the <a href="/windows/desktop/api/winbase/nf-winbase-getcurrentdirectory">GetCurrentDirectory</a> and <a href="/windows/desktop/api/fileapi/nf-fileapi-getfullpathnamea">GetFullPathName</a> functions. The exception being when the application is guaranteed to be running in a single thread, for example parsing file names from the command line argument string in the main thread prior to creating any additional threads. Using relative path names in multithreaded applications or shared library code can yield unpredictable results and is not supported.
+
+The current directory is shared by all threads of the process:
+If one thread changes the current directory, it affects all threads
+in the process.
+Multithreaded applications and shared library code should avoid
+calling the <b>SetCurrentDirectory</b> function due to the risk of
+affecting relative path calculations being performed by other threads.
+Conversely,
+multithreaded applications and shared library code should avoid
+using relative paths so that they are unaffected by changes to the
+current directory performed by other threads.
 
 In Windows 8 and Windows Server 2012, this function is supported by the following technologies.