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