1.\" $File: libmagic.man,v 1.26 2011/12/19 17:49:31 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 19, 2011 29.Dt LIBMAGIC 3 30.Os 31.Sh NAME 32.Nm magic_open , 33.Nm magic_close , 34.Nm magic_error , 35.Nm magic_descriptor , 36.Nm magic_buffer , 37.Nm magic_setflags , 38.Nm magic_check , 39.Nm magic_compile , 40.Nm magic_load 41.Nd Magic number recognition library 42.Sh LIBRARY 43.Lb libmagic 44.Sh SYNOPSIS 45.In magic.h 46.Ft magic_t 47.Fn magic_open "int flags" 48.Ft void 49.Fn magic_close "magic_t cookie" 50.Ft const char * 51.Fn magic_error "magic_t cookie" 52.Ft int 53.Fn magic_errno "magic_t cookie" 54.Ft const char * 55.Fn magic_descriptor "magic_t cookie" "int fd" 56.Ft const char * 57.Fn magic_file "magic_t cookie" "const char *filename" 58.Ft const char * 59.Fn magic_buffer "magic_t cookie" "const void *buffer" "size_t length" 60.Ft int 61.Fn magic_setflags "magic_t cookie" "int flags" 62.Ft int 63.Fn magic_check "magic_t cookie" "const char *filename" 64.Ft int 65.Fn magic_compile "magic_t cookie" "const char *filename" 66.Ft int 67.Fn magic_list "magic_t cookie" "const char *filename" 68.Ft int 69.Fn magic_load "magic_t cookie" "const char *filename" 70.Sh DESCRIPTION 71These functions 72operate on the magic database file 73which is described 74in 75.Xr magic __FSECTION__ . 76.Pp 77The function 78.Fn magic_open 79creates a magic cookie pointer and returns it. 80It returns 81.Dv NULL 82if there was an error allocating the magic cookie. 83The 84.Ar flags 85argument specifies how the other magic functions should behave: 86.Bl -tag -width MAGIC_COMPRESS 87.It Dv MAGIC_NONE 88No special handling. 89.It Dv MAGIC_DEBUG 90Print debugging messages to stderr. 91.It Dv MAGIC_SYMLINK 92If the file queried is a symlink, follow it. 93.It Dv MAGIC_COMPRESS 94If the file is compressed, unpack it and look at the contents. 95.It Dv MAGIC_DEVICES 96If the file is a block or character special device, then open the device 97and try to look in its contents. 98.It Dv MAGIC_MIME_TYPE 99Return a MIME type string, instead of a textual description. 100.It Dv MAGIC_MIME_ENCODING 101Return a MIME encoding, instead of a textual description. 102.It Dv MAGIC_MIME 103A shorthand for MAGIC_MIME_TYPE | MAGIC_MIME_ENCODING. 104.It Dv MAGIC_CONTINUE 105Return all matches, not just the first. 106.It Dv MAGIC_CHECK 107Check the magic database for consistency and print warnings to stderr. 108.It Dv MAGIC_PRESERVE_ATIME 109On systems that support 110.Xr utime 3 111or 112.Xr utimes 2 , 113attempt to preserve the access time of files analysed. 114.It Dv MAGIC_RAW 115Don't translate unprintable characters to a \eooo octal representation. 116.It Dv MAGIC_ERROR 117Treat operating system errors while trying to open files and follow symlinks 118as real errors, instead of printing them in the magic buffer. 119.It Dv MAGIC_APPLE 120Return the Apple creator and type. 121.It Dv MAGIC_NO_CHECK_APPTYPE 122Don't check for 123.Dv EMX 124application type (only on EMX). 125.It Dv MAGIC_NO_CHECK_CDF 126Don't get extra information on MS Composite Document Files. 127.It Dv MAGIC_NO_CHECK_COMPRESS 128Don't look inside compressed files. 129.It Dv MAGIC_NO_CHECK_ELF 130Don't print ELF details. 131.It Dv MAGIC_NO_CHECK_ENCODING 132Don't check text encodings. 133.It Dv MAGIC_NO_CHECK_SOFT 134Don't consult magic files. 135.It Dv MAGIC_NO_CHECK_TAR 136Don't examine tar files. 137.It Dv MAGIC_NO_CHECK_TEXT 138Don't check for various types of text files. 139.It Dv MAGIC_NO_CHECK_TOKENS 140Don't look for known tokens inside ascii files. 141.El 142.Pp 143The 144.Fn magic_close 145function closes the 146.Xr magic __FSECTION__ 147database and deallocates any resources used. 148.Pp 149The 150.Fn magic_error 151function returns a textual explanation of the last error, or 152.Dv NULL 153if there was no error. 154.Pp 155The 156.Fn magic_errno 157function returns the last operating system error number 158.Pq Xr errno 2 159that was encountered by a system call. 160.Pp 161The 162.Fn magic_file 163function returns a textual description of the contents of the 164.Ar filename 165argument, or 166.Dv NULL 167if an error occurred. 168If the 169.Ar filename 170is 171.Dv NULL , 172then stdin is used. 173.Pp 174The 175.Fn magic_descriptor 176function returns a textual description of the contents of the 177.Ar fd 178argument, or 179.Dv NULL 180if an error occurred. 181.Pp 182The 183.Fn magic_buffer 184function returns a textual description of the contents of the 185.Ar buffer 186argument with 187.Ar length 188bytes size. 189.Pp 190The 191.Fn magic_setflags 192function sets the 193.Ar flags 194described above. 195Note that using both MIME flags together can also 196return extra information on the charset. 197.Pp 198The 199.Fn magic_check 200function can be used to check the validity of entries in the colon 201separated database files passed in as 202.Ar filename , 203or 204.Dv NULL 205for the default database. 206It returns 0 on success and \-1 on failure. 207.Pp 208The 209.Fn magic_compile 210function can be used to compile the the colon 211separated list of database files passed in as 212.Ar filename , 213or 214.Dv NULL 215for the default database. 216It returns 0 on success and \-1 on failure. 217The compiled files created are named from the 218.Xr basename 1 219of each file argument with 220.Dq .mgc 221appended to it. 222.Pp 223The 224.Fn magic_list 225function dumps all magic entries in a human readable format, 226dumping first the entries that are matched against binary files and then the 227ones that match text files. 228It takes and optional 229.Fa filename 230argument which is a colon separated list of database files, or 231.Dv NULL 232for the default database. 233.Pp 234The 235.Fn magic_load 236function must be used to load the the colon 237separated list of database files passed in as 238.Ar filename , 239or 240.Dv NULL 241for the default database file before any magic queries can performed. 242.Pp 243The default database file is named by the MAGIC environment variable. 244If that variable is not set, the default database file name is __MAGIC__. 245.Fn magic_load 246adds 247.Dq .mgc 248to the database filename as appropriate. 249.Sh RETURN VALUES 250The function 251.Fn magic_open 252returns a magic cookie on success and 253.Dv NULL 254on failure setting errno to an appropriate value. 255It will set errno to 256.Er EINVAL 257if an unsupported value for flags was given. 258The 259.Fn magic_list , 260.Fn magic_load , 261.Fn magic_compile , 262and 263.Fn magic_check 264functions return 0 on success and \-1 on failure. 265The 266.Fn magic_buffer , 267.Fn magic_getpath , 268and 269.Fn magic_file , 270functions return a string on success and 271.Dv NULL 272on failure. 273The 274.Fn magic_error 275function returns a textual description of the errors of the above 276functions, or 277.Dv NULL 278if there was no error. 279Finally, 280.Fn magic_setflags 281returns \-1 on systems that don't support 282.Xr utime 3 , 283or 284.Xr utimes 2 285when 286.Dv MAGIC_PRESERVE_ATIME 287is set. 288.Sh FILES 289.Bl -tag -width __MAGIC__.mgc -compact 290.It Pa __MAGIC__ 291The non-compiled default magic database. 292.It Pa __MAGIC__.mgc 293The compiled default magic database. 294.El 295.Sh SEE ALSO 296.Xr file __CSECTION__ , 297.Xr magic __FSECTION__ 298.Sh AUTHORS 299.An M\(oans Rullg\(oard 300Initial libmagic implementation, and configuration. 301.An Christos Zoulas 302API cleanup, error code and allocation handling. 303