1.\" $NetBSD: libmagic.3,v 1.21 2023/08/18 19:00:10 christos Exp $ 2.\" 3.\" $File: libmagic.man,v 1.49 2023/07/20 14:32:07 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 June 16, 2023 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.Ft const char * 91.Fn magic_getpath "const char *magicfile" "int action" 92.Sh DESCRIPTION 93These functions 94operate on the magic database file 95which is described 96in 97.Xr magic 5 . 98.Pp 99The function 100.Fn magic_open 101creates a magic cookie pointer and returns it. 102It returns 103.Dv NULL 104if there was an error allocating the magic cookie. 105The 106.Ar flags 107argument specifies how the other magic functions should behave: 108.Bl -tag -width MAGIC_COMPRESS 109.It Dv MAGIC_NONE 110No special handling. 111.It Dv MAGIC_DEBUG 112Print debugging messages to stderr. 113.It Dv MAGIC_SYMLINK 114If the file queried is a symlink, follow it. 115.It Dv MAGIC_COMPRESS 116If the file is compressed, unpack it and look at the contents. 117.It Dv MAGIC_DEVICES 118If the file is a block or character special device, then open the device 119and try to look in its contents. 120.It Dv MAGIC_MIME_TYPE 121Return a MIME type string, instead of a textual description. 122.It Dv MAGIC_MIME_ENCODING 123Return a MIME encoding, instead of a textual description. 124.It Dv MAGIC_MIME 125A shorthand for MAGIC_MIME_TYPE | MAGIC_MIME_ENCODING. 126.It Dv MAGIC_CONTINUE 127Return all matches, not just the first. 128.It Dv MAGIC_CHECK 129Check the magic database for consistency and print warnings to stderr. 130.It Dv MAGIC_PRESERVE_ATIME 131On systems that support 132.Xr utime 3 133or 134.Xr utimes 2 , 135attempt to preserve the access time of files analysed. 136.It Dv MAGIC_RAW 137Don't translate unprintable characters to a \eooo octal representation. 138.It Dv MAGIC_ERROR 139Treat operating system errors while trying to open files and follow symlinks 140as real errors, instead of printing them in the magic buffer. 141.It Dv MAGIC_APPLE 142Return the Apple creator and type. 143.It Dv MAGIC_EXTENSION 144Return a slash-separated list of extensions for this file type. 145.It Dv MAGIC_COMPRESS_TRANSP 146Don't report on compression, only report about the uncompressed data. 147.It Dv MAGIC_NO_CHECK_APPTYPE 148Don't check for 149.Dv EMX 150application type (only on EMX). 151.It Dv MAGIC_NO_COMPRESS_FORK 152Don't allow decompressors that use fork. 153.It Dv MAGIC_NO_CHECK_CDF 154Don't get extra information on MS Composite Document Files. 155.It Dv MAGIC_NO_CHECK_COMPRESS 156Don't look inside compressed files. 157.It Dv MAGIC_NO_CHECK_ELF 158Don't print ELF details. 159.It Dv MAGIC_NO_CHECK_ENCODING 160Don't check text encodings. 161.It Dv MAGIC_NO_CHECK_SOFT 162Don't consult magic files. 163.It Dv MAGIC_NO_CHECK_TAR 164Don't examine tar files. 165.It Dv MAGIC_NO_CHECK_TEXT 166Don't check for various types of text files. 167.It Dv MAGIC_NO_CHECK_TOKENS 168Don't look for known tokens inside ascii files. 169.It Dv MAGIC_NO_CHECK_JSON 170Don't examine JSON files. 171.It Dv MAGIC_NO_CHECK_CSV 172Don't examine CSV files. 173.It Dv MAGIC_NO_CHECK_SIMH 174Don't examine SIMH tape files. 175.El 176.Pp 177The 178.Fn magic_close 179function closes the 180.Xr magic 5 181database and deallocates any resources used. 182.Pp 183The 184.Fn magic_error 185function returns a textual explanation of the last error, or 186.Dv NULL 187if there was no error. 188.Pp 189The 190.Fn magic_errno 191function returns the last operating system error number 192.Pq Xr errno 2 193that was encountered by a system call. 194.Pp 195The 196.Fn magic_file 197function returns a textual description of the contents of the 198.Ar filename 199argument, or 200.Dv NULL 201if an error occurred. 202If the 203.Ar filename 204is 205.Dv NULL , 206then stdin is used. 207.Pp 208The 209.Fn magic_descriptor 210function returns a textual description of the contents of the 211.Ar fd 212argument, or 213.Dv NULL 214if an error occurred. 215.Pp 216The 217.Fn magic_buffer 218function returns a textual description of the contents of the 219.Ar buffer 220argument with 221.Ar length 222bytes size. 223.Pp 224The 225.Fn magic_getflags 226functions returns a value representing current 227.Ar flags 228set. 229.Pp 230The 231.Fn magic_setflags 232function sets the 233.Ar flags 234described above. 235Note that using both MIME flags together can also 236return extra information on the charset. 237.Pp 238The 239.Fn magic_check 240function can be used to check the validity of entries in the colon 241separated database files passed in as 242.Ar filename , 243or 244.Dv NULL 245for the default database. 246It returns 0 on success and \-1 on failure. 247.Pp 248The 249.Fn magic_compile 250function can be used to compile the colon 251separated list of database files passed in as 252.Ar filename , 253or 254.Dv NULL 255for the default database. 256It returns 0 on success and \-1 on failure. 257The compiled files created are named from the 258.Xr basename 1 259of each file argument with 260.Dq .mgc 261appended to it. 262.Pp 263The 264.Fn magic_list 265function dumps all magic entries in a human readable format, 266dumping first the entries that are matched against binary files and then the 267ones that match text files. 268It takes and optional 269.Fa filename 270argument which is a colon separated list of database files, or 271.Dv NULL 272for the default database. 273.Pp 274The 275.Fn magic_load 276function must be used to load the colon 277separated list of database files passed in as 278.Ar filename , 279or 280.Dv NULL 281for the default database file before any magic queries can performed. 282.Pp 283The default database file is named by the MAGIC environment variable. 284If that variable is not set, the default database file name is 285.Pa /usr/share/misc/magic . 286.Fn magic_load 287adds 288.Dq .mgc 289to the database filename as appropriate. 290.Pp 291The 292.Fn magic_load_buffers 293function takes an array of size 294.Fa nbuffers 295of 296.Fa buffers 297with a respective size for each in the array of 298.Fa sizes 299loaded with the contents of the magic databases from the filesystem. 300This function can be used in environment where the magic library does 301not have direct access to the filesystem, but can access the magic 302database via shared memory or other IPC means. 303.Pp 304The 305.Fn magic_getparam 306and 307.Fn magic_setparam 308allow getting and setting various limits related to the magic 309library. 310.Bl -column "MAGIC_PARAM_ELF_PHNUM_MAX" "size_t" "Default" -offset indent 311.It Sy "Parameter" Ta Sy "Type" Ta Sy "Default" 312.It Li MAGIC_PARAM_INDIR_MAX Ta size_t Ta 15 313.It Li MAGIC_PARAM_NAME_MAX Ta size_t Ta 30 314.It Li MAGIC_PARAM_ELF_NOTES_MAX Ta size_t Ta 256 315.It Li MAGIC_PARAM_ELF_PHNUM_MAX Ta size_t Ta 128 316.It Li MAGIC_PARAM_ELF_SHNUM_MAX Ta size_t Ta 32768 317.It Li MAGIC_PARAM_REGEX_MAX Ta size_t Ta 8192 318.It Li MAGIC_PARAM_BYTES_MAX Ta size_t Ta 1048576 319.El 320.Pp 321The 322.Dv MAGIC_PARAM_INDIR_RECURSION 323parameter controls how many levels of recursion will be followed for 324indirect magic entries. 325.Pp 326The 327.Dv MAGIC_PARAM_NAME_RECURSION 328parameter controls how many levels of recursion will be followed for 329for name/use calls. 330.Pp 331The 332.Dv MAGIC_PARAM_NAME_MAX 333parameter controls the maximum number of calls for name/use. 334.Pp 335The 336.Dv MAGIC_PARAM_NOTES_MAX 337parameter controls how many ELF notes will be processed. 338.Pp 339The 340.Dv MAGIC_PARAM_PHNUM_MAX 341parameter controls how many ELF program sections will be processed. 342.Pp 343The 344.Dv MAGIC_PARAM_SHNUM_MAX 345parameter controls how many ELF sections will be processed. 346.Pp 347The 348.Fn magic_version 349command returns the version number of this library which is compiled into 350the shared library using the constant 351.Dv MAGIC_VERSION 352from 353.In magic.h . 354This can be used by client programs to verify that the version they compile 355against is the same as the version that they run against. 356.Pp 357The 358.Fn magic_getpath 359command returns the colon separated list of magic database locations. 360If the 361.Fa filename 362is non-NULL, then it is returned. 363Otherwise, if the 364.Dv MAGIC 365environment variable is defined, then it is returned. 366Otherwise, if 367.Fa action 368is 0 (meaning "file load"), then any user-specific magic database file is included. 369Otherwise, only the system default magic database path is included. 370.Sh RETURN VALUES 371The function 372.Fn magic_open 373returns a magic cookie on success and 374.Dv NULL 375on failure setting errno to an appropriate value. 376It will set errno to 377.Er EINVAL 378if an unsupported value for flags was given. 379The 380.Fn magic_list , 381.Fn magic_load , 382.Fn magic_compile , 383and 384.Fn magic_check 385functions return 0 on success and \-1 on failure. 386The 387.Fn magic_buffer , 388.Fn magic_getpath , 389and 390.Fn magic_file , 391functions return a string on success and 392.Dv NULL 393on failure. 394The 395.Fn magic_error 396function returns a textual description of the errors of the above 397functions, or 398.Dv NULL 399if there was no error. 400The 401.Fn magic_version 402always returns the version number of the library. 403Finally, 404.Fn magic_setflags 405returns \-1 on systems that don't support 406.Xr utime 3 , 407or 408.Xr utimes 2 409when 410.Dv MAGIC_PRESERVE_ATIME 411is set. 412.Sh FILES 413.Bl -tag -width /usr/share/misc/magic.mgc -compact 414.It Pa /usr/share/misc/magic 415The non-compiled default magic database. 416.It Pa /usr/share/misc/magic.mgc 417The compiled default magic database. 418.El 419.Sh SEE ALSO 420.Xr file 1 , 421.Xr magic 5 422.Sh BUGS 423The results from 424.Fn magic_buffer 425and 426.Fn magic_file 427where the buffer and the file contain the same data 428can produce different results, because in the 429.Fn magic_file 430case, the program can 431.Xr lseek 2 432and 433.Xr stat 2 434the file descriptor. 435.Sh AUTHORS 436.An M\(oans Rullg\(oard 437Initial libmagic implementation, and configuration. 438.An Christos Zoulas 439API cleanup, error code and allocation handling. 440