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