1.\" $File: libmagic.man,v 1.34 2014/12/16 23:18:40 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 December 16, 2014 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_NO_CHECK_APPTYPE 136Don't check for 137.Dv EMX 138application type (only on EMX). 139.It Dv MAGIC_NO_CHECK_CDF 140Don't get extra information on MS Composite Document Files. 141.It Dv MAGIC_NO_CHECK_COMPRESS 142Don't look inside compressed files. 143.It Dv MAGIC_NO_CHECK_ELF 144Don't print ELF details. 145.It Dv MAGIC_NO_CHECK_ENCODING 146Don't check text encodings. 147.It Dv MAGIC_NO_CHECK_SOFT 148Don't consult magic files. 149.It Dv MAGIC_NO_CHECK_TAR 150Don't examine tar files. 151.It Dv MAGIC_NO_CHECK_TEXT 152Don't check for various types of text files. 153.It Dv MAGIC_NO_CHECK_TOKENS 154Don't look for known tokens inside ascii files. 155.El 156.Pp 157The 158.Fn magic_close 159function closes the 160.Xr magic __FSECTION__ 161database and deallocates any resources used. 162.Pp 163The 164.Fn magic_error 165function returns a textual explanation of the last error, or 166.Dv NULL 167if there was no error. 168.Pp 169The 170.Fn magic_errno 171function returns the last operating system error number 172.Pq Xr errno 2 173that was encountered by a system call. 174.Pp 175The 176.Fn magic_file 177function returns a textual description of the contents of the 178.Ar filename 179argument, or 180.Dv NULL 181if an error occurred. 182If the 183.Ar filename 184is 185.Dv NULL , 186then stdin is used. 187.Pp 188The 189.Fn magic_descriptor 190function returns a textual description of the contents of the 191.Ar fd 192argument, or 193.Dv NULL 194if an error occurred. 195.Pp 196The 197.Fn magic_buffer 198function returns a textual description of the contents of the 199.Ar buffer 200argument with 201.Ar length 202bytes size. 203.Pp 204The 205.Fn magic_setflags 206function sets the 207.Ar flags 208described above. 209Note that using both MIME flags together can also 210return extra information on the charset. 211.Pp 212The 213.Fn magic_check 214function can be used to check the validity of entries in the colon 215separated database files passed in as 216.Ar filename , 217or 218.Dv NULL 219for the default database. 220It returns 0 on success and \-1 on failure. 221.Pp 222The 223.Fn magic_compile 224function can be used to compile the the colon 225separated list of database files passed in as 226.Ar filename , 227or 228.Dv NULL 229for the default database. 230It returns 0 on success and \-1 on failure. 231The compiled files created are named from the 232.Xr basename 1 233of each file argument with 234.Dq .mgc 235appended to it. 236.Pp 237The 238.Fn magic_list 239function dumps all magic entries in a human readable format, 240dumping first the entries that are matched against binary files and then the 241ones that match text files. 242It takes and optional 243.Fa filename 244argument which is a colon separated list of database files, or 245.Dv NULL 246for the default database. 247.Pp 248The 249.Fn magic_load 250function must be used to load the the colon 251separated list of database files passed in as 252.Ar filename , 253or 254.Dv NULL 255for the default database file before any magic queries can performed. 256.Pp 257The default database file is named by the MAGIC environment variable. 258If that variable is not set, the default database file name is __MAGIC__. 259.Fn magic_load 260adds 261.Dq .mgc 262to the database filename as appropriate. 263.Pp 264The 265.Fn magic_load_buffers 266function takes an array of size 267.Fa nbuffers 268of 269.Fa buffers 270with a respective size for each in the array of 271.Fa sizes 272loaded with the contents of the magic databases from the filesystem. 273This function can be used in environment where the magic library does 274not have direct access to the filesystem, but can access the magic 275database via shared memory or other IPC means. 276.Pp 277The 278.Fn magic_getparam 279and 280.Fn magic_setparam 281allow getting and setting various limits related to the the magic 282library. 283.Bl -column "MAGIC_PARAM_ELF_PHNUM_MAX" "size_t" "Default" -offset indent 284.It Sy "Parameter" Ta Sy "Type" Ta Sy "Default" 285.It Li MAGIC_PARAM_INDIR_MAX Ta size_t Ta 15 286.It Li MAGIC_PARAM_NAME_MAX Ta size_t Ta 30 287.It Li MAGIC_PARAM_ELF_NOTES_MAX Ta size_t Ta 256 288.It Li MAGIC_PARAM_ELF_PHNUM_MAX Ta size_t Ta 128 289.It Li MAGIC_PARAM_ELF_SHNUM_MAX Ta size_t Ta 32768 290.El 291.Pp 292The 293.Dv MAGIC_PARAM_INDIR_RECURSION 294parameter controls how many levels of recursion will be followed for 295indirect magic entries. 296.Pp 297The 298.Dv MAGIC_PARAM_NAME_RECURSION 299parameter controls how many levels of recursion will be followed for 300for name/use calls. 301.Pp 302The 303.Dv MAGIC_PARAM_NAME_MAX 304parameter controls the maximum number of calls for name/use. 305.Pp 306The 307.Dv MAGIC_PARAM_NOTES_MAX 308parameter controls how many ELF notes will be processed. 309.Pp 310The 311.Dv MAGIC_PARAM_PHNUM_MAX 312parameter controls how many ELF program sections will be processed. 313.Pp 314The 315.Dv MAGIC_PARAM_SHNUM_MAX 316parameter controls how many ELF sections will be processed. 317.Pp 318The 319.Fn magic_version 320command returns the version number of this library which is compiled into 321the shared library using the constant 322.Dv MAGIC_VERSION 323from 324.In magic.h . 325This can be used by client programs to verify that the version they compile 326against is the same as the version that they run against. 327.Sh RETURN VALUES 328The function 329.Fn magic_open 330returns a magic cookie on success and 331.Dv NULL 332on failure setting errno to an appropriate value. 333It will set errno to 334.Er EINVAL 335if an unsupported value for flags was given. 336The 337.Fn magic_list , 338.Fn magic_load , 339.Fn magic_compile , 340and 341.Fn magic_check 342functions return 0 on success and \-1 on failure. 343The 344.Fn magic_buffer , 345.Fn magic_getpath , 346and 347.Fn magic_file , 348functions return a string on success and 349.Dv NULL 350on failure. 351The 352.Fn magic_error 353function returns a textual description of the errors of the above 354functions, or 355.Dv NULL 356if there was no error. 357The 358.Fn magic_version 359always returns the version number of the library. 360Finally, 361.Fn magic_setflags 362returns \-1 on systems that don't support 363.Xr utime 3 , 364or 365.Xr utimes 2 366when 367.Dv MAGIC_PRESERVE_ATIME 368is set. 369.Sh FILES 370.Bl -tag -width __MAGIC__.mgc -compact 371.It Pa __MAGIC__ 372The non-compiled default magic database. 373.It Pa __MAGIC__.mgc 374The compiled default magic database. 375.El 376.Sh SEE ALSO 377.Xr file __CSECTION__ , 378.Xr magic __FSECTION__ 379.Sh AUTHORS 380.An M\(oans Rullg\(oard 381Initial libmagic implementation, and configuration. 382.An Christos Zoulas 383API cleanup, error code and allocation handling. 384