Merge main into live

snippets/csharp/System.Diagnostics/Process/StandardOutput/stdoutput-async.cs

@@ -3,31 +3,31 @@
 
 public class Example
 {
-   public static void Main()
-   {
-      var p = new Process();  
-      p.StartInfo.UseShellExecute = false;  
-      p.StartInfo.RedirectStandardOutput = true;  
-      string eOut = null;
-      p.StartInfo.RedirectStandardError = true;
-      p.ErrorDataReceived += new DataReceivedEventHandler((sender, e) => 
-                                 { eOut += e.Data; });
-      p.StartInfo.FileName = "Write500Lines.exe";  
-      p.Start();  
+    public static void Main()
+    {
+        var p = new Process();
+        p.StartInfo.UseShellExecute = false;
+        p.StartInfo.RedirectStandardOutput = true;
+        string eOut = null;
+        p.StartInfo.RedirectStandardError = true;
+        p.ErrorDataReceived += new DataReceivedEventHandler((sender, e) =>
+                                   { eOut += e.Data; });
+        p.StartInfo.FileName = "Write500Lines.exe";
+        p.Start();
 
-      // To avoid deadlocks, use an asynchronous read operation on at least one of the streams.  
-      p.BeginErrorReadLine();
-      string output = p.StandardOutput.ReadToEnd();  
-      p.WaitForExit();
+        // To avoid deadlocks, use an asynchronous read operation on at least one of the streams.  
+        p.BeginErrorReadLine();
+        string output = p.StandardOutput.ReadToEnd();
+        p.WaitForExit();
 
-      Console.WriteLine($"The last 50 characters in the output stream are:\n'{output.Substring(output.Length - 50)}'");
-      Console.WriteLine($"\nError stream: {eOut}");
-   }
+        Console.WriteLine($"The last 50 characters in the output stream are:\n'{output.Substring(output.Length - 50)}'");
+        Console.WriteLine($"\nError stream: {eOut}");
+    }
 }
 // The example displays the following output:
 //      The last 50 characters in the output stream are:
-//      ' 49,800.20%
-//      Line 500 of 500 written: 49,900.20%
+//      'ritten: 99,80%
+//      Line 500 of 500 written: 100,00%
 //      '
 //
 //      Error stream: Successfully wrote 500 lines.

snippets/csharp/System.Diagnostics/Process/StandardOutput/stdoutput-sync.cs

@@ -3,25 +3,25 @@
 
 public class Example2
 {
-   public static void Main()
-   {
-      var p = new Process();  
-      p.StartInfo.UseShellExecute = false;  
-      p.StartInfo.RedirectStandardOutput = true;  
-      p.StartInfo.FileName = "Write500Lines.exe";  
-      p.Start();  
+    public static void Main()
+    {
+        var p = new Process();
+        p.StartInfo.UseShellExecute = false;
+        p.StartInfo.RedirectStandardOutput = true;
+        p.StartInfo.FileName = "Write500Lines.exe";
+        p.Start();
 
-      // To avoid deadlocks, always read the output stream first and then wait.  
-      string output = p.StandardOutput.ReadToEnd();  
-      p.WaitForExit();
+        // To avoid deadlocks, always read the output stream first and then wait.  
+        string output = p.StandardOutput.ReadToEnd();
+        p.WaitForExit();
 
-      Console.WriteLine($"The last 50 characters in the output stream are:\n'{output.Substring(output.Length - 50)}'");
-   }
+        Console.WriteLine($"The last 50 characters in the output stream are:\n'{output.Substring(output.Length - 50)}'");
+    }
 }
 // The example displays the following output:
 //      Successfully wrote 500 lines.
 //
 //      The last 50 characters in the output stream are:
-//      ' 49,800.20%
-//      Line 500 of 500 written: 49,900.20%
+//      'ritten: 99,80%
+//      Line 500 of 500 written: 100,00%
 //      '

snippets/csharp/System.Diagnostics/Process/StandardOutput/write500lines.cs

@@ -1,20 +1,22 @@
 using System;
