Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

cmd/link,runtime: fix c-shared dlopen on non-glibc systems (#13492) #75048

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jgowdy wants to merge 4 commits into golang:master
base: master
Choose a base branch
Loading
from jgowdy:non-glibc
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
88 changes: 88 additions & 0 deletions doc/standards/README.txt
View file Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,88 @@
Go non-glibc Compatibility Fixes

This directory contains documentation for fixes that enable Go shared
libraries to work correctly on non-glibc Unix systems, particularly for
shared library builds (-buildmode=c-shared and -buildmode=c-archive).

TLS General Dynamic Model (see tls-general-dynamic.txt)
Issue: Go shared libraries fail to load via dlopen() on non-glibc systems
Solution: Comprehensive TLS General Dynamic model implementation across all architectures
Impact: Enables Go shared libraries to work with non-glibc dynamic loaders and libc implementations

argc/argv SIGSEGV Fix (see argc-argv-fix.txt)
Issue: Go shared libraries crash on systems that follow ELF specification strictly
Solution: Added null-safety checks for argc/argv across all Unix platforms
Impact: Prevents SIGSEGV crashes when DT_INIT_ARRAY functions don't receive arguments

Acknowledgments

This work was inspired by and builds upon prior efforts by the Go community:

- Issue #71953: Proposal: runtime: support general dynamic thread local storage model
(https://github.com/golang/go/issues/71953) - The foundational proposal for TLS General Dynamic support
- Alexander Musman (alexander.musman@gmail.com): ARM64 TLS General Dynamic prototype implementation in
review 644975 (https://go-review.googlesource.com/c/go/+/644975) that provided the technical foundation
for this comprehensive multi-architecture implementation
- Issue #73667: Related work that helped identify the scope and approach for comprehensive TLS General Dynamic implementation

Special thanks to the contributors who identified these critical compatibility issues and proposed
solutions that enable Go shared libraries to work correctly across all Unix systems, and to Rich Felker,
author of musl libc, for technical knowledge and documentation on thread local storage models that
informed the TLS General Dynamic implementation approach.

Standards References

ELF Generic Application Binary Interface (gABI)

Link: ELF gABI v4.1 (https://www.sco.com/developers/gabi/latest/contents.html)

Relevant Section 5.2.3 - DT_INIT_ARRAY:
"This element holds the address of an array of pointers to initialization functions..."

Note: The specification does NOT require these functions to receive argc, argv, envp arguments.
Only glibc provides this non-standard extension.

Section 5.1.2 - Dynamic Section:
"The dynamic array tags define the interpretation of the dynamic array entries. The dynamic linker
uses these entries to initialize the process image."

ELF Thread-Local Storage Specification

Link: ELF Handling For Thread-Local Storage (https://www.akkadia.org/drepper/tls.pdf) (Ulrich Drepper)

Section 2.2 - TLS Models:
"General Dynamic: This is the most flexible model. It can be used in all situations, including
shared libraries that are loaded dynamically."

"Initial Exec: This model can be used in shared libraries which are loaded as part of the startup
process of the application."

Section 3.4.1 - x86-64 General Dynamic:
"The general dynamic model is the most general model. It allows accessing thread-local variables
from shared libraries that might be loaded dynamically."

System V Application Binary Interface

x86-64 ABI: System V ABI AMD64 (https://gitlab.com/x86-psABIs/x86-64-ABI)
ARM64 ABI: ARM AAPCS64 (https://github.com/ARM-software/abi-aa/blob/main/aapcs64/aapcs64.rst)
RISC-V ABI: RISC-V ELF psABI (https://github.com/riscv-non-isa/riscv-elf-psabi-doc)

Relevance: These specifications define TLS relocations and calling conventions that our TLS General
Dynamic implementation follows.

Additional References

Standards-Compliant libc Implementations:
Most Unix systems use libc implementations that strictly follow specifications rather than providing
glibc-specific extensions. This includes BSD systems, embedded systems, and many containerized environments.

Impact

These fixes enable Go shared libraries to work correctly on:
- Alpine Linux and other lightweight distributions
- FreeBSD, NetBSD, OpenBSD and other BSD variants
- Embedded systems with minimal libc implementations
- Any non-glibc Unix system

The changes maintain full backward compatibility with glibc-based systems while extending support
to non-glibc implementations.
129 changes: 129 additions & 0 deletions doc/standards/argc-argv-fix.txt
View file Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,129 @@
argc/argv SIGSEGV Fix for Shared Libraries

Problem Statement

Go programs built with -buildmode=c-shared or -buildmode=c-archive crash
with SIGSEGV when loaded on standards-compliant systems:

runtime.sysargs: segmentation fault at address 0x0

This affects any system where the libc implementation follows the ELF
specification strictly, including lightweight distributions (Alpine Linux),
BSD systems (FreeBSD, NetBSD, OpenBSD, DragonFly BSD), Solaris, and
embedded systems (uClibc, dietlibc).

Root Cause

The Go runtime assumes that DT_INIT_ARRAY functions receive (argc, argv,
envp) arguments, following glibc's non-standard behavior. However:

1. ELF Specification: The ELF specification does NOT require passing
arguments to DT_INIT_ARRAY functions
2. glibc Extension: Only glibc passes these arguments as a non-standard
extension
3. Standards Compliance: BSD libcs and other standards-compliant
implementations don't pass arguments
4. Runtime Crash: Go's runtime initialization code dereferences argv
without checking validity

Standards Compliance

- ELF gABI Specification: DT_INIT_ARRAY functions are not required to
receive arguments
- Standards-Compliant Behavior: Most non-glibc implementations correctly
follow the ELF specification

Implementation

Added null-safety checks in the sysargs() function across all Unix
platforms to handle cases where argc/argv are not passed according to
the ELF specification.

Universal Check Logic

// Check for nil argv to handle c-shared/c-archive libraries
// where DT_INIT_ARRAY doesn't pass arguments according to ELF specification
if argv == nil || argc < 0 || (islibrary || isarchive) {
// Skip argv processing for shared libraries
return
}

Platform Coverage

Linux (runtime/os_linux.go):
- Handles standards-compliant libc implementations
- Handles null argv before auxiliary vector parsing

Darwin/macOS (runtime/os_darwin.go):
- Prevents crashes on macOS when using c-shared builds
- Handles executable path extraction safely

FreeBSD (runtime/os_freebsd.go):
- BSD libc doesn't pass argc/argv to DT_INIT_ARRAY functions
- Handles auxiliary vector parsing safely

NetBSD (runtime/os_netbsd.go):
- NetBSD libc follows ELF specification strictly
- Prevents SIGSEGV in shared library initialization

OpenBSD (runtime/os_openbsd.go):
- OpenBSD libc is standards-compliant
- Safe handling of missing argc/argv arguments

DragonFly BSD (runtime/os_dragonfly.go):
- DragonFly BSD follows BSD conventions
- Prevents crashes in c-shared/c-archive builds

Solaris (runtime/os3_solaris.go):
- Solaris libc is standards-compliant
- Handles missing arguments gracefully

Behavior Changes

Before Fix
- glibc systems: Worked (argc/argv passed)
- Standards-compliant systems: SIGSEGV crash (argc/argv not passed)

After Fix
- glibc systems: No change (argc/argv still processed when available)
- Standards-compliant systems: Safe operation (argc/argv absence handled
gracefully)
- All systems: Shared libraries initialize without crashes

Library Mode Handling

When islibrary or isarchive is true:
- Skip argument processing entirely (arguments don't exist in shared
library context)
- Initialize with safe defaults
- Avoid dereferencing potentially null pointers

Backward Compatibility

- No breaking changes: Existing behavior preserved on glibc systems
- Enhanced compatibility: New support for standards-compliant systems
- Library behavior: Shared libraries now work correctly on all Unix
variants
- Performance: No performance impact (early return when argc/argv
unavailable)

Testing

Verified on:
- Alpine Linux: Standards-compliant libc testing
- FreeBSD: BSD libc verification
- macOS: Darwin compatibility testing
- Ubuntu/Debian: glibc regression testing

Standards References

- ELF gABI: Generic Application Binary Interface specification
- System V ABI: Unix System V Application Binary Interface

Related Issues

- Resolves crashes when loading Go shared libraries via dlopen() on
Alpine Linux
- Fixes compatibility with embedded systems using uClibc or dietlibc
- Enables Go shared libraries to work on all BSD variants
- Provides foundation for broader Go adoption in containerized environments
Loading

AltStyle によって変換されたページ (->オリジナル) /