1.\" $NetBSD: libmagic.3,v 1.11 2013/03/23 16:15:57 christos Exp $ 2.\" 3.\" $File: libmagic.man,v 1.27 2013/01/06 20:56:52 christos Exp $ 4.\" 5.\" Copyright (c) Christos Zoulas 2003. 6.\" All Rights Reserved. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice immediately at the beginning of the file, without modification, 13.\" this list of conditions, and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR 22.\" ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.Dd January 6, 2012 31.Dt LIBMAGIC 3 32.Os 33.Sh NAME 34.Nm magic_open , 35.Nm magic_close , 36.Nm magic_error , 37.Nm magic_descriptor , 38.Nm magic_buffer , 39.Nm magic_setflags , 40.Nm magic_check , 41.Nm magic_compile , 42.Nm magic_list , 43.Nm magic_load , 44.Nm magic_version 45.Nd Magic number recognition library 46.Sh LIBRARY 47.Lb libmagic 48.Sh SYNOPSIS 49.In magic.h 50.Ft magic_t 51.Fn magic_open "int flags" 52.Ft void 53.Fn magic_close "magic_t cookie" 54.Ft const char * 55.Fn magic_error "magic_t cookie" 56.Ft int 57.Fn magic_errno "magic_t cookie" 58.Ft const char * 59.Fn magic_descriptor "magic_t cookie" "int fd" 60.Ft const char * 61.Fn magic_file "magic_t cookie" "const char *filename" 62.Ft const char * 63.Fn magic_buffer "magic_t cookie" "const void *buffer" "size_t length" 64.Ft int 65.Fn magic_setflags "magic_t cookie" "int flags" 66.Ft int 67.Fn magic_check "magic_t cookie" "const char *filename" 68.Ft int 69.Fn magic_compile "magic_t cookie" "const char *filename" 70.Ft int 71.Fn magic_list "magic_t cookie" "const char *filename" 72.Ft int 73.Fn magic_load "magic_t cookie" "const char *filename" 74.Ft int 75.Fn magic_version "void" 76.Sh DESCRIPTION 77These functions 78operate on the magic database file 79which is described 80in 81.Xr magic 5 . 82.Pp 83The function 84.Fn magic_open 85creates a magic cookie pointer and returns it. 86It returns 87.Dv NULL 88if there was an error allocating the magic cookie. 89The 90.Ar flags 91argument specifies how the other magic functions should behave: 92.Bl -tag -width MAGIC_COMPRESS 93.It Dv MAGIC_NONE 94No special handling. 95.It Dv MAGIC_DEBUG 96Print debugging messages to stderr. 97.It Dv MAGIC_SYMLINK 98If the file queried is a symlink, follow it. 99.It Dv MAGIC_COMPRESS 100If the file is compressed, unpack it and look at the contents. 101.It Dv MAGIC_DEVICES 102If the file is a block or character special device, then open the device 103and try to look in its contents. 104.It Dv MAGIC_MIME_TYPE 105Return a MIME type string, instead of a textual description. 106.It Dv MAGIC_MIME_ENCODING 107Return a MIME encoding, instead of a textual description. 108.It Dv MAGIC_MIME 109A shorthand for MAGIC_MIME_TYPE | MAGIC_MIME_ENCODING. 110.It Dv MAGIC_CONTINUE 111Return all matches, not just the first. 112.It Dv MAGIC_CHECK 113Check the magic database for consistency and print warnings to stderr. 114.It Dv MAGIC_PRESERVE_ATIME 115On systems that support 116.Xr utime 3 117or 118.Xr utimes 2 , 119attempt to preserve the access time of files analysed. 120.It Dv MAGIC_RAW 121Don't translate unprintable characters to a \eooo octal representation. 122.It Dv MAGIC_ERROR 123Treat operating system errors while trying to open files and follow symlinks 124as real errors, instead of printing them in the magic buffer. 125.It Dv MAGIC_APPLE 126Return the Apple creator and type. 127.It Dv MAGIC_NO_CHECK_APPTYPE 128Don't check for 129.Dv EMX 130application type (only on EMX). 131.It Dv MAGIC_NO_CHECK_CDF 132Don't get extra information on MS Composite Document Files. 133.It Dv MAGIC_NO_CHECK_COMPRESS 134Don't look inside compressed files. 135.It Dv MAGIC_NO_CHECK_ELF 136Don't print ELF details. 137.It Dv MAGIC_NO_CHECK_ENCODING 138Don't check text encodings. 139.It Dv MAGIC_NO_CHECK_SOFT 140Don't consult magic files. 141.It Dv MAGIC_NO_CHECK_TAR 142Don't examine tar files. 143.It Dv MAGIC_NO_CHECK_TEXT 144Don't check for various types of text files. 145.It Dv MAGIC_NO_CHECK_TOKENS 146Don't look for known tokens inside ascii files. 147.El 148.Pp 149The 150.Fn magic_close 151function closes the 152.Xr magic 5 153database and deallocates any resources used. 154.Pp 155The 156.Fn magic_error 157function returns a textual explanation of the last error, or 158.Dv NULL 159if there was no error. 160.Pp 161The 162.Fn magic_errno 163function returns the last operating system error number 164.Pq Xr errno 2 165that was encountered by a system call. 166.Pp 167The 168.Fn magic_file 169function returns a textual description of the contents of the 170.Ar filename 171argument, or 172.Dv NULL 173if an error occurred. 174If the 175.Ar filename 176is 177.Dv NULL , 178then stdin is used. 179.Pp 180The 181.Fn magic_descriptor 182function returns a textual description of the contents of the 183.Ar fd 184argument, or 185.Dv NULL 186if an error occurred. 187.Pp 188The 189.Fn magic_buffer 190function returns a textual description of the contents of the 191.Ar buffer 192argument with 193.Ar length 194bytes size. 195.Pp 196The 197.Fn magic_setflags 198function sets the 199.Ar flags 200described above. 201Note that using both MIME flags together can also 202return extra information on the charset. 203.Pp 204The 205.Fn magic_check 206function can be used to check the validity of entries in the colon 207separated database files passed in as 208.Ar filename , 209or 210.Dv NULL 211for the default database. 212It returns 0 on success and \-1 on failure. 213.Pp 214The 215.Fn magic_compile 216function can be used to compile the the colon 217separated list of database files passed in as 218.Ar filename , 219or 220.Dv NULL 221for the default database. 222It returns 0 on success and \-1 on failure. 223The compiled files created are named from the 224.Xr basename 1 225of each file argument with 226.Dq .mgc 227appended to it. 228.Pp 229The 230.Fn magic_list 231function dumps all magic entries in a human readable format, 232dumping first the entries that are matched against binary files and then the 233ones that match text files. 234It takes and optional 235.Fa filename 236argument which is a colon separated list of database files, or 237.Dv NULL 238for the default database. 239.Pp 240The 241.Fn magic_load 242function must be used to load the the colon 243separated list of database files passed in as 244.Ar filename , 245or 246.Dv NULL 247for the default database file before any magic queries can performed. 248.Pp 249The default database file is named by the MAGIC environment variable. 250If that variable is not set, the default database file name is 251.Pa /usr/share/misc/magic . 252.Fn magic_load 253adds 254.Dq .mgc 255to the database filename as appropriate. 256.Pp 257The 258.Fn magic_version 259command returns the version number of this library which is compiled into 260the shared library using the constant 261.Dv MAGIC_VERSION 262from 263.In magic.h . 264This can be used by client programs to verify that the version they compile 265against is the same as the version that they run against. 266.Sh RETURN VALUES 267The function 268.Fn magic_open 269returns a magic cookie on success and 270.Dv NULL 271on failure setting errno to an appropriate value. 272It will set errno to 273.Er EINVAL 274if an unsupported value for flags was given. 275The 276.Fn magic_list , 277.Fn magic_load , 278.Fn magic_compile , 279and 280.Fn magic_check 281functions return 0 on success and \-1 on failure. 282The 283.Fn magic_buffer , 284.Fn magic_getpath , 285and 286.Fn magic_file , 287functions return a string on success and 288.Dv NULL 289on failure. 290The 291.Fn magic_error 292function returns a textual description of the errors of the above 293functions, or 294.Dv NULL 295if there was no error. 296The 297.Fn magic_version 298always returns the version number of the library. 299Finally, 300.Fn magic_setflags 301returns \-1 on systems that don't support 302.Xr utime 3 , 303or 304.Xr utimes 2 305when 306.Dv MAGIC_PRESERVE_ATIME 307is set. 308.Sh FILES 309.Bl -tag -width /usr/share/misc/magic.mgc -compact 310.It Pa /usr/share/misc/magic 311The non-compiled default magic database. 312.It Pa /usr/share/misc/magic.mgc 313The compiled default magic database. 314.El 315.Sh SEE ALSO 316.Xr file 1 , 317.Xr magic 5 318.Sh AUTHORS 319.An M\(oans Rullg\(oard 320Initial libmagic implementation, and configuration. 321.An Christos Zoulas 322API cleanup, error code and allocation handling. 323