Skip to content

Commit ac0540d

Browse files
authored
Document breaking change: GnuTarEntry and PaxTarEntry no longer includes atime and ctime by default (#46588)
1 parent ac4f0e0 commit ac0540d

File tree

3 files changed

+60
-0
lines changed

3 files changed

+60
-0
lines changed

docs/core/compatibility/10.0.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af
3030
| [Consistent shift behavior in generic math](core-libraries/10.0/generic-math.md) | Behavioral change | Preview 1 |
3131
| [Default trace context propagator updated to W3C standard](core-libraries/10.0/default-trace-context-propagator.md) | Behavioral change | Preview 4 |
3232
| [DriveInfo.DriveFormat returns Linux filesystem types](core-libraries/10.0/driveinfo-driveformat-linux.md) | Behavioral change | Preview 6 |
33+
| [GnuTarEntry and PaxTarEntry no longer includes atime and ctime by default](core-libraries/10.0/tar-atime-ctime-default.md) | Behavioral change | Preview 5 |
3334
| [LDAP DirectoryControl parsing is now more stringent](core-libraries/10.0/ldap-directorycontrol-parsing.md) | Behavioral change | Preview 1 |
3435
| [MacCatalyst version normalization](core-libraries/10.0/maccatalyst-version-normalization.md) | Behavioral change | Preview 1 |
3536
| [.NET runtime no longer provides default SIGTERM signal handler](core-libraries/10.0/sigterm-signal-handler.md) | Behavioral change | Preview 5 |
Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
---
2+
title: "Breaking change: GnuTarEntry and PaxTarEntry exclude atime and ctime by default"
3+
description: "Learn about the breaking change in .NET 10 where GnuTarEntry and PaxTarEntry no longer automatically set access time and change time fields."
4+
ms.date: 06/05/2025
5+
ai-usage: ai-assisted
6+
ms.custom: https://github.com/dotnet/docs/issues/46465
7+
---
8+
# GnuTarEntry and PaxTarEntry exclude atime and ctime by default
9+
10+
Starting in .NET 10, <xref:System.Formats.Tar.GnuTarEntry> and <xref:System.Formats.Tar.PaxTarEntry> no longer automatically set access time (`atime`) and change time (`ctime`) fields when creating new entries. These fields are problematic in tar entries because not all tar readers support them. The fields will still be preserved when reading, and you set them directly. But they won't be set on existing entries that didn't have them to start, or when converting from other entry types.
11+
12+
The behavior of <xref:System.Formats.Tar.TarEntry.ModificationTime?displayProperty=nameWithType> is unchanged. It's initialized to <xref:System.DateTime.UtcNow> for tar entries created with a constructor, and uses the file modification time for entries created from files.
13+
14+
Other minor fixes have been made to <xref:System.Formats.Tar> to prioritize round-tripping of `TarEntry` entries from read to write without change.
15+
16+
## Version introduced
17+
18+
.NET 10 Preview 5
19+
20+
## Previous behavior
21+
22+
Previously, `GnuTarEntry` and `PaxTarEntry` always added `atime` and `ctime` values when creating new entries.
23+
24+
## New behavior
25+
26+
Starting in .NET 10, `GnuTarEntry` and `PaxTarEntry` only set `atime` and `ctime` if:
27+
28+
- The entry is read from a tar archive that already contains these fields.
29+
- The user explicitly set them using the appropriate properties.
30+
31+
The behavior of <xref:System.Formats.Tar.TarEntry.ModificationTime?displayProperty=nameWithType> remains unchanged. It's initialized to <xref:System.DateTime.UtcNow?displayProperty=nameWithType> for tar entries created with a constructor, and uses the file modification time for entries created from files.
32+
33+
## Type of breaking change
34+
35+
This is a [behavioral change](../../categories.md#behavioral-change).
36+
37+
## Reason for change
38+
39+
This change was made for better compatibility with other tar readers and to improve round-tripping of tar files without modification.
40+
41+
## Recommended action
42+
43+
No action required for most users&mdash;most archives have no use for these timestamps.
44+
45+
If you require these fields to be set, you can use the following APIs:
46+
47+
- For `GnuTarEntry`: Use the <xref:System.Formats.Tar.GnuTarEntry.AccessTime?displayProperty=nameWithType> and <xref:System.Formats.Tar.GnuTarEntry.ChangeTime?displayProperty=nameWithType> properties.
48+
- For `PaxTarEntry`: Use the constructor that accepts extended attributes: <xref:System.Formats.Tar.PaxTarEntry.%23ctor(System.Formats.Tar.TarEntryType,System.String,System.Collections.Generic.IEnumerable{System.Collections.Generic.KeyValuePair{System.String,System.String}})>.
49+
50+
However, be aware that setting these fields creates a tar file that isn't readable by many tar clients.
51+
52+
## Affected APIs
53+
54+
- <xref:System.Formats.Tar.GnuTarEntry?displayProperty=fullName>
55+
- <xref:System.Formats.Tar.PaxTarEntry?displayProperty=fullName>
56+
- <xref:System.Formats.Tar.TarReader?displayProperty=fullName>
57+
- <xref:System.Formats.Tar.TarWriter?displayProperty=fullName>

docs/core/compatibility/toc.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,8 @@ items:
2626
href: core-libraries/10.0/default-trace-context-propagator.md
2727
- name: DriveInfo.DriveFormat returns Linux filesystem types
2828
href: core-libraries/10.0/driveinfo-driveformat-linux.md
29+
- name: GnuTarEntry and PaxTarEntry exclude atime and ctime by default
30+
href: core-libraries/10.0/tar-atime-ctime-default.md
2931
- name: LDAP DirectoryControl parsing is now more stringent
3032
href: core-libraries/10.0/ldap-directorycontrol-parsing.md
3133
- name: MacCatalyst version normalization

0 commit comments

Comments
 (0)