-using System.IO;
 
 public class Example3
 {
-   public static void Main()
-   {
-      for (int ctr = 0; ctr < 500; ctr++)
-         Console.WriteLine($"Line {ctr + 1} of 500 written: {ctr + 1/500.0:P2}");
+    public static void Main()
+    {
+        for (int ctr = 0; ctr < 500; ctr++)
+            Console.WriteLine($"Line {ctr + 1} of 500 written: {(ctr + 1) / 500.0:P2}");
 
-      Console.Error.WriteLine("\nSuccessfully wrote 500 lines.\n");
-   }
+        Console.Error.WriteLine("\nSuccessfully wrote 500 lines.\n");
+    }
 }
 // The example displays the following output:
-//      The last 50 characters in the output stream are:
-//      ' 49,800.20%
-//      Line 500 of 500 written: 49,900.20%
-//'
+//      Line 1 of 500 written: 0,20%
+//      Line 2 of 500 written: 0,40%
+//      Line 3 of 500 written: 0,60%
+//      ...
+//      Line 498 of 500 written: 99,60%
+//      Line 499 of 500 written: 99,80%
+//      Line 500 of 500 written: 100,00%
 //
-//      Error stream: Successfully wrote 500 lines.
+//      Successfully wrote 500 lines.

snippets/csharp/System.IO/StreamReader/Read/strmreader read2.cs

