Document symbolic link and junction extraction behavior for TarFile and ZipFile (#12009)

Author: iremyux

xml/System.Formats.Tar/TarFile.xml

@@ -223,6 +223,7 @@
           <see langword="true" /> to overwrite files and directories in <paramref name="destinationDirectoryName" />; <see langword="false" /> to avoid overwriting, and throw if any files or directories are found with existing names.</param>
         <summary>Extracts the contents of a stream that represents a tar archive into the specified directory.</summary>
         <remarks>
+          <para>If a symbolic link or junction in the tar archive results in a file being extracted outside the specified <paramref name="destinationDirectoryName" />, an <see cref="T:System.IO.IOException" /> is thrown to ensure extraction remains within the same directory.</para>
           <para>Files of type <see cref="F:System.Formats.Tar.TarEntryType.BlockDevice" />, <see cref="F:System.Formats.Tar.TarEntryType.CharacterDevice" />, or <see cref="F:System.Formats.Tar.TarEntryType.Fifo" /> can only be extracted in Unix platforms.</para>
           <para>Elevation is required to extract a <see cref="F:System.Formats.Tar.TarEntryType.BlockDevice" /> or <see cref="F:System.Formats.Tar.TarEntryType.CharacterDevice" /> to disk.</para>
         </remarks>
@@ -273,6 +274,7 @@ Extracting one of the tar entries would have resulted in a file outside the spec
           <see langword="true" /> to overwrite files and directories in <paramref name="destinationDirectoryName" />; <see langword="false" /> to avoid overwriting, and throw if any files or directories are found with existing names.</param>
         <summary>Extracts the contents of a tar file into the specified directory.</summary>
         <remarks>
+          <para>If a symbolic link or junction in the tar archive results in a file being extracted outside the specified <paramref name="destinationDirectoryName" />, an <see cref="T:System.IO.IOException" /> is thrown to ensure extraction remains within the same directory.</para>
           <para>Files of type <see cref="F:System.Formats.Tar.TarEntryType.BlockDevice" />, <see cref="F:System.Formats.Tar.TarEntryType.CharacterDevice" />, or <see cref="F:System.Formats.Tar.TarEntryType.Fifo" /> can only be extracted in Unix platforms.</para>
           <para>Elevation is required to extract a <see cref="F:System.Formats.Tar.TarEntryType.BlockDevice" /> or <see cref="F:System.Formats.Tar.TarEntryType.CharacterDevice" /> to disk.</para>
         </remarks>
@@ -322,6 +324,7 @@ Extracting one of the tar entries would have resulted in a file outside the spec
         <summary>Asynchronously extracts the contents of a stream that represents a tar archive into the specified directory.</summary>
         <returns>A task that represents the asynchronous extraction operation.</returns>
         <remarks>
+          <para>If a symbolic link or junction in the tar archive results in a file being extracted outside the specified <paramref name="destinationDirectoryName" />, an <see cref="T:System.IO.IOException" /> is thrown to ensure extraction remains within the same directory.</para>
           <para>Files of type <see cref="F:System.Formats.Tar.TarEntryType.BlockDevice" />, <see cref="F:System.Formats.Tar.TarEntryType.CharacterDevice" />, or <see cref="F:System.Formats.Tar.TarEntryType.Fifo" /> can only be extracted in Unix platforms.</para>
           <para>Elevation is required to extract a <see cref="F:System.Formats.Tar.TarEntryType.BlockDevice" /> or <see cref="F:System.Formats.Tar.TarEntryType.CharacterDevice" /> to disk.</para>
           <para>This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as <see cref="T:System.ArgumentException" />, are still thrown synchronously. For the stored exceptions, see the exceptions thrown by <see cref="M:System.Formats.Tar.TarFile.ExtractToDirectory(System.IO.Stream,System.String,System.Boolean)" />.</para>
@@ -376,6 +379,7 @@ Extracting one of the tar entries would have resulted in a file outside the spec
         <summary>Asynchronously extracts the contents of a tar file into the specified directory.</summary>
         <returns>A task that represents the asynchronous extraction operation.</returns>
         <remarks>
+          <para>If a symbolic link or junction in the tar archive results in a file being extracted outside the specified <paramref name="destinationDirectoryName" />, an <see cref="T:System.IO.IOException" /> is thrown to ensure extraction remains within the same directory.</para>
           <para>Files of type <see cref="F:System.Formats.Tar.TarEntryType.BlockDevice" />, <see cref="F:System.Formats.Tar.TarEntryType.CharacterDevice" />, or <see cref="F:System.Formats.Tar.TarEntryType.Fifo" /> can only be extracted in Unix platforms.</para>
           <para>Elevation is required to extract a <see cref="F:System.Formats.Tar.TarEntryType.BlockDevice" /> or <see cref="F:System.Formats.Tar.TarEntryType.CharacterDevice" /> to disk.</para>
           <para>This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as <see cref="T:System.ArgumentException" />, are still thrown synchronously. For the stored exceptions, see the exceptions thrown by <see cref="M:System.Formats.Tar.TarFile.ExtractToDirectory(System.String,System.String,System.Boolean)" />.</para>

xml/System.IO.Compression/ZipFile.xml

@@ -1021,6 +1021,7 @@ An I/O error occurred while opening a file to be archived.</exception>
         <remarks>This method creates the specified directory and all subdirectories. The destination directory cannot already exist.
             Exceptions related to validating the paths in the <paramref name="destinationDirectoryName" /> or the files in the zip archive contained in <paramref name="source" /> parameters are thrown before extraction. Otherwise, if an error occurs during extraction, the archive remains partially extracted.
             Each extracted file has the same relative path to the directory specified by <paramref name="destinationDirectoryName" /> as its source entry has to the root of the archive.
+            If an entry in the zip archive is a symbolic link, it's extracted as a regular folder since symbolic link information isn't preserved in the ZIP format.
             If a file to be archived has an invalid last modified time, the first date and time representable in the zip timestamp format (midnight on January 1, 1980) will be used.</remarks>
         <exception cref="T:System.ArgumentException">
           <paramref name="destinationDirectoryName" /> is <see cref="F:System.String.Empty" />, contains only white space, or contains at least one invalid character.</exception>
@@ -1100,6 +1101,8 @@ An archive entry was compressed by using a compression method that isn't support
 ## Remarks
  This method creates the specified directory and all subdirectories. The destination directory cannot already exist. Exceptions related to validating the paths in the `destinationDirectoryName` or `sourceArchiveFileName` parameters are thrown before extraction. Otherwise, if an error occurs during extraction, the archive remains partially extracted. Each extracted file has the same relative path to the directory specified by `destinationDirectoryName` as its source entry has to the root of the archive.
 
+ If an entry in the zip archive is a symbolic link, it's extracted as a regular folder since symbolic link information isn't preserved in the ZIP format.
+
 ## Examples
  This example shows how to create and extract a zip archive by using the <xref:System.IO.Compression.ZipFile> class. It compresses the contents of a folder into a zip archive and extracts that content to a new folder. To use the <xref:System.IO.Compression.ZipFile> class, you must reference the `System.IO.Compression.FileSystem` assembly in your project.
 
@@ -1174,6 +1177,7 @@ An archive entry was compressed by using a compression method that isn't support
         <remarks>This method creates the specified directory and all subdirectories. The destination directory cannot already exist.
             Exceptions related to validating the paths in the <paramref name="destinationDirectoryName" /> or the files in the zip archive contained in <paramref name="source" /> parameters are thrown before extraction. Otherwise, if an error occurs during extraction, the archive remains partially extracted.
             Each extracted file has the same relative path to the directory specified by <paramref name="destinationDirectoryName" /> as its source entry has to the root of the archive.
+            If an entry in the zip archive is a symbolic link, it's extracted as a regular folder since symbolic link information isn't preserved in the ZIP format.
             If a file to be archived has an invalid last modified time, the first date and time representable in the zip timestamp format (midnight on January 1, 1980) will be used.</remarks>
         <exception cref="T:System.ArgumentException">
           <paramref name="destinationDirectoryName" /> is <see cref="F:System.String.Empty" />, contains only white space, or contains at least one invalid character.</exception>
@@ -1330,6 +1334,8 @@ Each entry will be extracted such that the extracted file has the same relative
 
 The `sourceArchiveFileName` and `destinationDirectoryName` parameters accept both relative and absolute paths. A relative path is interpreted as relative to the current working directory.
 
+If an entry in the zip archive is a symbolic link, it's extracted as a regular folder since symbolic link information isn't preserved in the ZIP format.
+
 If a file to be archived has an invalid last modified time, the first date and time representable in the zip timestamp format (midnight on January 1, 1980) will be used.
 
           ]]></format>
