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