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