1.\" $File: libmagic.man,v 1.38 2015/09/11 17:24:09 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 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 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 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.El 296.Pp 297The 298.Dv MAGIC_PARAM_INDIR_RECURSION 299parameter controls how many levels of recursion will be followed for 300indirect magic entries. 301.Pp 302The 303.Dv MAGIC_PARAM_NAME_RECURSION 304parameter controls how many levels of recursion will be followed for 305for name/use calls. 306.Pp 307The 308.Dv MAGIC_PARAM_NAME_MAX 309parameter controls the maximum number of calls for name/use. 310.Pp 311The 312.Dv MAGIC_PARAM_NOTES_MAX 313parameter controls how many ELF notes will be processed. 314.Pp 315The 316.Dv MAGIC_PARAM_PHNUM_MAX 317parameter controls how many ELF program sections will be processed. 318.Pp 319The 320.Dv MAGIC_PARAM_SHNUM_MAX 321parameter controls how many ELF sections will be processed. 322.Pp 323The 324.Fn magic_version 325command returns the version number of this library which is compiled into 326the shared library using the constant 327.Dv MAGIC_VERSION 328from 329.In magic.h . 330This can be used by client programs to verify that the version they compile 331against is the same as the version that they run against. 332.Sh RETURN VALUES 333The function 334.Fn magic_open 335returns a magic cookie on success and 336.Dv NULL 337on failure setting errno to an appropriate value. 338It will set errno to 339.Er EINVAL 340if an unsupported value for flags was given. 341The 342.Fn magic_list , 343.Fn magic_load , 344.Fn magic_compile , 345and 346.Fn magic_check 347functions return 0 on success and \-1 on failure. 348The 349.Fn magic_buffer , 350.Fn magic_getpath , 351and 352.Fn magic_file , 353functions return a string on success and 354.Dv NULL 355on failure. 356The 357.Fn magic_error 358function returns a textual description of the errors of the above 359functions, or 360.Dv NULL 361if there was no error. 362The 363.Fn magic_version 364always returns the version number of the library. 365Finally, 366.Fn magic_setflags 367returns \-1 on systems that don't support 368.Xr utime 3 , 369or 370.Xr utimes 2 371when 372.Dv MAGIC_PRESERVE_ATIME 373is set. 374.Sh FILES 375.Bl -tag -width __MAGIC__.mgc -compact 376.It Pa __MAGIC__ 377The non-compiled default magic database. 378.It Pa __MAGIC__.mgc 379The compiled default magic database. 380.El 381.Sh SEE ALSO 382.Xr file __CSECTION__ , 383.Xr magic __FSECTION__ 384.Sh AUTHORS 385.An M\(oans Rullg\(oard 386Initial libmagic implementation, and configuration. 387.An Christos Zoulas 388API cleanup, error code and allocation handling. 389