NAME¶

r_magic — File type detection library using magic numbers

SYNOPSIS¶

#include <r_magic.h>

DESCRIPTION¶

The r_magic library provides file type detection using magic number patterns. It can identify file types by examining the content of files or buffers, similar to the Unix file(1) command.

The library uses a database of magic patterns that describe how to recognize different file formats based on their binary signatures, text patterns, and structural characteristics.

INITIALIZATION¶

A magic context holds the parsed magic database and runtime state; allocate one before attempting to probe files or buffers and free it when finished.

/* allocate and free a magic context */
RMagic *r_magic_new(int flags);
void r_magic_free(RMagic *ms);

/* example */
RMagic *magic = r_magic_new(R_MAGIC_NONE);
if (!magic) { /* handle allocation error */ }

After creating the instance you must load a magic database (or a buffer containing a magic database) before asking it to identify content.

/* load default database */
bool r_magic_load(RMagic *ms, const char *magicfile);
bool r_magic_load_buffer(RMagic *ms, const ut8 *buf, size_t len);

FILE TYPE DETECTION¶

Once a magic instance is loaded it can inspect files, file descriptors or in-memory buffers. The functions return a pointer to an internal, NUL-terminated string describing the matching type (do not free it). If no match is found they return NULL and you may call r_magic_error() to obtain diagnostics.

/* signatures */
const char *r_magic_file(RMagic *ms, const char *path);
const char *r_magic_descriptor(RMagic *ms, int fd);
const char *r_magic_buffer(RMagic *ms, const void *buf, size_t nb);

Use the buffer API when the data is already in memory (for example a block read from a file or a memory map). `libr/core` uses this approach when detecting the type of the current block being inspected (see `libr/core/cmd_magic.inc.c`), then combines the returned description with further actions (flags, printing or nested probes using offsets).

/* example: probe a memory buffer */
const char *type = r_magic_buffer(magic, data, data_len);
if (type) {
    printf("Buffer type: %s0, type);
} else {
    const char *err = r_magic_error(magic);
    fprintf(stderr, "magic failed: %s0, err ? err : "unknown");
}

CONFIGURATION FLAGS¶

Flags control how the magic engine behaves (what it searches for and the format of the output). Set flags when creating the instance or at runtime with r_magic_setflags():

void r_magic_setflags(RMagic *ms, int flags);

Common flags include MIME-only output or enabling debug diagnostics; many others tune which checks are performed (compressed files, ELF details, etc.).

R_MAGIC_NONE

No special flags

R_MAGIC_DEBUG

Enable debugging output

R_MAGIC_MIME_TYPE

Return only MIME type

R_MAGIC_MIME_ENCODING

Return only MIME encoding

R_MAGIC_CONTINUE

Return all matches, not just first

R_MAGIC_RAW

Do not translate unprintable characters

ERROR HANDLING¶

The magic API reports human-readable error messages and an errno-like value when operations fail (for example, inability to open the magic file or parse its contents). Query these functions after an operation returns NULL/false.

const char *r_magic_error(RMagic *ms);
int r_magic_errno(RMagic *ms);

Callers should always check the return value of load/probe functions and then inspect `r_magic_error` for diagnostics. In long-running programs keep the magic instance around and reload only when the database changes (this is the pattern used in `libr/core`).

DATABASE MANAGEMENT¶

The magic database can be loaded from the system default path, from a specific file, or from a buffer in memory. Helper functions also allow compiling and syntax-checking magic files.

/* signatures */
bool r_magic_load(RMagic *ms, const char *magicfile);
bool r_magic_load_buffer(RMagic *ms, const ut8 *buf, size_t len);
bool r_magic_compile(RMagic *ms, const char *magicfile);
bool r_magic_check(RMagic *ms, const char *magicfile);

In practice `libr/core` will call `r_magic_load` once (using the `dir.magic` configuration key) and reuse the returned context for multiple buffer probes. If you wish to supply a custom database at runtime use `r_magic_load_buffer` or `r_magic_compile` to validate a file first.

/* example: load custom magic then probe a buffer */
if (!r_magic_load(magic, "/usr/share/magic/magic.mgc")) {
    fprintf(stderr, "failed to load magic: %s0, r_magic_error(magic));
}
const char *t = r_magic_buffer(magic, data, data_len);

SUPPORTED FORMATS¶

The library can detect hundreds of file formats including:

• Executable formats (ELF, PE, Mach-O)
• Archives (ZIP, TAR, RAR)
• Images (JPEG, PNG, GIF, BMP)
• Documents (PDF, DOC, XLS)
• Audio/Video (MP3, MP4, AVI)
• Compressed files (GZ, BZ2, XZ)
• And many others

1) Simple command-line file probe — same pattern used by `rabin2` and the
`cmd.magic` implementation in `libr/core`.

#include <r_magic.h>
#include <stdio.h>

int main(int argc, char **argv) {
    if (argc < 2) { return 1; }
    RMagic *m = r_magic_new(R_MAGIC_NONE);
    if (!m) { perror("r_magic_new"); return 1; }
    if (!r_magic_load(m, NULL)) {
        fprintf(stderr, "load failed: %s0, r_magic_error(m));
        r_magic_free(m);
        return 1;
    }
    const char *t = r_magic_file(m, argv[1]);
    if (t) printf("%s: %s0, argv[1], t);
    r_magic_free(m);
    return 0;
}

2) Inspecting an in-memory block and reacting to generic "data" results.
`libr/core` probes the current block and, when the result is generic
(for example "data"), it may choose to continue searching at a different
alignment or attempt more specific heuristics.

RMagic *m = r_magic_new(0);
r_magic_load(m, NULL);
const char *info = r_magic_buffer(m, block, block_len);
if (info) {
    if (!strcmp(info, "data")) {
        /* fallback: try different alignments or other detectors */
    } else {
        printf("info: %s0, info);
    }
}
r_magic_free(m);

3) Request MIME-only output — useful when integrating magic into
automated pipelines.

r_magic_setflags(m, R_MAGIC_MIME_TYPE);
const char *mime = r_magic_buffer(m, data, size);
printf("MIME: %s0, mime ? mime : "unknown");

SEE ALSO¶

r_bin(3), r_util(3)