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