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