@@ -1436,6 +1442,8 @@ A <see cref="T:System.IO.Compression.ZipArchiveEntry" /> has been compressed usi
 
 This method creates the specified directory and all subdirectories, if necessary. Exceptions related to validating the paths in the `destinationDirectoryName` or `sourceArchiveFileName` parameters are thrown before extraction. Otherwise, if an error occurs during extraction, the archive remains partially extracted. Each extracted file has the same relative path to the directory specified by `destinationDirectoryName` as its source entry has to the root of the archive.
 
+If an entry in the zip archive is a symbolic link, it's extracted as a regular folder since symbolic link information isn't preserved in the ZIP format.
+
 If `entryNameEncoding` is set to a value other than `null`, entry names and comments are decoded according to the following rules:
 
 - For entries where the language encoding flag (in the general-purpose bit flag of the local file header) is not set, the entry names and comments are decoded by using the specified encoding.
@@ -1526,6 +1534,7 @@ If `entryNameEncoding` is set to `null`, entry names and comments are decoded ac
         <remarks>This method creates the specified directory and all subdirectories. The destination directory cannot already exist.
             Exceptions related to validating the paths in the <paramref name="destinationDirectoryName" /> or the files in the zip archive contained in <paramref name="source" /> parameters are thrown before extraction. Otherwise, if an error occurs during extraction, the archive remains partially extracted.
             Each extracted file has the same relative path to the directory specified by <paramref name="destinationDirectoryName" /> as its source entry has to the root of the archive.
+            If an entry in the zip archive is a symbolic link, it's extracted as a regular folder since symbolic link information isn't preserved in the ZIP format.
             If a file to be archived has an invalid last modified time, the first date and time representable in the zip timestamp format (midnight on January 1, 1980) will be used.</remarks>
         <exception cref="T:System.ArgumentException">
           <paramref name="destinationDirectoryName" /> is <see cref="F:System.String.Empty" />, contains only white space, or contains at least one invalid character.
@@ -1622,6 +1631,8 @@ An archive entry was compressed by using a compression method that isn't support
 
  The `sourceArchiveFileName` and `destinationDirectoryName` parameters accept both relative and absolute paths. A relative path is interpreted as relative to the current working directory.
 
+ If an entry in the zip archive is a symbolic link, it's extracted as a regular folder since symbolic link information isn't preserved in the ZIP format.
+
  If a file to be archived has an invalid last modified time, the first date and time representable in the zip timestamp format (midnight on January 1, 1980) will be used.
 
 ]]></format>