net: document @-prefix support for Unix socket addresses

[nussjustin]

Go version

go version go1.26.0 linux/amd64

Output of go env in your module/workspace:

AR='ar'
CC='gcc'
CGO_CFLAGS='-O2 -g'
CGO_CPPFLAGS=''
CGO_CXXFLAGS='-O2 -g'
CGO_ENABLED='1'
CGO_FFLAGS='-O2 -g'
CGO_LDFLAGS='-O2 -g'
CXX='g++'
GCCGO='gccgo'
GO111MODULE=''
GOAMD64='v1'
GOARCH='amd64'
GOAUTH='netrc'
GOBIN=''
GOCACHE='/home/justinn/.cache/go-build'
GOCACHEPROG=''
GODEBUG=''
GOENV='/home/justinn/.config/go/env'
GOEXE=''
GOEXPERIMENT=''
GOFIPS140='off'
GOFLAGS=''
GOGCCFLAGS='-fPIC -m64 -pthread -Wl,--no-gc-sections -fmessage-length=0 -ffile-prefix-map=/tmp/go-build2382649238=/tmp/go-build -gno-record-gcc-switches'
GOHOSTARCH='amd64'
GOHOSTOS='linux'
GOINSECURE=''
GOMOD='/home/justinn/Workspace/go-playground/unixsockettest/go.mod'
GOMODCACHE='/home/justinn/.gopath/pkg/mod'
GONOPROXY=''
GONOSUMDB=''
GOOS='linux'
GOPATH='/home/justinn/.gopath'
GOPRIVATE=''
GOPROXY='https://proxy.golang.org,direct'
GOROOT='/home/justinn/.gopath/pkg/mod/golang.org/toolchain@v0.0.1-go1.26.0.linux-amd64'
GOSUMDB='sum.golang.org'
GOTELEMETRY='on'
GOTELEMETRYDIR='/home/justinn/.config/go/telemetry'
GOTMPDIR=''
GOTOOLCHAIN='go1.25.0+auto'
GOTOOLDIR='/home/justinn/.gopath/pkg/mod/golang.org/toolchain@v0.0.1-go1.26.0.linux-amd64/pkg/tool/linux_amd64'
GOVCS=''
GOVERSION='go1.26.0'
GOWORK=''
PKG_CONFIG='pkg-config'

What did you do?

Wrote a program that listens on a Unix socket in the abstract socket namespace using the @<name> address syntax.

Example:

conn, err := net.ListenUnixgram("unixgram", &net.UnixAddr{Name: "@test"})

What did you see happen?

No documentation on Go supporting the non-standard @<name> syntax for connecting to and listening on an abstract socket address.

An Unix socket address starting with a null-byte ('\0') is interpreted as an abstract socket address, but Go also supports using an at-symbol ('@') instead.

While it can be assumed that Go supports using the standard format using a null-byte (as that is handled by the OS itself, at least under Linux) it is not obvious that the at-symbol can be used instead.

I found some information on the web about Go supporting this and also remembered it faintly from past experiences using the @<name> syntax, but there seems to be no official documentation.

What did you expect to see?

Documentation on the supported syntax.

The handling of the at-symbol is implemented in the syscall package, but given that users generally use high-level functions and methods in the net package and not the low-level functions in the syscall package it probably makes more sense to document it in the net package.

It may also make sense to document that the null-byte variant also works.

[gabyhelp]

Related Issues

• syscall: unable to use the full length for abstract socket starting with null #70893 (closed)
• syscall: unnamed unix sockets on Linux report Name "@" in their address #7354 (closed)
• x/crypto: TestDialUnix and unnamed socket name in Go #31413 (closed)
• syscall: support for abstract unix domain socket with len(name) == len(sa.raw.Path) #21965 (closed)

_{(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)}

[spqr79]

The conversion lives in syscall/syscall_linux.go (unixSocketPath/unixPathToAddr) and is already tested in syscall/syscall_unix_test.go, but nothing surfaces it at the net package level where users actually land.

The two places worth touching:

src/net/unixsock.go — add to the UnixAddr doc:

// UnixAddr represents the address of a Unix domain socket endpoint.
//
// On Linux, abstract socket addresses are supported via two equivalent notations
// in the Name field:
//
//   - "\x00name" — leading null byte (POSIX/kernel convention)
//   - "@name"    — Go-specific shorthand; converted to \x00name internally
//
// Abstract sockets are Linux-only. On other platforms a Name starting with "@"
// is treated as a literal filesystem path with no error.

src/net/net.go — one short paragraph in the package doc mentioning abstract Unix sockets and pointing at UnixAddr.

The roundtrip direction (LocalAddr() returning @ vs \x00) should also be pinned by a test — the current syscall-level test doesn't cover net.(*UnixConn).LocalAddr(). A test along these lines belongs in src/net/unixsock_linux_test.go:

func TestAbstractUnixAddrRoundtrip(t *testing.T) {
    name := "@abstract-roundtrip-" + strconv.Itoa(os.Getpid())
    conn, err := net.ListenUnixgram("unixgram", &net.UnixAddr{Name: name, Net: "unixgram"})
    if err != nil {
        t.Fatal(err)
    }
    defer conn.Close()
    got := conn.LocalAddr().(*net.UnixAddr).Name
    if got != name {
        t.Errorf("LocalAddr().Name = %q, want %q", got, name)
    }
}

That test will fail if the kernel-level \x00 leaks back through LocalAddr() instead of being re-encoded as @, making the contract explicit and regression-proof.

Worth noting separately: &net.UnixAddr{Name: "@foo"} and &net.UnixAddr{Name: "\x00foo"} compare unequal despite being semantically identical — that's a real footgun but it's an API change, so it probably deserves its own issue rather than being bundled here.

[nussjustin]

@spqr79

// Abstract sockets are Linux-only. On other platforms a Name starting with "@"
// is treated as a literal filesystem path with no error.

Not sure if this is actually correct.

I saw some code handling "@" for Windows and Solaris while checking the syscall package, though I haven't had the opportunity to check more deeply yet.

• "@name" — Go-specific shorthand; converted to \x00name internally

Maybe also worth to note that the "@name" format is used by some tools like ss or netstat when displaying abstract socket addresses.

[spqr79]

Good catch on the Windows/Solaris point — worth verifying before the doc lands. The @→\x00 conversion in syscall_linux.go is Linux-specific, but if there's parallel handling in syscall_windows.go or a Solaris equivalent, the "Linux-only" note in the doc would need to be scoped more carefully, or replaced with an explicit per-platform table.

If you have a chance to check the syscall package: the relevant functions are unixSocketPath and unixPathToAddr — if those (or equivalents) exist on other platforms with the same @ semantics, the doc should reflect that.
The ss/netstat point is worth adding to the Godoc — it helps users recognize the format when they see it in system tools, not just when writing Go code. Something like:

// The "@name" format is also used by tools such as ss(8) and netstat(8)
// when displaying abstract socket addresses.

[dr2chase]

@neild @ianlancetaylor

[ianlancetaylor]

Abstract sockets are Linux-specific. The code handling @ in syscall_solaris.go and syscall_windows.go is almost certainly useless, as the resulting socket paths won't work.