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