1.\" 2.\" Copyright (c) Christos Zoulas 2003. 3.\" All Rights Reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice immediately at the beginning of the file, without modification, 10.\" this list of conditions, and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR 19.\" ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.Dd November 15, 2006 28.Dt MAGIC 3 29.Os 30.Sh NAME 31.Nm magic_open , 32.Nm magic_close , 33.Nm magic_error , 34.Nm magic_file , 35.Nm magic_buffer , 36.Nm magic_setflags , 37.Nm magic_check , 38.Nm magic_compile , 39.Nm magic_load 40.Nd Magic number recognition library. 41.Sh LIBRARY 42.Lb libmagic 43.Sh SYNOPSIS 44.In magic.h 45.Ft magic_t 46.Fn magic_open "int flags" 47.Ft void 48.Fn magic_close "magic_t cookie" 49.Ft const char * 50.Fn magic_error "magic_t cookie" 51.Ft int 52.Fn magic_errno "magic_t cookie" 53.Ft const char * 54.Fn magic_file "magic_t cookie, const char *filename" 55.Ft const char * 56.Fn magic_buffer "magic_t cookie, const void *buffer, size_t length" 57.Ft int 58.Fn magic_setflags "magic_t cookie, int flags" 59.Ft int 60.Fn magic_check "magic_t cookie, const char *filename" 61.Ft int 62.Fn magic_compile "magic_t cookie, const char *filename" 63.Ft int 64.Fn magic_load "magic_t cookie, const char *filename" 65.Sh DESCRIPTION 66These functions 67operate on the magic database file 68which is described 69in 70.Xr magic __FSECTION__ . 71.Pp 72The function 73.Fn magic_open 74creates a magic cookie pointer and returns it. It returns NULL if 75there was an error allocating the magic cookie. The 76.Ar flags 77argument specifies how the other magic functions should behave: 78.Bl -tag -width MAGIC_COMPRESS 79.It Dv MAGIC_NONE 80No special handling. 81.It Dv MAGIC_DEBUG 82Print debugging messages to stderr. 83.It Dv MAGIC_SYMLINK 84If the file queried is a symlink, follow it. 85.It Dv MAGIC_COMPRESS 86If the file is compressed, unpack it and look at the contents. 87.It Dv MAGIC_DEVICES 88If the file is a block or character special device, then open the device 89and try to look in its contents. 90.It Dv MAGIC_MIME_TYPE 91Return a MIME type string, instead of a textual description. 92.It Dv MAGIC_MIME_ENCODING 93Return a MIME encoding, instead of a textual description. 94.It Dv MAGIC_CONTINUE 95Return all matches, not just the first. 96.It Dv MAGIC_CHECK 97Check the magic database for consistency and print warnings to stderr. 98.It Dv MAGIC_PRESERVE_ATIME 99On systems that support 100.Xr utime 2 101or 102.Xr utimes 2 , 103attempt to preserve the access time of files analyzed. 104.It Dv MAGIC_RAW 105Don't translate unprintable characters to a \eooo octal representation. 106.It Dv MAGIC_ERROR 107Treat operating system errors while trying to open files and follow symlinks 108as real errors, instead of printing them in the magic buffer. 109.It Dv MAGIC_NO_CHECK_APPTYPE 110Check for 111.Dv EMX 112application type (only on EMX). 113.It Dv MAGIC_NO_CHECK_ASCII 114Check for various types of ascii files. 115.It Dv MAGIC_NO_CHECK_COMPRESS 116Don't look for, or inside compressed files. 117.It Dv MAGIC_NO_CHECK_ELF 118Don't print elf details. 119.It Dv MAGIC_NO_CHECK_FORTRAN 120Don't look for fortran sequences inside ascii files. 121.It Dv MAGIC_NO_CHECK_SOFT 122Don't consult magic files. 123.It Dv MAGIC_NO_CHECK_TAR 124Don't examine tar files. 125.It Dv MAGIC_NO_CHECK_TOKENS 126Don't look for known tokens inside ascii files. 127.It Dv MAGIC_NO_CHECK_TROFF 128Don't look for troff sequences inside ascii files. 129.El 130.Pp 131The 132.Fn magic_close 133function closes the 134.Xr magic __FSECTION__ 135database and deallocates any resources used. 136.Pp 137The 138.Fn magic_error 139function returns a textual explanation of the last error, or NULL if there was 140no error. 141.Pp 142The 143.Fn magic_errno 144function returns the last operating system error number 145.Pq Xr errno 2 146that was encountered by a system call. 147.Pp 148The 149.Fn magic_file 150function returns a textual description of the contents of the 151.Ar filename 152argument, or NULL if an error occurred. 153If the 154.Ar filename 155is NULL, then stdin is used. 156.Pp 157The 158.Fn magic_buffer 159function returns a textual description of the contents of the 160.Ar buffer 161argument with 162.Ar length 163bytes size. 164.Pp 165The 166.Fn magic_setflags 167function, sets the 168.Ar flags 169described above. Note that using both MIME flags together can also 170return extra information on the charset. 171.Pp 172The 173.Fn magic_check 174function can be used to check the validity of entries in the colon 175separated database files passed in as 176.Ar filename , 177or NULL for the default database. It returns 0 on success and -1 on 178failure. 179.Pp 180The 181.Fn magic_compile 182function can be used to compile the the colon 183separated list of database files passed in as 184.Ar filename , 185or NULL for the default database. It returns 0 on success and -1 on 186failure. The compiled files created are named from the 187.Xr basename 1 188of each file argument with ".mgc" appended to it. 189.Pp 190The 191.Fn magic_load 192function must be used to load the the colon 193separated list of database files passed in as 194.Ar filename , 195or NULL for the default database file 196before any magic queries can performed. 197.Pp 198The default database file is named by the MAGIC environment variable. If 199that variable is not set, the default database file name is __MAGIC__. 200.Pp 201.Fn magic_load 202adds ".mime" and/or ".mgc" to the database filename as appropriate. 203.Sh RETURN VALUES 204The function 205.Fn magic_open 206returns a magic cookie on success and NULL on failure setting errno to 207an appropriate value. It will set errno to EINVAL if an unsupported 208value for flags was given. 209The 210.Fn magic_load , 211.Fn magic_compile , 212and 213.Fn magic_check 214functions return 0 on success and -1 on failure. 215The 216.Fn magic_file , 217and 218.Fn magic_buffer 219functions return a string on success and NULL on failure. The 220.Fn magic_error 221function returns a textual description of the errors of the above 222functions, or NULL if there was no error. 223Finally, 224.Fn magic_setflags 225returns -1 on systems that don't support 226.Xr utime 2 , 227or 228.Xr utimes 2 229when 230.Dv MAGIC_PRESERVE_ATIME 231is set. 232.Sh FILES 233.Bl -tag -width __MAGIC__.mime.mgc -compact 234.It Pa __MAGIC__.mime 235The non-compiled default magic mime database. 236.It Pa __MAGIC__.mime.mgc 237The compiled default magic mime database. 238.It Pa __MAGIC__ 239The non-compiled default magic database. 240.It Pa __MAGIC__.mgc 241The compiled default magic database. 242.El 243.Sh SEE ALSO 244.Xr file __CSECTION__ , 245.Xr magic __FSECTION__ 246.Sh AUTHORS 247M�ns Rullg�rd Initial libmagic implementation, 248and configuration. 249Christos Zoulas API cleanup, error code and allocation handling. 250