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