magic

package module
v0.3.0 Latest Latest
Warning

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

Go to latest
Published: Oct 13, 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.

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.

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. The Linux archives are built for musl and are static, so a program links them under glibc and under musl.

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, every decision and the open questions
docs/BACKLOG.md the work that is known and not done

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 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

View Source
var MagicDB []byte

MagicDB is the compiled magic database. It is byte-identical for every target -- the format is endian-independent and libmagic byte-swaps on load -- so one embedded copy serves all platforms.

Functions

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