magic

package module
v0.4.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 15, 2026 License: MIT Imports: 7 Imported by: 0

README

magic

magic is a Go package that identifies the type of a file or a buffer with libmagic, the library of the file command.

The repository carries libmagic 5.48 as static archives, and the package embeds the magic database. You do not install libmagic, and the package does not read a magic file from your system. You need Go and a C compiler, because the package uses cgo.

magic is becoming a pure Go port of libmagic, which will need no C compiler. The port has not started, and docs/PLAN.md holds its plan. Until it is ready, the package works as this page describes.

Install

go get github.com/xo/magic

Use

m, err := magic.New(magic.MimeType)
if err != nil {
	return err
}
defer m.Close()

typ, err := m.File("photo.gif")
if err != nil {
	return err
}
fmt.Println(typ) // image/gif

Buffer identifies a byte slice in the same way. The flags are the MAGIC_* flags of libmagic: None gives a description, MimeType gives a MIME type and Extension gives the usual file extensions.

FileTypes and BufferTypes identify one input with several flags in one call. FileWith and BufferWith use other flags for one call and do not change the flags of the handle.

A handle is safe to share across goroutines. Each call holds a lock, so calls on one handle run one at a time. If you want calls to run in parallel, give each worker its own handle.

The package embeds the database compressed with zstd, about 0.3 MiB, and New expands it, which takes about 1.7 ms. MagicDB returns the plain database, for a program that needs the bytes of a magic.mgc file. Each call returns a new slice of about 10 MiB.

cmd/file is a small example program:

go run ./cmd/file -mime testdata/gif.gif

Platforms

The repository has archives for these targets:

GOOS GOARCH
linux amd64, arm64, arm (armv7)
darwin amd64, arm64
windows amd64, arm64
freebsd amd64

A build for any other target fails.

Each platform is a Go module of its own, such as github.com/xo/magic/libmagic/linux_amd64/v5. Go downloads the module of your platform and no other when it builds. go get and go mod tidy fetch every platform once, because they read the imports for all platforms.

The Linux archives link with glibc, which is what gcc uses on most Linux systems, and with musl. They carry their own regex engine, so the output is the same either way.

Releases up to v0.4.0 do not have that engine. Built with gcc on Linux, they give wrong descriptions for some files, and they can crash with a segmentation fault, as on a script that starts with #! /usr/bin/cmd1. Use v0.4.1 or later.

The archives for freebsd/amd64 link into a program, and nothing has run them yet, because GitHub has no hosted FreeBSD runner. The tests run in CI on windows/arm64, with clang from llvm-mingw as the C compiler.

Documents

Document What it holds
README.md this page, for a person who uses the package
CONTRIBUTING.md how to change the package, rebuild the archives and install the agent skills
AGENTS.md the rules for a coding agent. CLAUDE.md imports it
docs/PLAN.md the plan of the pure Go port, and the open questions
docs/API.md the design of the API of the port
docs/decisions/ every decision, one file each, with an index
docs/UPSTREAM.md the rules for following file, the upstream of the port
docs/BACKLOG.md the work that is known and not done, and the binary walker

License

The code is under the MIT license. See LICENSE. The archives hold libmagic, zlib, bzip2, xz and zstd, each under its own license. The Windows and Linux archives also hold libgnurx, which is under LGPL 2.1.

Documentation

Overview

Package magic is a wrapper around file's libmagic.

Index

Constants

View Source
const (
	None          = C.MAGIC_NONE
	Debug         = C.MAGIC_DEBUG
	Symlink       = C.MAGIC_SYMLINK
	Compress      = C.MAGIC_COMPRESS
	Devices       = C.MAGIC_DEVICES
	MimeType      = C.MAGIC_MIME_TYPE
	MimeEncoding  = C.MAGIC_MIME_ENCODING
	Mime          = C.MAGIC_MIME
	Continue      = C.MAGIC_CONTINUE
	Check         = C.MAGIC_CHECK
	PreserveATime = C.MAGIC_PRESERVE_ATIME
	Raw           = C.MAGIC_RAW
	Error         = C.MAGIC_ERROR
	Extension     = C.MAGIC_EXTENSION
)

Magic flags. Mirrors MAGIC_* constants in magic.h.

Variables

This section is empty.

Functions

func MagicDB

func MagicDB() ([]byte, error)

MagicDB returns the compiled magic database, as libmagic reads it from a magic.mgc file. The package embeds it compressed, so each call expands it into a new slice of about 10 MiB. A program that only identifies files does not need it, because New loads the database itself.

MagicDB was a []byte variable before v0.4.0. See D21.

func Version

func Version() string

Version returns the libmagic version as a dotted string, e.g. "5.48".

magic_version() encodes the minor part in the low two digits: 548 is 5.48, 504 is 5.04. The %02d matters -- without it 5.04 would render as "5.4".

func VersionInt

func VersionInt() int

VersionInt returns the libmagic version as an int.

Types

type Magic

type Magic struct {
	// contains filtered or unexported fields
}

Magic is an open libmagic handle with the embedded database loaded.

A magic_t cookie holds mutable per-lookup state and is not safe for concurrent use, so every method below serializes on mu. That makes a single Magic safe to share across goroutines, at the cost of serializing lookups: for parallel throughput, give each worker its own handle.

func New

func New(flags int) (*Magic, error)

New opens a handle and loads the embedded database.

func (*Magic) Buffer

func (m *Magic) Buffer(buf []byte) (string, error)

Buffer identifies the contents of buf using the handle's flags.

func (*Magic) BufferTypes

func (m *Magic) BufferTypes(buf []byte, flags ...int) ([]string, error)

BufferTypes identifies the contents of buf once per entry in flags, returning a result for each. Passing no flags uses the handle's own.

The whole sequence runs under a single lock, so the results describe the same buffer through the same handle with no other goroutine interleaving:

desc, err := m.BufferTypes(buf, magic.None, magic.MimeType, magic.Extension)

func (*Magic) BufferWith

func (m *Magic) BufferWith(flags int, buf []byte) (string, error)

BufferWith identifies the contents of buf using flags, leaving the handle's configured flags unchanged.

func (*Magic) Close

func (m *Magic) Close() error

Close releases the handle and the database copy. It is safe to call twice, and safe to race with other methods: they report a closed handle rather than touching a freed cookie.

func (*Magic) File

func (m *Magic) File(name string) (string, error)

File identifies the file at name using the handle's flags.

func (*Magic) FileTypes

func (m *Magic) FileTypes(name string, flags ...int) ([]string, error)

FileTypes identifies the file at name once per entry in flags, returning a result for each. Passing no flags uses the handle's own.

The whole sequence runs under a single lock, so the results describe the same file through the same handle with no other goroutine interleaving:

desc, err := m.FileTypes("x.png", magic.None, magic.MimeType, magic.Extension)

func (*Magic) FileWith

func (m *Magic) FileWith(flags int, name string) (string, error)

FileWith identifies the file at name using flags, leaving the handle's configured flags unchanged.

func (*Magic) Flags

func (m *Magic) Flags() int

Flags returns the handle's configured flags.

func (*Magic) SetFlags

func (m *Magic) SetFlags(flags int) error

SetFlags changes the flags on an open handle.

Directories

Path Synopsis
cmd
file command
compress
xz module
zstd module
libmagic
darwin_amd64 module
darwin_arm64 module
freebsd_amd64 module
linux_amd64 module
linux_arm module
linux_arm64 module
windows_amd64 module
windows_arm64 module

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL