[llvm] e2c8fa0 - [SystemZ][z/OS] Add z/OS archive writing support (#200087)
via llvm-commits
llvm-commits at lists.llvm.org
Mon Jul 13 19:41:29 PDT 2026
Author: Amy Kwan
Date: 2026-07-13T22:41:24-04:00
New Revision: e2c8fa09872cfacba7f73599dcf8557971ebe865
URL: https://github.com/llvm/llvm-project/commit/e2c8fa09872cfacba7f73599dcf8557971ebe865
DIFF: https://github.com/llvm/llvm-project/commit/e2c8fa09872cfacba7f73599dcf8557971ebe865.diff
LOG: [SystemZ][z/OS] Add z/OS archive writing support (#200087)
This patch implement z/OS archive writing in ArchiveWriter and adds the
option `llvm-ar --format=zos`.
Moreover, This patch teaches `llvm-ar` to emit z/OS-compatible archives
by:
- Detecting GOFF object files as z/OS members
- Writing z/OS member headers and archive magic
- Converting archive headers and symbol-name string tables to EBCDIC
- Emitting z/OS symbol table entries
- Using EBCDIC newline padding bytes
- Add a z/OS-specific workaround for empty symbol tables by emitting a
dummy blank symbol to satisfy binder requirements.
Added:
llvm/test/tools/llvm-ar/zos-write.test
Modified:
llvm/lib/Object/ArchiveWriter.cpp
llvm/tools/llvm-ar/llvm-ar.cpp
Removed:
################################################################################
diff --git a/llvm/lib/Object/ArchiveWriter.cpp b/llvm/lib/Object/ArchiveWriter.cpp
index 3b2d8c30bb301..9af8e0efe1872 100644
--- a/llvm/lib/Object/ArchiveWriter.cpp
+++ b/llvm/lib/Object/ArchiveWriter.cpp
@@ -20,6 +20,7 @@
#include "llvm/Object/COFF.h"
#include "llvm/Object/COFFImportFile.h"
#include "llvm/Object/Error.h"
+#include "llvm/Object/GOFFObjectFile.h"
#include "llvm/Object/IRObjectFile.h"
#include "llvm/Object/MachO.h"
#include "llvm/Object/ObjectFile.h"
@@ -70,6 +71,8 @@ object::Archive::Kind NewArchiveMember::detectKindFromObject() const {
if (isa<object::COFFObjectFile>(**OptionalObject) ||
isa<object::COFFImportFile>(**OptionalObject))
return object::Archive::K_COFF;
+ if (isa<object::GOFFObjectFile>(**OptionalObject))
+ return object::Archive::K_ZOS;
return object::Archive::K_GNU;
}
@@ -186,6 +189,10 @@ static bool isCOFFArchive(object::Archive::Kind Kind) {
return Kind == object::Archive::K_COFF;
}
+static bool isZOSArchive(object::Archive::Kind Kind) {
+ return Kind == object::Archive::K_ZOS;
+}
+
static bool isBSDLike(object::Archive::Kind Kind) {
switch (Kind) {
case object::Archive::K_GNU:
@@ -253,6 +260,31 @@ printBSDMemberHeader(raw_ostream &Out, uint64_t Pos, StringRef Name,
Out.write(uint8_t(0));
}
+static void
+printZOSMemberHeader(raw_ostream &Out, StringRef Name,
+ const sys::TimePoint<std::chrono::seconds> &ModTime,
+ unsigned UID, unsigned GID, unsigned Perms,
+ uint64_t Size) {
+ std::string AHeader;
+ raw_string_ostream AOut(AHeader);
+ if (Name.size() <= 16) {
+ printWithSpacePadding(AOut, Twine(Name), 16);
+ printRestOfMemberHeader(AOut, ModTime, UID, GID, Perms, Size);
+ } else {
+ // z/OS ar stores the exact name length inline with no extra alignment
+ // padding, unlike the BSD format which pads to an 8-byte boundary.
+ printWithSpacePadding(AOut, Twine("#1/") + Twine(Name.size()), 16);
+ printRestOfMemberHeader(AOut, ModTime, UID, GID, Perms, Name.size() + Size);
+ AOut << Name;
+ }
+ SmallString<256> EHeader;
+ if (std::error_code EC = ConverterEBCDIC::convertToEBCDIC(AHeader, EHeader))
+ report_fatal_error(
+ Twine("failed to convert z/OS member header to EBCDIC: ") +
+ EC.message());
+ Out << EHeader.str();
+}
+
static void
printBigArchiveMemberHeader(raw_ostream &Out, StringRef Name,
const sys::TimePoint<std::chrono::seconds> &ModTime,
@@ -306,6 +338,9 @@ printMemberHeader(raw_ostream &Out, uint64_t Pos, raw_ostream &StringTable,
if (isBSDLike(Kind))
return printBSDMemberHeader(Out, Pos, MemberName, ModTime, M.UID, M.GID,
M.Perms, Size);
+ if (isZOSArchive(Kind))
+ return printZOSMemberHeader(Out, MemberName, ModTime, M.UID, M.GID, M.Perms,
+ Size);
if (!useStringTable(Thin, MemberName))
return printGNUSmallMemberHeader(Out, MemberName, ModTime, M.UID, M.GID,
M.Perms, Size);
@@ -390,7 +425,10 @@ static uint64_t computeSymbolTableSize(object::Archive::Kind Kind,
uint32_t *Padding = nullptr) {
assert((OffsetSize == 4 || OffsetSize == 8) && "Unsupported OffsetSize");
uint64_t Size = OffsetSize; // Number of entries
- if (isBSDLike(Kind))
+ // Each symbol table entry consists of a member offset.
+ // For BSD, each entry also includes a string table offset.
+ // For z/OS, each entry instead also includes a flag field.
+ if (isBSDLike(Kind) || isZOSArchive(Kind))
Size += NumSyms * OffsetSize * 2; // Table
else
Size += NumSyms * OffsetSize; // Table
@@ -453,6 +491,9 @@ static void writeSymbolTableHeader(raw_ostream &Out, object::Archive::Kind Kind,
} else if (isAIXBigArchive(Kind)) {
printBigArchiveMemberHeader(Out, "", now(Deterministic), 0, 0, 0, Size,
PrevMemberOffset, NextMemberOffset);
+ } else if (isZOSArchive(Kind)) {
+ const char *Name = "__.SYMDEF";
+ printZOSMemberHeader(Out, Name, now(Deterministic), 0, 0, 0, Size);
} else {
const char *Name = is64BitKind(Kind) ? "/SYM64" : "";
printGNUSmallMemberHeader(Out, Name, now(Deterministic), 0, 0, 0, Size);
@@ -611,7 +652,14 @@ static void writeSymbolTable(raw_ostream &Out, object::Archive::Kind Kind,
uint32_t Pad;
uint64_t Size = computeSymbolTableSize(Kind, NumSyms, OffsetSize,
StringTable.size(), &Pad);
- writeSymbolTableHeader(Out, Kind, Deterministic, Size, PrevMemberOffset,
+
+ // Padding size is not included in the Size field of the z/OS symbol table
+ // header.
+ int64_t HeaderSize = Size;
+ if (isZOSArchive(Kind))
+ HeaderSize -= Pad;
+
+ writeSymbolTableHeader(Out, Kind, Deterministic, HeaderSize, PrevMemberOffset,
NextMemberOffset);
if (isBSDLike(Kind))
@@ -633,6 +681,9 @@ static void writeSymbolTable(raw_ostream &Out, object::Archive::Kind Kind,
if (isBSDLike(Kind))
printNBits(Out, Kind, StringOffset);
printNBits(Out, Kind, Pos); // member offset
+ // FIXME: Properly handle symbol attributes for z/OS archives.
+ if (isZOSArchive(Kind))
+ printNBits(Out, Kind, 0); // symbol flags
}
Pos += M.Header.size() + M.Data.size() + M.Padding.size();
}
@@ -640,7 +691,17 @@ static void writeSymbolTable(raw_ostream &Out, object::Archive::Kind Kind,
if (isBSDLike(Kind))
// byte count of the string table
printNBits(Out, Kind, StringTable.size());
- Out << StringTable;
+ if (isZOSArchive(Kind)) {
+ SmallString<256> EStringTable;
+ if (std::error_code EC =
+ ConverterEBCDIC::convertToEBCDIC(StringTable, EStringTable))
+ report_fatal_error(
+ Twine("failed to convert z/OS symbol table to EBCDIC: ") +
+ EC.message());
+ Out << EStringTable.str();
+ } else {
+ Out << StringTable;
+ }
while (Pad--)
Out.write(uint8_t(0));
@@ -785,6 +846,8 @@ computeMemberData(raw_ostream &StringTable, raw_ostream &SymNames,
LLVMContext &Context, ArrayRef<NewArchiveMember> NewMembers,
std::optional<bool> IsEC, function_ref<void(Error)> Warn) {
static char PaddingData[8] = {'\n', '\n', '\n', '\n', '\n', '\n', '\n', '\n'};
+ static char ZOSPaddingData[8] = {0x15, 0x15, 0x15, 0x15,
+ 0x15, 0x15, 0x15, 0x15}; // EBCDIC newlines.
uint64_t Pos =
isAIXBigArchive(Kind) ? sizeof(object::BigArchive::FixLenHdr) : 0;
@@ -846,6 +909,9 @@ computeMemberData(raw_ostream &StringTable, raw_ostream &SymNames,
Entry.second = Entry.second > 1 ? 1 : 0;
}
+ uint32_t LastZosObjIndex =
+ UINT_MAX; // Only set when writing symbol table in z/OS archive.
+
for (const NewArchiveMember &M : NewMembers) {
MemberData &D = Ret.emplace_back();
D.Data = M.Buf->getBuffer();
@@ -887,6 +953,9 @@ computeMemberData(raw_ostream &StringTable, raw_ostream &SymNames,
.str();
}
}
+
+ if (isZOSArchive(Kind) && D.SymFile.get())
+ LastZosObjIndex = Ret.size() - 1;
}
}
@@ -939,12 +1008,18 @@ computeMemberData(raw_ostream &StringTable, raw_ostream &SymNames,
// is happy with archives that we generate.
unsigned MemberPadding =
isDarwin(Kind) ? offsetToAlignment(D.Data.size(), Align(8)) : 0;
- unsigned TailPadding =
- offsetToAlignment(D.Data.size() + MemberPadding, Align(2));
- D.Padding = StringRef(PaddingData, MemberPadding + TailPadding);
StringRef MemberName = D.HybridName.size() ? D.HybridName : M->MemberName;
+ // z/OS stores long member names inline using their exact byte length.
+ // Include the inline name when computing alignment.
+ uint64_t PaddingBase = D.Data.size() + MemberPadding;
+ if (isZOSArchive(Kind) && MemberName.size() > 16)
+ PaddingBase += MemberName.size();
+ unsigned TailPadding = offsetToAlignment(PaddingBase, Align(2));
+ D.Padding = StringRef(isZOSArchive(Kind) ? ZOSPaddingData : PaddingData,
+ MemberPadding + TailPadding);
+
sys::TimePoint<std::chrono::seconds> ModTime;
if (UniqueTimestamps)
// Increment timestamp for each file of a given name.
@@ -1006,6 +1081,15 @@ computeMemberData(raw_ostream &StringTable, raw_ostream &SymNames,
if (D.SymFile)
HasObject = true;
}
+ // On z/OS, when there are no symbols, add a dummy blank symbol
+ // into the symbol table. This is done since the z/OS binder:
+ // - emits an error if there is no symbol table in the archive
+ // - emits an error if the symbol table has 0 symbols
+ // - should not find any references to a blank symbol
+ if ((LastZosObjIndex == Index) && (SymNames.tell() == 0)) {
+ D.Symbols.push_back(0);
+ SymNames << ' ' << '\0';
+ }
Pos += D.Header.size() + D.Data.size() + D.Padding.size();
}
@@ -1180,6 +1264,8 @@ Error writeArchiveToStream(raw_ostream &Out,
Out << "!<thin>\n";
else if (isAIXBigArchive(Kind))
Out << "<bigaf>\n";
+ else if (isZOSArchive(Kind))
+ Out << ZOSArchiveMagic;
else
Out << "!<arch>\n";
diff --git a/llvm/test/tools/llvm-ar/zos-write.test b/llvm/test/tools/llvm-ar/zos-write.test
new file mode 100644
index 0000000000000..0e390183f8d00
--- /dev/null
+++ b/llvm/test/tools/llvm-ar/zos-write.test
@@ -0,0 +1,72 @@
+## Test writing a z/OS archive.
+
+# RUN: rm -rf %t.dir %t.a %t.odd.a %t.long.a %t.sym.a %t.blank-sym.a && mkdir -p %t.dir
+# RUN: split-file %s %t.dir
+
+## Create a z/OS archive from a plain text file with symbol table writing disabled.
+# RUN: printf 'abcd' > %t.dir/test.txt
+# RUN: llvm-ar rcSD --format=zos %t.a %t.dir/test.txt
+
+## The archive should be written and read back successfully through llvm-ar.
+# RUN: llvm-ar t %t.a | FileCheck %s --check-prefix=LIST
+# RUN: llvm-ar p %t.a test.txt | FileCheck %s --check-prefix=CONTENT
+
+## Check raw bytes:
+## - The first 8 bytes are the z/OS archive magic in EBCDIC.
+## - Bytes 66..67 are the first member header terminator (`\n in EBCDIC => 79 15).
+# RUN: %python -c "d=open(r'%t.a','rb').read(); print(d[:8].hex()); print(d[66:68].hex())" | FileCheck %s --check-prefix=BYTES
+
+# LIST: test.txt
+# CONTENT: abcd
+# BYTES: 5a4c819983886e15
+# BYTES-NEXT: 7915
+
+## Odd-sized members should be padded with EBCDIC newline (0x15).
+# RUN: printf 'abc' > %t.dir/odd.txt
+# RUN: llvm-ar rcSD --format=zos %t.odd.a %t.dir/odd.txt
+# RUN: %python -c "d=open(r'%t.odd.a','rb').read(); print(f'{d[-1]:02x}')" | FileCheck %s --check-prefix=PAD
+
+# PAD: 15
+
+## Long member names should use their exact byte length and be read back
+## correctly. The 25-byte name plus the 3-byte contents is already even-sized,
+## so the archive should not contain a trailing padding byte.
+# RUN: printf 'xyz' > %t.dir/very_long_member_name.txt
+# RUN: llvm-ar rcSD --format=zos %t.long.a %t.dir/very_long_member_name.txt
+# RUN: llvm-ar t %t.long.a | FileCheck %s --check-prefix=LONG-LIST
+# RUN: llvm-ar p %t.long.a very_long_member_name.txt | FileCheck %s --check-prefix=LONG-CONTENT
+# RUN: %python -c "d=open(r'%t.long.a','rb').read(); print(d[8:24].decode('cp037').strip()); print(len(d))" | FileCheck %s --check-prefix=LONG-BYTES
+
+# LONG-LIST: very_long_member_name.txt
+# LONG-CONTENT: xyz
+# LONG-BYTES: #1/25
+# LONG-BYTES-NEXT: 96
+
+## Use LLVM bitcode here so the test remains target-independent. The archive
+## writer only needs a symbolic input in order to emit the archive symbol table.
+## A z/OS archive with real symbols should write a readable symbol table.
+# RUN: llvm-as %t.dir/mytest.ll -o %t.dir/mytest.bc
+# RUN: llvm-ar rcD --format=zos %t.sym.a %t.dir/mytest.bc
+# RUN: llvm-nm --print-armap %t.sym.a | FileCheck %s --check-prefix=SYMTAB
+
+# SYMTAB: Archive map
+# SYMTAB-NEXT: mytest in mytest.bc
+# SYMTAB-NOT: in mytest.bc
+
+## A z/OS archive with no real symbols should still write the dummy blank symbol.
+# RUN: llvm-as %t.dir/blank.ll -o %t.dir/blank.bc
+# RUN: llvm-ar rcD --format=zos %t.blank-sym.a %t.dir/blank.bc
+# RUN: llvm-nm --print-armap %t.blank-sym.a | FileCheck %s --check-prefix=EMPTY-SYMTAB
+
+# EMPTY-SYMTAB: Archive map
+# EMPTY-SYMTAB-NEXT: in blank.bc
+# EMPTY-SYMTAB-NOT: in blank.bc
+
+#--- mytest.ll
+define i32 @mytest() {
+entry:
+ ret i32 87
+}
+
+#--- blank.ll
+source_filename = "blank.ll"
diff --git a/llvm/tools/llvm-ar/llvm-ar.cpp b/llvm/tools/llvm-ar/llvm-ar.cpp
index bac99c548a178..38f929f63b39f 100644
--- a/llvm/tools/llvm-ar/llvm-ar.cpp
+++ b/llvm/tools/llvm-ar/llvm-ar.cpp
@@ -83,6 +83,7 @@ static void printArHelp(StringRef ToolName) {
=darwin - darwin
=bsd - bsd
=bigarchive - big archive (AIX OS)
+ =zos - zos archive (z/OS OS)
=coff - coff
--plugin=<string> - ignored for compatibility
-h --help - display this help and exit
@@ -195,7 +196,16 @@ static SmallVector<const char *, 256> PositionalArgs;
static bool MRI;
namespace {
-enum Format { Default, GNU, COFF, BSD, DARWIN, BIGARCHIVE, Unknown };
+enum Format {
+ Default,
+ GNU,
+ COFF,
+ BSD,
+ DARWIN,
+ BIGARCHIVE,
+ ZOSARCHIVE,
+ Unknown
+};
}
static Format FormatType = Default;
@@ -1079,6 +1089,11 @@ static void performWriteOperation(ArchiveOperation Operation,
fail("only the gnu format has a thin mode");
Kind = object::Archive::K_AIXBIG;
break;
+ case ZOSARCHIVE:
+ if (Thin)
+ fail("only the gnu format has a thin mode");
+ Kind = object::Archive::K_ZOS;
+ break;
case Unknown:
llvm_unreachable("");
}
@@ -1397,6 +1412,7 @@ static int ar_main(int argc, char **argv) {
.Case("bsd", BSD)
.Case("bigarchive", BIGARCHIVE)
.Case("coff", COFF)
+ .Case("zos", ZOSARCHIVE)
.Default(Unknown);
if (FormatType == Unknown)
fail(std::string("Invalid format ") + Match);
More information about the llvm-commits
mailing list