@@ -32,7 +32,7 @@ public static void Main()
                 while (sr.Peek() >= 0)
                 {
                     c = new char[5];
-                    sr.Read(c, 0, c.Length);
+                    sr.ReadBlock(c, 0, c.Length);
                     //The output will look odd, because
                     //only five characters are read at a time.
                     Console.WriteLine(c);

snippets/fsharp/System.Diagnostics/Process/StandardOutput/stdoutput-async.fs

@@ -21,8 +21,8 @@ printfn $"The last 50 characters in the output stream are:\n'{output.Substring(o
 printfn $"\nError stream: {eOut}"
 // The example displays the following output:
 //      The last 50 characters in the output stream are:
-//      ' 49,800.20%
-//      Line 500 of 500 written: 49,900.20%
+//      'ritten: 99,80%
+//      Line 500 of 500 written: 100,00%
 //      '
 //
 //      Error stream: Successfully wrote 500 lines.

snippets/fsharp/System.Diagnostics/Process/StandardOutput/stdoutput-sync.fs

@@ -15,8 +15,7 @@ p.WaitForExit()
 printfn $"The last 50 characters in the output stream are:\n'{output.Substring(output.Length - 50)}'"
 // The example displays the following output:
 //      Successfully wrote 500 lines.
-//
 //      The last 50 characters in the output stream are:
-//      ' 49,800.20%
-//      Line 500 of 500 written: 49,900.20%
+//      'ritten: 99,80%
+//      Line 500 of 500 written: 100,00%
 //      '

snippets/fsharp/System.Diagnostics/Process/StandardOutput/write500lines.fs

@@ -5,9 +5,11 @@ for i in 1. .. 500. do
 
 eprintfn "Successfully wrote 500 lines.";
 // The example displays the following output:
-//      The last 50 characters in the output stream are:
-//      ' 49,800.20%
-//      Line 500 of 500 written: 49,900.20%
-//'
-//
-//      Error stream: Successfully wrote 500 lines.
+//      Line 1 of 500 written: 0,20%
+//      Line 2 of 500 written: 0,40%
+//      Line 3 of 500 written: 0,60%
+//      ...
+//      Line 498 of 500 written: 99,60%
+//      Line 499 of 500 written: 99,80%
+//      Line 500 of 500 written: 100,00%
+//      Successfully wrote 500 lines.

snippets/visualbasic/api/system.diagnostics/process/standardoutput/Write500Lines.vb

@@ -3,16 +3,19 @@
 Public Module Example
    Public Sub Main()
       For ctr As Integer = 0 To 499
-         Console.WriteLine($"Line {ctr + 1} of 500 written: {ctr + 1/500.0:P2}")
+         Console.WriteLine($"Line {ctr + 1} of 500 written: {(ctr + 1) / 500.0:P2}")
       Next
 
       Console.Error.WriteLine($"{vbCrLf}Successfully wrote 500 lines.{vbCrLf}")
    End Sub
 End Module
 ' The example displays the following output:
-'      The last 50 characters in the output stream are:
-'      ' 49,800.20%
-'      Line 500 of 500 written: 49,900.20%
+'      Line 1 of 500 written 0,20%
+'      Line 2 of 500 written: 0,40%
+'      Line 3 of 500 written: 0,60%
+'      ...
+'      Line 498 of 500 written: 99,60%
+'      Line 499 of 500 written: 99,80%
+'      Line 500 of 500 written: 100,00%
 '
-'
-'      Error stream: Successfully wrote 500 lines.
+'      Successfully wrote 500 lines.

snippets/visualbasic/api/system.diagnostics/process/standardoutput/stdoutput-async.vb

@@ -22,8 +22,8 @@ Public Module Example
 End Module
 ' The example displays the following output:
 '      The last 50 characters in the output stream are:
-'      ' 49,800.20%
-'      Line 500 of 500 written: 49,900.20%
+'      'ritten: 99,80%
+'      Line 500 of 500 written: 100,00%
 '      '
 '
 '      Error stream: Successfully wrote 500 lines.

snippets/visualbasic/api/system.diagnostics/process/standardoutput/stdoutput-sync.vb

@@ -19,6 +19,6 @@ End Module
 '      Successfully wrote 500 lines.
 '
 '      The last 50 characters in the output stream are:
-'      ' 49,800.20%
-'      Line 500 of 500 written: 49,900.20%
+'      'ritten: 99,80%
+'      Line 500 of 500 written: 100,00%
 '      '

xml/System.Buffers/ReadOnlySequence`1.xml

@@ -463,9 +463,9 @@
       </Parameters>
       <Docs>
         <param name="position">The <see cref="T:System.SequencePosition" /> of which to get the offset.</param>
-        <summary>Returns the offset of a <paramref name="position" /> within this sequence from the start.</summary>
-        <returns>The offset from the start of the sequence.</returns>
-        <remarks>To be added.</remarks>
+        <summary>Returns the offset of a <paramref name="position" /> within this sequence.</summary>
+        <returns>The offset in the sequence.</returns>
+        <remarks>The returned offset is not a zero-based index from the start. To obtain the zero-based index offset, subtract <code>mySequence.GetOffset(mySequence.Start)</code> from the returned offset.</remarks>
         <exception cref="T:System.ArgumentOutOfRangeException">The position is out of range.</exception>
       </Docs>
     </Member>

xml/System.Diagnostics/Process.xml

@@ -110,6 +110,12 @@
 
  A system process is uniquely identified on the system by its process identifier. Like many Windows resources, a process is also identified by its handle, which might not be unique on the computer. A handle is the generic term for an identifier of a resource. The operating system persists the process handle, which is accessed through the <xref:System.Diagnostics.Process.Handle%2A> property of the <xref:System.Diagnostics.Process> component, even when the process has exited. Thus, you can get the process's administrative information, such as the <xref:System.Diagnostics.Process.ExitCode%2A> (usually either zero for success or a nonzero error code) and the <xref:System.Diagnostics.Process.ExitTime%2A>. Handles are an extremely valuable resource, so leaking handles is more virulent than leaking memory.
 
+On macOS, the following properties return 0:
+
+ - <xref:System.Diagnostics.Process.PeakVirtualMemorySize64>
+ - <xref:System.Diagnostics.Process.PrivateMemorySize64>
+ - <xref:System.Diagnostics.Process.PeakWorkingSet64>
+
 > [!NOTE]
 >  This class contains a link demand and an inheritance demand at the class level that applies to all members. A <xref:System.Security.SecurityException> is thrown when either the immediate caller or the derived class does not have full-trust permission. For details about security demands, see [Link Demands](/dotnet/framework/misc/link-demands).
 

xml/System.IO/Path.xml

@@ -2175,12 +2175,19 @@ If the current Windows version exposes the [`GetTempPath2`](https://learn.micros
 
 On Windows versions that don't expose GetTempPath2, this method instead invokes the [`GetTempPath`](https://learn.microsoft.com/windows/win32/api/fileapi/nf-fileapi-gettemppathw) Win32 API and returns the resolved path. For more information on how this resolution is performed, including how to control the return value through the use of environment variables, see [the _Remarks_ section](https://learn.microsoft.com/windows/win32/api/fileapi/nf-fileapi-gettemppathw#remarks) of the GetTempPath documentation.
 
+# [MacOS](#tab/macos)
+
+If the `TMPDIR` environment variable has been set, this method returns the value specified by that environment variable. MacOS sets `TMPDIR` on login to a per-user temporary directory.
+
+Otherwise, this method returns `/tmp/`.
+
 # [Linux](#tab/linux)
 
 If the `TMPDIR` environment variable has been set, this method returns the value specified by that environment variable.
 
 Otherwise, this method returns `/tmp/`.
-
+The `/tmp/` directory on Linux is commonly shared among all users (`1777` permissions); ensure this meets your application's security needs.
+
 ---
 
 ## Examples

xml/System.IO/StreamReader.xml

@@ -974,13 +974,13 @@
         <param name="stream">The stream to be read.</param>
         <param name="encoding">The character encoding to use.</param>
         <param name="detectEncodingFromByteOrderMarks">Indicates whether to look for byte order marks at the beginning of the file.</param>
-        <param name="bufferSize">The minimum buffer size.</param>
+        <param name="bufferSize">The minimum buffer size, in bytes.</param>
         <summary>Initializes a new instance of the <see cref="T:System.IO.StreamReader" /> class for the specified stream, with the specified character encoding, byte order mark detection option, and buffer size.</summary>
         <remarks>
           <format type="text/markdown"><![CDATA[
 
 ## Remarks
- The buffer size, in number of 16-bit characters, is set by the `bufferSize` parameter. If `bufferSize` is less than the minimum allowable size (128 characters), the minimum allowable size is used.
+ The buffer size, in bytes, is set by the `bufferSize` parameter. If `bufferSize` is less than the minimum allowable size (128 bytes), the minimum allowable size is used.
 
  This constructor allows you to change the encoding the first time you read from the <xref:System.IO.StreamReader> object. The `detectEncodingFromByteOrderMarks` parameter detects the encoding by looking at the first four bytes of the stream. It automatically recognizes UTF-8, little-endian UTF-16, big-endian UTF-16, little-endian UTF-32, and big-endian UTF-32 text if the file starts with the appropriate byte order marks. Otherwise, the user-provided encoding is used. See the <xref:System.Text.Encoding.GetPreamble%2A?displayProperty=nameWithType> method for more information.
 
@@ -1008,7 +1008,7 @@
         <exception cref="T:System.ArgumentNullException">
           <paramref name="stream" /> or <paramref name="encoding" /> is <see langword="null" />.</exception>
         <exception cref="T:System.ArgumentOutOfRangeException">
-          <paramref name="bufferSize" /> is less than or equal to zero.</exception>
+          <paramref name="bufferSize" /> is less than or equal to zero, except for -1, which is allowed to indicate the default buffer size.</exception>
         <altmember cref="T:System.Text.Encoding" />
         <related type="Article" href="/dotnet/standard/io/">File and Stream I/O</related>
         <related type="Article" href="/dotnet/standard/io/how-to-read-text-from-a-file">How to: Read Text from a File</related>
@@ -1077,7 +1077,7 @@
         <param name="path">The complete file path to be read.</param>
         <param name="encoding">The character encoding to use.</param>
         <param name="detectEncodingFromByteOrderMarks">Indicates whether to look for byte order marks at the beginning of the file.</param>
-        <param name="bufferSize">The minimum buffer size, in number of 16-bit characters.</param>
+        <param name="bufferSize">The minimum buffer size, in bytes.</param>
         <summary>Initializes a new instance of the <see cref="T:System.IO.StreamReader" /> class for the specified file name, with the specified character encoding, byte order mark detection option, and buffer size.</summary>
         <remarks>
           <format type="text/markdown"><![CDATA[
@@ -1087,7 +1087,7 @@
 
  This constructor allows you to change the encoding the first time you read from the <xref:System.IO.StreamReader> object. The `detectEncodingFromByteOrderMarks` parameter detects the encoding by looking at the first four bytes of the stream. It automatically recognizes UTF-8, little-endian UTF-16, big-endian UTF-16, little-endian UTF-32, and big-endian UTF-32 text if the file starts with the appropriate byte order marks. Otherwise, the user-provided encoding is used. See the <xref:System.Text.Encoding.GetPreamble%2A?displayProperty=nameWithType> method for more information.
 
- The buffer size, in number of 16-bit characters, is set by the `bufferSize` parameter. If `bufferSize` is less than the minimum allowable size (128 characters), the minimum allowable size is used.
+ The buffer size, in bytes, is set by the `bufferSize` parameter. If `bufferSize` is less than the minimum allowable size (128 bytes), the minimum allowable size is used.
 
  The `path` parameter can be a file name, including a file on a Universal Naming Convention (UNC) share.
 
@@ -1115,7 +1115,7 @@
         <exception cref="T:System.NotSupportedException">
           <paramref name="path" /> includes an incorrect or invalid syntax for file name, directory name, or volume label.</exception>
         <exception cref="T:System.ArgumentOutOfRangeException">
-          <paramref name="bufferSize" /> is less than or equal to zero.</exception>
+          <paramref name="bufferSize" /> is less than or equal to zero, except for -1, which is allowed to indicate the default buffer size.</exception>
         <altmember cref="T:System.Text.Encoding" />
         <related type="Article" href="/dotnet/standard/io/">File and Stream I/O</related>
         <related type="Article" href="/dotnet/standard/io/how-to-read-text-from-a-file">How to: Read Text from a File</related>
@@ -1249,7 +1249,7 @@
         <param name="encoding">The character encoding to use.</param>
         <param name="detectEncodingFromByteOrderMarks">
           <see langword="true" /> to look for byte order marks at the beginning of the file; otherwise, <see langword="false" />.</param>
-        <param name="bufferSize">The minimum buffer size.</param>
+        <param name="bufferSize">The minimum buffer size, in bytes.</param>
         <param name="leaveOpen">
           <see langword="true" /> to leave the stream open after the <see cref="T:System.IO.StreamReader" /> object is disposed; otherwise, <see langword="false" />.</param>
         <summary>Initializes a new instance of the <see cref="T:System.IO.StreamReader" /> class for the specified stream based on the specified character encoding, byte order mark detection option, and buffer size, and optionally leaves the stream open.</summary>
@@ -1259,7 +1259,7 @@
 ## Remarks
  Unless you set the `leaveOpen` parameter to `true`, the <xref:System.IO.StreamReader> object calls <xref:System.IO.Stream.Dispose> on the provided <xref:System.IO.Stream> object when <xref:System.IO.StreamReader.Dispose%2A?displayProperty=nameWithType> is called.
 
- The buffer size, in number of 16-bit characters, is set by the `bufferSize` parameter. If `bufferSize` is less than the minimum allowable size (128 characters), the minimum allowable size is used.
+ The buffer size, in bytes, is set by the `bufferSize` parameter. If `bufferSize` is less than the minimum allowable size (128 bytes), the minimum allowable size is used.
 
  This constructor enables you to change the encoding the first time you read from the <xref:System.IO.StreamReader> object. If the `detectEncodingFromByteOrderMarks` parameter is `true`, the constructor detects the encoding by looking at the first four bytes of the stream. It automatically recognizes UTF-8, little-endian UTF-16, big-endian UTF-16, little-endian UTF-32, and big-endian UTF-32 text if the file starts with the appropriate byte order marks. Otherwise, the user-provided encoding is used. See the <xref:System.Text.Encoding.GetPreamble%2A?displayProperty=nameWithType> method for more information.