contrib/file/doc/libmagic.man

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