1.\" $File: libmagic.man,v 1.19 2008/10/06 20:16:04 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 October 6, 2008 29.Dt MAGIC 3 30.Os 31.Sh NAME 32.Nm magic_open , 33.Nm magic_close , 34.Nm magic_error , 35.Nm magic_file , 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_file "magic_t cookie, const char *filename" 56.Ft const char * 57.Fn magic_buffer "magic_t cookie, const void *buffer, size_t length" 58.Ft int 59.Fn magic_setflags "magic_t cookie, int flags" 60.Ft int 61.Fn magic_check "magic_t cookie, const char *filename" 62.Ft int 63.Fn magic_compile "magic_t cookie, const char *filename" 64.Ft int 65.Fn magic_load "magic_t cookie, const char *filename" 66.Sh DESCRIPTION 67These functions 68operate on the magic database file 69which is described 70in 71.Xr magic __FSECTION__ . 72.Pp 73The function 74.Fn magic_open 75creates a magic cookie pointer and returns it. It returns NULL if 76there was an error allocating the magic cookie. The 77.Ar flags 78argument specifies how the other magic functions should behave: 79.Bl -tag -width MAGIC_COMPRESS 80.It Dv MAGIC_NONE 81No special handling. 82.It Dv MAGIC_DEBUG 83Print debugging messages to stderr. 84.It Dv MAGIC_SYMLINK 85If the file queried is a symlink, follow it. 86.It Dv MAGIC_COMPRESS 87If the file is compressed, unpack it and look at the contents. 88.It Dv MAGIC_DEVICES 89If the file is a block or character special device, then open the device 90and try to look in its contents. 91.It Dv MAGIC_MIME_TYPE 92Return a MIME type string, instead of a textual description. 93.It Dv MAGIC_MIME_ENCODING 94Return a MIME encoding, instead of a textual description. 95.It Dv MAGIC_CONTINUE 96Return all matches, not just the first. 97.It Dv MAGIC_CHECK 98Check the magic database for consistency and print warnings to stderr. 99.It Dv MAGIC_PRESERVE_ATIME 100On systems that support 101.Xr utime 2 102or 103.Xr utimes 2 , 104attempt to preserve the access time of files analyzed. 105.It Dv MAGIC_RAW 106Don't translate unprintable characters to a \eooo octal representation. 107.It Dv MAGIC_ERROR 108Treat operating system errors while trying to open files and follow symlinks 109as real errors, instead of printing them in the magic buffer. 110.It Dv MAGIC_NO_CHECK_APPTYPE 111Check for 112.Dv EMX 113application type (only on EMX). 114.It Dv MAGIC_NO_CHECK_ASCII 115Check for various types of ascii files. 116.It Dv MAGIC_NO_CHECK_COMPRESS 117Don't look for, or inside compressed files. 118.It Dv MAGIC_NO_CHECK_ELF 119Don't print elf details. 120.It Dv MAGIC_NO_CHECK_FORTRAN 121Don't look for fortran sequences inside ascii files. 122.It Dv MAGIC_NO_CHECK_SOFT 123Don't consult magic files. 124.It Dv MAGIC_NO_CHECK_TAR 125Don't examine tar files. 126.It Dv MAGIC_NO_CHECK_TOKENS 127Don't look for known tokens inside ascii files. 128.It Dv MAGIC_NO_CHECK_TROFF 129Don't look for troff sequences inside ascii files. 130.El 131.Pp 132The 133.Fn magic_close 134function closes the 135.Xr magic __FSECTION__ 136database and deallocates any resources used. 137.Pp 138The 139.Fn magic_error 140function returns a textual explanation of the last error, or NULL if there was 141no error. 142.Pp 143The 144.Fn magic_errno 145function returns the last operating system error number 146.Pq Xr errno 2 147that was encountered by a system call. 148.Pp 149The 150.Fn magic_file 151function returns a textual description of the contents of the 152.Ar filename 153argument, or NULL if an error occurred. 154If the 155.Ar filename 156is NULL, then stdin is used. 157.Pp 158The 159.Fn magic_buffer 160function returns a textual description of the contents of the 161.Ar buffer 162argument with 163.Ar length 164bytes size. 165.Pp 166The 167.Fn magic_setflags 168function sets the 169.Ar flags 170described above. Note that using both MIME flags together can also 171return extra information on the charset. 172.Pp 173The 174.Fn magic_check 175function can be used to check the validity of entries in the colon 176separated database files passed in as 177.Ar filename , 178or NULL for the default database. It returns 0 on success and -1 on 179failure. 180.Pp 181The 182.Fn magic_compile 183function can be used to compile the the colon 184separated list of database files passed in as 185.Ar filename , 186or NULL for the default database. It returns 0 on success and -1 on 187failure. The compiled files created are named from the 188.Xr basename 1 189of each file argument with 190.Dq .mgc 191appended to it. 192.Pp 193The 194.Fn magic_load 195function must be used to load the the colon 196separated list of database files passed in as 197.Ar filename , 198or NULL for the default database file 199before any magic queries can performed. 200.Pp 201The default database file is named by the MAGIC environment variable. If 202that variable is not set, the default database file name is __MAGIC__. 203.Fn magic_load 204adds 205.Dq .mgc 206to the database filename as appropriate. 207.Sh RETURN VALUES 208The function 209.Fn magic_open 210returns a magic cookie on success and NULL on failure setting errno to 211an appropriate value. It will set errno to EINVAL if an unsupported 212value for flags was given. 213The 214.Fn magic_load , 215.Fn magic_compile , 216and 217.Fn magic_check 218functions return 0 on success and -1 on failure. 219The 220.Fn magic_file , 221and 222.Fn magic_buffer 223functions return a string on success and NULL on failure. The 224.Fn magic_error 225function returns a textual description of the errors of the above 226functions, or NULL if there was no error. 227Finally, 228.Fn magic_setflags 229returns -1 on systems that don't support 230.Xr utime 2 , 231or 232.Xr utimes 2 233when 234.Dv MAGIC_PRESERVE_ATIME 235is set. 236.Sh FILES 237.Bl -tag -width __MAGIC__.mgc -compact 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