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