Add remarks to last error Marshal APIs (#7334)

dotnet · Nov 5, 2021 · 07b2c6a · 07b2c6a
1 parent 8a20dff
commit 07b2c6a
Show file tree

Hide file tree

Showing 4 changed files with 108 additions and 17 deletions.
diff --git a/samples/snippets/csharp/System.Runtime.InteropServices/Marshal/GetLastPInvokeError.cs b/samples/snippets/csharp/System.Runtime.InteropServices/Marshal/GetLastPInvokeError.cs
@@ -0,0 +1,48 @@
+//<snippet1>
+using System;
+using System.Runtime.InteropServices;
+
+// These functions specify SetLastError=true to propagate the last error from the p/invoke
+// such that it can be retrieved using Marshal.GetLastPInvokeError().
+internal static class Kernel32
+{
+ [DllImport(nameof(Kernel32), ExactSpelling = true, SetLastError = true)]
+ internal static extern bool SetCurrentDirectoryW([MarshalAs(UnmanagedType.LPWStr)] string path);
+}
+
+internal static class libc
+{
+ [DllImport(nameof(libc), SetLastError = true)]
+ internal static extern int chdir([MarshalAs(UnmanagedType.LPUTF8Str)] string path);
+}
+
+class Program
+{
+ public static void Main(string[] args)
+ {
+ // Call p/invoke with valid arguments.
+ CallPInvoke(AppContext.BaseDirectory);
+
+ // Call p/invoke with invalid arguments.
+ CallPInvoke(string.Empty);
+ }
+
+ private static void CallPInvoke(string path)
+ {
+ if (OperatingSystem.IsWindows())
+ {
+ Console.WriteLine($"Calling SetCurrentDirectoryW with path '{path}'");
+ Kernel32.SetCurrentDirectoryW(path);
+ }
+ else
+ {
+ Console.WriteLine($"Calling chdir with path '{path}'");
+ libc.chdir(path);
+ }
+
+ // Get the last p/invoke error and display it.
+ int error = Marshal.GetLastPInvokeError();
+ Console.WriteLine($"Last p/invoke error: {error}");
+ }
+}
+//</snippet1>
diff --git a/samples/snippets/csharp/System.Runtime.InteropServices/Marshal/Marshal.csproj b/samples/snippets/csharp/System.Runtime.InteropServices/Marshal/Marshal.csproj
@@ -0,0 +1,8 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+ <PropertyGroup>
+ <OutputType>Exe</OutputType>
+ <TargetFramework>net6.0</TargetFramework>
+ </PropertyGroup>
+
+</Project>
diff --git a/xml/System.Runtime.InteropServices/DllImportAttribute.xml b/xml/System.Runtime.InteropServices/DllImportAttribute.xml
@@ -557,16 +557,21 @@
  <ReturnType>System.Boolean</ReturnType>
  </ReturnValue>
  <Docs>
- <summary>Indicates whether the callee calls the <see langword="SetLastError" /> Windows API function before returning from the attributed method.</summary>
+ <summary>Indicates whether the callee sets an error (<see langword="SetLastError" /> on Windows or <see langword="errno" /> on other platforms) before returning from the attributed method.</summary>
  <remarks>
  <format type="text/markdown"><![CDATA[ 
  
 ## Remarks 
- `true` to indicate that the callee will call `SetLastError`; otherwise, `false`. The default is `false`. 
- 
- The runtime marshaler calls `GetLastError` and caches the value returned to prevent it from being overwritten by other API calls. You can retrieve the error code by calling <xref:System.Runtime.InteropServices.Marshal.GetLastWin32Error%2A>. 
+ `true` to indicate that the callee will set an error via `SetLastError` on Windows or `errno` on other platforms; otherwise, `false`. The default is `false`.
  
+ If this field is set to `true`, the runtime marshaler calls `GetLastError` or `errno` and caches the value returned to prevent it from being overwritten by other API calls.
+ You can retrieve the error code by calling <xref:System.Runtime.InteropServices.Marshal.GetLastPInvokeError%2A> on .NET 6.0 and above
+ or <xref:System.Runtime.InteropServices.Marshal.GetLastWin32Error%2A> on .NET 5.0 and below or .NET Framework.
  
+ On .NET, the error information is cleared (set to `0`) before invoking the callee when this field is set to `true`. On .NET Framework, the error information is not cleared.
+ This means that error information returned by <xref:System.Runtime.InteropServices.Marshal.GetLastPInvokeError%2A> and <xref:System.Runtime.InteropServices.Marshal.GetLastWin32Error%2A>
+ on .NET represents only the error information from the last p/invoke with <xref:System.Runtime.InteropServices.DllImportAttribute.SetLastError?displayProperty=nameWithType>
+ set to `true`. On .NET Framework, the error information can persist from one p/invoke to the next.
  
 ## Examples 
  In some cases, Visual Basic developers use the <xref:System.Runtime.InteropServices.DllImportAttribute>, instead of using the `Declare` statement, to define a DLL function in managed code. Setting the <xref:System.Runtime.InteropServices.DllImportAttribute.SetLastError> field is one of those cases. 
@@ -577,6 +582,7 @@
  
  ]]></format>
  </remarks>
+ <altmember cref="M:System.Runtime.InteropServices.Marshal.GetLastPInvokeError" />
  <altmember cref="M:System.Runtime.InteropServices.Marshal.GetLastWin32Error" />
  </Docs>
  </Member>

diff --git a/xml/System.Runtime.InteropServices/Marshal.xml b/xml/System.Runtime.InteropServices/Marshal.xml
@@ -4362,15 +4362,31 @@
  </ReturnValue>
  <Parameters />
  <Docs>
- <summary>Get the last platform invoke error on the current thread</summary>
- <returns>The last platform invoke error</returns>
+ <summary>Get the last platform invoke error on the current thread.</summary>
+ <returns>The last platform invoke error.</returns>
  <remarks>
  <format type="text/markdown"><![CDATA[
 
 ## Remarks
 
-The last platform invoke error corresponds to the error set by either the most recent platform
- invoke that was configured to set the last error or a call to <xref:System.Runtime.InteropServices.Marshal.SetLastPInvokeError(System.Int32)>.
+The last platform invoke error corresponds to the error set either by the most recent platform invoke that was
+configured with <xref:System.Runtime.InteropServices.DllImportAttribute.SetLastError?displayProperty=nameWithType>
+set to `true` or by a call to <xref:System.Runtime.InteropServices.Marshal.SetLastPInvokeError(System.Int32)>,
+whichever happened last.
+
+This method will only return errors set via the mentioned scenarios. To get the last system error independent of
+platform invoke usage, use <xref:System.Runtime.InteropServices.Marshal.GetLastSystemError%2A>.
+
+This method is functionally equivalent to <xref:System.Runtime.InteropServices.Marshal.GetLastWin32Error%2A>. It is
+named to better reflect the intent of the API and its cross-platform nature. <xref:System.Runtime.InteropServices.Marshal.GetLastPInvokeError%2A>
+should be preferred over <xref:System.Runtime.InteropServices.Marshal.GetLastWin32Error%2A>.
+
+## Examples
+
+The following example defines a p/invoke with <xref:System.Runtime.InteropServices.DllImportAttribute.SetLastError?displayProperty=nameWithType>
+set to `true` and demonstrates using <xref:System.Runtime.InteropServices.Marshal.GetLastPInvokeError%2A> to get the last p/invoke error.
+
+:::code language="csharp" source="~/samples/snippets/csharp/System.Runtime.InteropServices/Marshal/GetLastPInvokeError.cs" id="Snippet1":::
 
  ]]></format>
  </remarks>
@@ -4399,14 +4415,17 @@ The last platform invoke error corresponds to the error set by either the most r
  </ReturnValue>
  <Parameters />
  <Docs>
- <summary>Get the last system error on the current thread</summary>
- <returns>The last system error</returns>
+ <summary>Gets the last system error on the current thread.</summary>
+ <returns>The last system error.</returns>
  <remarks>
  <format type="text/markdown"><![CDATA[
 
 ## Remarks
 
-The error is that for the current operating system (e.g. errno on Unix, GetLastError on Windows)
+The system error is based on the current operating system&mdash;that is, `errno` on non-Windows and [GetLastError](/windows/win32/api/errhandlingapi/nf-errhandlingapi-getlasterror) on Windows.
+
+This method is provided as a low-level API to allow getting the current system error in a cross-platform manner. It is not tied to
+platform invoke usage. To get the last platform invoke error, use <xref:System.Runtime.InteropServices.Marshal.GetLastPInvokeError%2A>.
 
  ]]></format>
  </remarks>
@@ -4473,6 +4492,8 @@ You can use this method to obtain error codes only if you apply the <xref:System
 
 There is a difference in the behavior of the `GetLastWin32Error` method on .NET Core and .NET Framework when <xref:System.Runtime.InteropServices.DllImportAttribute.SetLastError?displayProperty=nameWithType> is `true`. On .NET Framework, the `GetLastWin32Error` method can retain error information from one P/Invoke call to the next. On .NET Core, error information is cleared before P/Invoke call, and the `GetLastWin32Error` represents only error information from the last method call.
 
+On .NET 6 and later versions, this method is functionally equivalent to <xref:System.Runtime.InteropServices.Marshal.GetLastPInvokeError%2A>, which is named to better reflect the intent of the API and its cross-platform nature. <xref:System.Runtime.InteropServices.Marshal.GetLastPInvokeError%2A> should be preferred over <xref:System.Runtime.InteropServices.Marshal.GetLastWin32Error%2A>.
+
 ## Examples 
  The following example calls the `GetLastWin32Error` method. The example first demonstrates calling the method with no error present and then demonstrates calling the method with an error present. 
 
@@ -9692,9 +9713,17 @@ There is a difference in the behavior of the `GetLastWin32Error` method on .NET
  <Parameter Name="error" Type="System.Int32" Index="0" FrameworkAlternate="net-6.0" />
  </Parameters>
  <Docs>
- <param name="error">Error to set</param>
- <summary>Set the last platform invoke error on the current thread</summary>
- <remarks>To be added.</remarks>
+ <param name="error">The error to set.</param>
+ <summary>Sets the last platform invoke error on the current thread.</summary>
+ <remarks>
+ <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+The last platform invoke error is stored per-thread and can be retrieved using <xref:System.Runtime.InteropServices.Marshal.GetLastPInvokeError%2A>.
+
+ ]]></format>
+ </remarks>
  </Docs>
  </Member>
  <Member MemberName="SetLastSystemError">
@@ -9722,14 +9751,14 @@ There is a difference in the behavior of the `GetLastWin32Error` method on .NET
  <Parameter Name="error" Type="System.Int32" Index="0" FrameworkAlternate="net-6.0" />
  </Parameters>
  <Docs>
- <param name="error">Error to set</param>
- <summary>Set the last system error on the current thread</summary>
+ <param name="error">The error to set.</param>
+ <summary>Sets the last system error on the current thread.</summary>
  <remarks>
  <format type="text/markdown"><![CDATA[
 
 ## Remarks
 
-The error is that for the current operating system (e.g. errno on Unix, SetLastError on Windows)
+The system error is based on the current operating system&mdash;that is, `errno` on Unix and [SetLastError](/windows/win32/api/errhandlingapi/nf-errhandlingapi-setlasterror) on Windows.
 
  ]]></format>
  </remarks>