Description
Background and motivation
In the initial PR implementing the new System.Formats.Tar APIs, @stephentoub suggested we consider merging the DeviceMajor and DeviceMajor public properties into one.
The device major and device minor values are used in Unix to uniquely identify character device and block device files.
The suggestion to merge them into a single API makes sense because:
- We would rarely need to consume the properties individually. If we use one, we will most likely use the other one too.
- The P/Invoke already retrieves major and minor into a single one and then sets both major and minor at the same time in the
TarEntryheader. - When extracting a character or block device into a Unix system, we read both values together to pass them to the P/Invoke that creates the file.
API Proposal
The major and minor numbers are available in Ustar, Pax and Gnu.
public abstract partial class PosixTarEntry : TarEntry
{
internal PosixTarEntry() { }
- public int DeviceMajor { get; set; }
- public int DeviceMinor { get; set; }
public string GroupName { get; set; }
public string UserName { get; set; }
+ public (int, int) GetDeviceIdentifiers();
+ public void SetDeviceIdentifiers(int deviceMajor, int deviceMinor);
}API Usage
Instead of:
// Get
int major = entry.DeviceMajor;
int minor = entry.DeviceMinor;
// Set
entry.DeviceMajor = newMajor;
entry.DeviceMinor = newMinor;We would have:
// Get
(int major, int minor) = entry.GetDeviceIdentifiers();
// Set
entry.SetDeviceIdentifiers(newMajor, newMinor);Or with the alternative design:
// Get
entry.GetDeviceIdentifiers(out int major, out int minor);Alternative Designs
a) Instead of returning a tuple, get the values as out:
public abstract partial class PosixTarEntry : TarEntry
{
+ public void GetDeviceIdentifiers(out int deviceMajor, out int deviceMinor);
}b) Keep the APIs as they are, letting the user consume the major and minor separately, even if they are internally retrieved or set together.
Risks
Creating character or block devices is rare, and they are file types that are only available in some Unix filesystems. I am not aware of any particular use cases where the user would only need to retrieve the device major individually or the device minor individually. @tmds can you think of any?
These are all new APIs in .NET 7.0, so we have time to decide better designs where applicable.
@bartonjs @adamsitnik @jozkee @jeffhandley let me know what you think.