1.\" $NetBSD: libmagic.3,v 1.20 2022/09/24 20:21:45 christos Exp $ 2.\" 3.\" $File: libmagic.man,v 1.46 2022/09/15 16:54:14 christos Exp $ 4.\" 5.\" Copyright (c) Christos Zoulas 2003, 2018, 2022 6.\" All Rights Reserved. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice immediately at the beginning of the file, without modification, 13.\" this list of conditions, and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR 22.\" ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.Dd September 15, 2022 31.Dt LIBMAGIC 3 32.Os 33.Sh NAME 34.Nm magic_open , 35.Nm magic_close , 36.Nm magic_error , 37.Nm magic_errno , 38.Nm magic_descriptor , 39.Nm magic_file , 40.Nm magic_buffer , 41.Nm magic_getflags , 42.Nm magic_setflags , 43.Nm magic_check , 44.Nm magic_compile , 45.Nm magic_list , 46.Nm magic_load , 47.Nm magic_load_buffers , 48.Nm magic_setparam , 49.Nm magic_getparam , 50.Nm magic_version 51.Nd Magic number recognition library 52.Sh LIBRARY 53.Lb libmagic 54.Sh SYNOPSIS 55.In magic.h 56.Ft magic_t 57.Fn magic_open "int flags" 58.Ft void 59.Fn magic_close "magic_t cookie" 60.Ft const char * 61.Fn magic_error "magic_t cookie" 62.Ft int 63.Fn magic_errno "magic_t cookie" 64.Ft const char * 65.Fn magic_descriptor "magic_t cookie" "int fd" 66.Ft const char * 67.Fn magic_file "magic_t cookie" "const char *filename" 68.Ft const char * 69.Fn magic_buffer "magic_t cookie" "const void *buffer" "size_t length" 70.Ft int 71.Fn magic_getflags "magic_t cookie" 72.Ft int 73.Fn magic_setflags "magic_t cookie" "int flags" 74.Ft int 75.Fn magic_check "magic_t cookie" "const char *filename" 76.Ft int 77.Fn magic_compile "magic_t cookie" "const char *filename" 78.Ft int 79.Fn magic_list "magic_t cookie" "const char *filename" 80.Ft int 81.Fn magic_load "magic_t cookie" "const char *filename" 82.Ft int 83.Fn magic_load_buffers "magic_t cookie" "void **buffers" "size_t *sizes" "size_t nbuffers" 84.Ft int 85.Fn magic_getparam "magic_t cookie" "int param" "void *value" 86.Ft int 87.Fn magic_setparam "magic_t cookie" "int param" "const void *value" 88.Ft int 89.Fn magic_version "void" 90.Sh DESCRIPTION 91These functions 92operate on the magic database file 93which is described 94in 95.Xr magic 5 . 96.Pp 97The function 98.Fn magic_open 99creates a magic cookie pointer and returns it. 100It returns 101.Dv NULL 102if there was an error allocating the magic cookie. 103The 104.Ar flags 105argument specifies how the other magic functions should behave: 106.Bl -tag -width MAGIC_COMPRESS 107.It Dv MAGIC_NONE 108No special handling. 109.It Dv MAGIC_DEBUG 110Print debugging messages to stderr. 111.It Dv MAGIC_SYMLINK 112If the file queried is a symlink, follow it. 113.It Dv MAGIC_COMPRESS 114If the file is compressed, unpack it and look at the contents. 115.It Dv MAGIC_DEVICES 116If the file is a block or character special device, then open the device 117and try to look in its contents. 118.It Dv MAGIC_MIME_TYPE 119Return a MIME type string, instead of a textual description. 120.It Dv MAGIC_MIME_ENCODING 121Return a MIME encoding, instead of a textual description. 122.It Dv MAGIC_MIME 123A shorthand for MAGIC_MIME_TYPE | MAGIC_MIME_ENCODING. 124.It Dv MAGIC_CONTINUE 125Return all matches, not just the first. 126.It Dv MAGIC_CHECK 127Check the magic database for consistency and print warnings to stderr. 128.It Dv MAGIC_PRESERVE_ATIME 129On systems that support 130.Xr utime 3 131or 132.Xr utimes 2 , 133attempt to preserve the access time of files analysed. 134.It Dv MAGIC_RAW 135Don't translate unprintable characters to a \eooo octal representation. 136.It Dv MAGIC_ERROR 137Treat operating system errors while trying to open files and follow symlinks 138as real errors, instead of printing them in the magic buffer. 139.It Dv MAGIC_APPLE 140Return the Apple creator and type. 141.It Dv MAGIC_EXTENSION 142Return a slash-separated list of extensions for this file type. 143.It Dv MAGIC_COMPRESS_TRANSP 144Don't report on compression, only report about the uncompressed data. 145.It Dv MAGIC_NO_CHECK_APPTYPE 146Don't check for 147.Dv EMX 148application type (only on EMX). 149.It Dv MAGIC_NO_COMPRESS_FORK 150Don't allow decompressors that use fork. 151.It Dv MAGIC_NO_CHECK_CDF 152Don't get extra information on MS Composite Document Files. 153.It Dv MAGIC_NO_CHECK_COMPRESS 154Don't look inside compressed files. 155.It Dv MAGIC_NO_CHECK_ELF 156Don't print ELF details. 157.It Dv MAGIC_NO_CHECK_ENCODING 158Don't check text encodings. 159.It Dv MAGIC_NO_CHECK_SOFT 160Don't consult magic files. 161.It Dv MAGIC_NO_CHECK_TAR 162Don't examine tar files. 163.It Dv MAGIC_NO_CHECK_TEXT 164Don't check for various types of text files. 165.It Dv MAGIC_NO_CHECK_TOKENS 166Don't look for known tokens inside ascii files. 167.It Dv MAGIC_NO_CHECK_JSON 168Don't examine JSON files. 169.It Dv MAGIC_NO_CHECK_CSV 170Don't examine CSV files. 171.El 172.Pp 173The 174.Fn magic_close 175function closes the 176.Xr magic 5 177database and deallocates any resources used. 178.Pp 179The 180.Fn magic_error 181function returns a textual explanation of the last error, or 182.Dv NULL 183if there was no error. 184.Pp 185The 186.Fn magic_errno 187function returns the last operating system error number 188.Pq Xr errno 2 189that was encountered by a system call. 190.Pp 191The 192.Fn magic_file 193function returns a textual description of the contents of the 194.Ar filename 195argument, or 196.Dv NULL 197if an error occurred. 198If the 199.Ar filename 200is 201.Dv NULL , 202then stdin is used. 203.Pp 204The 205.Fn magic_descriptor 206function returns a textual description of the contents of the 207.Ar fd 208argument, or 209.Dv NULL 210if an error occurred. 211.Pp 212The 213.Fn magic_buffer 214function returns a textual description of the contents of the 215.Ar buffer 216argument with 217.Ar length 218bytes size. 219.Pp 220The 221.Fn magic_getflags 222functions returns a value representing current 223.Ar flags 224set. 225.Pp 226The 227.Fn magic_setflags 228function sets the 229.Ar flags 230described above. 231Note that using both MIME flags together can also 232return extra information on the charset. 233.Pp 234The 235.Fn magic_check 236function can be used to check the validity of entries in the colon 237separated database files passed in as 238.Ar filename , 239or 240.Dv NULL 241for the default database. 242It returns 0 on success and \-1 on failure. 243.Pp 244The 245.Fn magic_compile 246function can be used to compile the colon 247separated list of database files passed in as 248.Ar filename , 249or 250.Dv NULL 251for the default database. 252It returns 0 on success and \-1 on failure. 253The compiled files created are named from the 254.Xr basename 1 255of each file argument with 256.Dq .mgc 257appended to it. 258.Pp 259The 260.Fn magic_list 261function dumps all magic entries in a human readable format, 262dumping first the entries that are matched against binary files and then the 263ones that match text files. 264It takes and optional 265.Fa filename 266argument which is a colon separated list of database files, or 267.Dv NULL 268for the default database. 269.Pp 270The 271.Fn magic_load 272function must be used to load the colon 273separated list of database files passed in as 274.Ar filename , 275or 276.Dv NULL 277for the default database file before any magic queries can performed. 278.Pp 279The default database file is named by the MAGIC environment variable. 280If that variable is not set, the default database file name is 281.Pa /usr/share/misc/magic . 282.Fn magic_load 283adds 284.Dq .mgc 285to the database filename as appropriate. 286.Pp 287The 288.Fn magic_load_buffers 289function takes an array of size 290.Fa nbuffers 291of 292.Fa buffers 293with a respective size for each in the array of 294.Fa sizes 295loaded with the contents of the magic databases from the filesystem. 296This function can be used in environment where the magic library does 297not have direct access to the filesystem, but can access the magic 298database via shared memory or other IPC means. 299.Pp 300The 301.Fn magic_getparam 302and 303.Fn magic_setparam 304allow getting and setting various limits related to the magic 305library. 306.Bl -column "MAGIC_PARAM_ELF_PHNUM_MAX" "size_t" "Default" -offset indent 307.It Sy "Parameter" Ta Sy "Type" Ta Sy "Default" 308.It Li MAGIC_PARAM_INDIR_MAX Ta size_t Ta 15 309.It Li MAGIC_PARAM_NAME_MAX Ta size_t Ta 30 310.It Li MAGIC_PARAM_ELF_NOTES_MAX Ta size_t Ta 256 311.It Li MAGIC_PARAM_ELF_PHNUM_MAX Ta size_t Ta 128 312.It Li MAGIC_PARAM_ELF_SHNUM_MAX Ta size_t Ta 32768 313.It Li MAGIC_PARAM_REGEX_MAX Ta size_t Ta 8192 314.It Li MAGIC_PARAM_BYTES_MAX Ta size_t Ta 1048576 315.El 316.Pp 317The 318.Dv MAGIC_PARAM_INDIR_RECURSION 319parameter controls how many levels of recursion will be followed for 320indirect magic entries. 321.Pp 322The 323.Dv MAGIC_PARAM_NAME_RECURSION 324parameter controls how many levels of recursion will be followed for 325for name/use calls. 326.Pp 327The 328.Dv MAGIC_PARAM_NAME_MAX 329parameter controls the maximum number of calls for name/use. 330.Pp 331The 332.Dv MAGIC_PARAM_NOTES_MAX 333parameter controls how many ELF notes will be processed. 334.Pp 335The 336.Dv MAGIC_PARAM_PHNUM_MAX 337parameter controls how many ELF program sections will be processed. 338.Pp 339The 340.Dv MAGIC_PARAM_SHNUM_MAX 341parameter controls how many ELF sections will be processed. 342.Pp 343The 344.Fn magic_version 345command returns the version number of this library which is compiled into 346the shared library using the constant 347.Dv MAGIC_VERSION 348from 349.In magic.h . 350This can be used by client programs to verify that the version they compile 351against is the same as the version that they run against. 352.Sh RETURN VALUES 353The function 354.Fn magic_open 355returns a magic cookie on success and 356.Dv NULL 357on failure setting errno to an appropriate value. 358It will set errno to 359.Er EINVAL 360if an unsupported value for flags was given. 361The 362.Fn magic_list , 363.Fn magic_load , 364.Fn magic_compile , 365and 366.Fn magic_check 367functions return 0 on success and \-1 on failure. 368The 369.Fn magic_buffer , 370.Fn magic_getpath , 371and 372.Fn magic_file , 373functions return a string on success and 374.Dv NULL 375on failure. 376The 377.Fn magic_error 378function returns a textual description of the errors of the above 379functions, or 380.Dv NULL 381if there was no error. 382The 383.Fn magic_version 384always returns the version number of the library. 385Finally, 386.Fn magic_setflags 387returns \-1 on systems that don't support 388.Xr utime 3 , 389or 390.Xr utimes 2 391when 392.Dv MAGIC_PRESERVE_ATIME 393is set. 394.Sh FILES 395.Bl -tag -width /usr/share/misc/magic.mgc -compact 396.It Pa /usr/share/misc/magic 397The non-compiled default magic database. 398.It Pa /usr/share/misc/magic.mgc 399The compiled default magic database. 400.El 401.Sh SEE ALSO 402.Xr file 1 , 403.Xr magic 5 404.Sh BUGS 405The results from 406.Fn magic_buffer 407and 408.Fn magic_file 409where the buffer and the file contain the same data 410can produce different results, because in the 411.Fn magic_file 412case, the program can 413.Xr lseek 2 414and 415.Xr stat 2 416the file descriptor. 417.Sh AUTHORS 418.An M\(oans Rullg\(oard 419Initial libmagic implementation, and configuration. 420.An Christos Zoulas 421API cleanup, error code and allocation handling. 422