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