diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Makefile.in | 22 | ||||
| -rw-r--r-- | doc/file.man | 74 | ||||
| -rw-r--r-- | doc/libmagic.man | 25 | ||||
| -rw-r--r-- | doc/magic.man | 45 |
4 files changed, 121 insertions, 45 deletions
diff --git a/doc/Makefile.in b/doc/Makefile.in index 8d0fa7b..165918a 100644 --- a/doc/Makefile.in +++ b/doc/Makefile.in @@ -1,7 +1,7 @@ -# Makefile.in generated by automake 1.14 from Makefile.am. +# Makefile.in generated by automake 1.15 from Makefile.am. # @configure_input@ -# Copyright (C) 1994-2013 Free Software Foundation, Inc. +# Copyright (C) 1994-2014 Free Software Foundation, Inc. # This Makefile.in is free software; the Free Software Foundation # gives unlimited permission to copy and/or distribute it, @@ -14,7 +14,17 @@ @SET_MAKE@ VPATH = @srcdir@ -am__is_gnu_make = test -n '$(MAKEFILE_LIST)' && test -n '$(MAKELEVEL)' +am__is_gnu_make = { \ + if test -z '$(MAKELEVEL)'; then \ + false; \ + elif test -n '$(MAKE_HOST)'; then \ + true; \ + elif test -n '$(MAKE_VERSION)' && test -n '$(CURDIR)'; then \ + true; \ + else \ + false; \ + fi; \ +} am__make_running_with_option = \ case $${target_option-} in \ ?) ;; \ @@ -77,7 +87,6 @@ POST_UNINSTALL = : build_triplet = @build@ host_triplet = @host@ subdir = doc -DIST_COMMON = $(srcdir)/Makefile.in $(srcdir)/Makefile.am ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 am__aclocal_m4_deps = $(top_srcdir)/m4/libtool.m4 \ $(top_srcdir)/m4/ltoptions.m4 $(top_srcdir)/m4/ltsugar.m4 \ @@ -85,6 +94,7 @@ am__aclocal_m4_deps = $(top_srcdir)/m4/libtool.m4 \ $(top_srcdir)/acinclude.m4 $(top_srcdir)/configure.ac am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \ $(ACLOCAL_M4) +DIST_COMMON = $(srcdir)/Makefile.am $(am__DIST_COMMON) mkinstalldirs = $(install_sh) -d CONFIG_HEADER = $(top_builddir)/config.h CONFIG_CLEAN_FILES = @@ -144,6 +154,7 @@ man5dir = $(mandir)/man5 NROFF = nroff MANS = $(man_MANS) am__tagged_files = $(HEADERS) $(SOURCES) $(TAGS_FILES) $(LISP) +am__DIST_COMMON = $(srcdir)/Makefile.in DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST) pkgdatadir = @pkgdatadir@ ACLOCAL = @ACLOCAL@ @@ -286,7 +297,6 @@ $(srcdir)/Makefile.in: $(srcdir)/Makefile.am $(am__configure_deps) echo ' cd $(top_srcdir) && $(AUTOMAKE) --foreign doc/Makefile'; \ $(am__cd) $(top_srcdir) && \ $(AUTOMAKE) --foreign doc/Makefile -.PRECIOUS: Makefile Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status @case '$?' in \ *config.status*) \ @@ -642,6 +652,8 @@ uninstall-man: uninstall-man1 uninstall-man3 uninstall-man4 \ tags-am uninstall uninstall-am uninstall-man uninstall-man1 \ uninstall-man3 uninstall-man4 uninstall-man5 +.PRECIOUS: Makefile + file.1: Makefile file.man @rm -f $@ diff --git a/doc/file.man b/doc/file.man index 64b8435..1c66241 100644 --- a/doc/file.man +++ b/doc/file.man @@ -1,5 +1,5 @@ -.\" $File: file.man,v 1.111 2014/12/16 23:18:40 christos Exp $ -.Dd December 16, 2014 +.\" $File: file.man,v 1.125 2017/01/03 11:24:46 christos Exp $ +.Dd October 19, 2016 .Dt FILE __CSECTION__ .Os .Sh NAME @@ -8,8 +8,9 @@ .Sh SYNOPSIS .Nm .Bk -words -.Op Fl bcEhiklLNnprsvz0 +.Op Fl bcdEhiklLNnprsvzZ0 .Op Fl Fl apple +.Op Fl Fl extension .Op Fl Fl mime-encoding .Op Fl Fl mime-type .Op Fl e Ar testname @@ -180,6 +181,8 @@ Cause a checking printout of the parsed form of the magic file. This is usually used in conjunction with the .Fl m flag to debug a new magic file before installing it. +.It Fl d +Prints internal debugging information to stderr. .It Fl E On filesystem errors (file not found etc), instead of handling the error as regular output as POSIX mandates and keep going, issue an error message @@ -207,12 +210,18 @@ Prints details of Compound Document Files. .It compress Checks for, and looks inside, compressed files. .It elf -Prints ELF file details. +Prints ELF file details, provided soft magic tests are enabled and the +elf magic is found. .It soft Consults magic files. .It tar Examines tar files. +.It text +A synonym for +.Sq ascii . .El +.It Fl Fl extension +Print a slash-separated list of valid extensions for the file type found. .It Fl F , Fl Fl separator Ar separator Use the specified string as the separator between the filename and the file result returned. @@ -229,8 +238,8 @@ or at least one filename argument must be present; to test the standard input, use .Sq - as a filename argument. -Please note that -.Ar namefile +Please note that +.Ar namefile is unwrapped and the enclosed filenames are processed when this option is encountered and before any further options processing is done. This allows one to process multiple lists of files with different command line @@ -306,13 +315,15 @@ attempt to preserve the access time of files analyzed, to pretend that never read them. .It Fl P , Fl Fl parameter Ar name=value Set various parameter limits. -.Bl -column "elf_phnum" "Default" "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" -offset indent +.Bl -column "elf_phnum" "Default" "XXXXXXXXXXXXXXXXXXXXXXXXXXX" -offset indent .It Sy "Name" Ta Sy "Default" Ta Sy "Explanation" .It Li indir Ta 15 Ta recursion limit for indirect magic .It Li name Ta 30 Ta use count limit for name/use magic .It Li elf_notes Ta 256 Ta max ELF notes processed .It Li elf_phnum Ta 128 Ta max ELF program sections processed .It Li elf_shnum Ta 32768 Ta max ELF sections processed +.It Li regex Ta 8192 Ta length limit for regex searches +.It Li bytes Ta 1048576 Ta max number of bytes to read from file .El .It Fl r , Fl Fl raw Don't translate unprintable characters to \eooo. @@ -343,6 +354,9 @@ since on some systems it reports a zero size for raw disk partitions. Print the version of the program and exit. .It Fl z , Fl Fl uncompress Try to look inside compressed files. +.It Fl Z , Fl Fl uncompress-noreport +Try to look inside compressed files, but report information about the contents +only not the compression. .It Fl 0 , Fl Fl print0 Output a null character .Sq \e0 @@ -351,6 +365,11 @@ Nice to .Xr cut 1 the output. This does not affect the separator, which is still printed. +.Pp +If this option is repeated more than once, then +.Nm +prints just the filename followed by a NUL followed by the description +(or ERROR: text) followed by a second NUL for each entry. .It Fl -help Print a help message and exit. .El @@ -392,10 +411,10 @@ and .Fl h options. .Sh SEE ALSO -.Xr magic __FSECTION__ , .Xr hexdump 1 , .Xr od 1 , .Xr strings 1 , +.Xr magic __FSECTION__ .Sh STANDARDS CONFORMANCE This program is believed to exceed the System V Interface Definition of FILE(CMD), as near as one can determine from the vague language @@ -511,16 +530,15 @@ John Gilmore revised the code extensively, making it better than the first version. Geoff Collyer found several inadequacies and provided some magic file entries. -Contributions by the +Contributions of the .Sq \*[Am] operator by Rob McMahon, .Aq cudcv@warwick.ac.uk , 1989. .Pp -Guy Harris, +Guy Harris, .Aq guy@netapp.com , made many changes from 1993 to the present. -1989. .Pp Primary development and maintenance from 1990 to the present by Christos Zoulas @@ -568,7 +586,6 @@ program, and are not covered by the above license. .Nm returns 0 on success, and non-zero on error. .Sh BUGS -.Pp Please report bugs and send patches to the bug tracker at .Pa http://bugs.gw.com/ or the mailing list at @@ -577,7 +594,6 @@ or the mailing list at .Pa http://mx.gw.com/mailman/listinfo/file first to subscribe). .Sh TODO -.Pp Fix output so that tests for MIME and APPLE flags are not needed all over the place, and actual output is only done in one place. This needs a design. @@ -586,20 +602,30 @@ last-pushed (most specific, one hopes) value at the end, or use a default if the list is empty. This should not slow down evaluation. .Pp +The handling of +.Dv MAGIC_CONTINUE +and printing \e012- between entries is clumsy and complicated; refactor +and centralize. +.Pp +Some of the encoding logic is hard-coded in encoding.c and can be moved +to the magic files if we had a !:charset annotation +.Pp Continue to squash all magic bugs. See Debian BTS for a good source. .Pp Store arbitrarily long strings, for example for %s patterns, so that they can be printed out. Fixes Debian bug #271672. -Would require more complex store/load code in apprentice. +This can be done by allocating strings in a string pool, storing the +string pool at the end of the magic file and converting all the string +pointers to relative offsets from the string pool. .Pp Add syntax for relative offsets after current level (Debian bug #466037). .Pp Make file -ki work, i.e. give multiple MIME types. .Pp Add a zip library so we can peek inside Office2007 documents to -figure out what they are. +print more details about their contents. .Pp Add an option to print URLs for the sources of the file descriptions. .Pp @@ -609,23 +635,35 @@ string to be looked up in a table). This would avoid adding the same magic repeatedly for each new hash-bang interpreter. .Pp +When a file descriptor is available, we can skip and adjust the buffer +instead of the hacky buffer management we do now. +.Pp Fix .Dq name and .Dq use -to check for consistency at compile time (duplicate +to check for consistency at compile time (duplicate .Dq name , .Dq use pointing to undefined .Dq name ). -Make +Make .Dq name / -.Dq use +.Dq use more efficient by keeping a sorted list of names. Special-case ^ to flip endianness in the parser so that it does not have to be escaped, and document it. +.Pp +If the offsets specified internally in the file exceed the buffer size +( +.Dv HOWMANY +variable in file.h), then we don't seek to that offset, but we give up. +It would be better if buffer managements was done when the file descriptor +is available so move around the file. +One must be careful though because this has performance (and thus security +considerations). .Sh AVAILABILITY You can obtain the original author's latest version by anonymous FTP on diff --git a/doc/libmagic.man b/doc/libmagic.man index 3c907ca..4c7e42f 100644 --- a/doc/libmagic.man +++ b/doc/libmagic.man @@ -1,4 +1,4 @@ -.\" $File: libmagic.man,v 1.34 2014/12/16 23:18:40 christos Exp $ +.\" $File: libmagic.man,v 1.41 2017/05/23 21:54:07 christos Exp $ .\" .\" Copyright (c) Christos Zoulas 2003. .\" All Rights Reserved. @@ -25,7 +25,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd December 16, 2014 +.Dd May 23, 2017 .Dt LIBMAGIC 3 .Os .Sh NAME @@ -35,6 +35,7 @@ .Nm magic_errno , .Nm magic_descriptor , .Nm magic_buffer , +.Nm magic_getflags , .Nm magic_setflags , .Nm magic_check , .Nm magic_compile , @@ -64,6 +65,8 @@ .Ft const char * .Fn magic_buffer "magic_t cookie" "const void *buffer" "size_t length" .Ft int +.Fn magic_getflags "magic_t cookie" +.Ft int .Fn magic_setflags "magic_t cookie" "int flags" .Ft int .Fn magic_check "magic_t cookie" "const char *filename" @@ -132,6 +135,10 @@ Treat operating system errors while trying to open files and follow symlinks as real errors, instead of printing them in the magic buffer. .It Dv MAGIC_APPLE Return the Apple creator and type. +.It Dv MAGIC_EXTENSION +Return a slash-separated list of extensions for this file type. +.It Dv MAGIC_COMPRESS_TRANSP +Don't report on compression, only report about the uncompressed data. .It Dv MAGIC_NO_CHECK_APPTYPE Don't check for .Dv EMX @@ -202,6 +209,12 @@ argument with bytes size. .Pp The +.Fn magic_getflags +functions returns a value representing current +.Ar flags +set. +.Pp +The .Fn magic_setflags function sets the .Ar flags @@ -221,7 +234,7 @@ It returns 0 on success and \-1 on failure. .Pp The .Fn magic_compile -function can be used to compile the the colon +function can be used to compile the colon separated list of database files passed in as .Ar filename , or @@ -247,7 +260,7 @@ for the default database. .Pp The .Fn magic_load -function must be used to load the the colon +function must be used to load the colon separated list of database files passed in as .Ar filename , or @@ -278,7 +291,7 @@ The .Fn magic_getparam and .Fn magic_setparam -allow getting and setting various limits related to the the magic +allow getting and setting various limits related to the magic library. .Bl -column "MAGIC_PARAM_ELF_PHNUM_MAX" "size_t" "Default" -offset indent .It Sy "Parameter" Ta Sy "Type" Ta Sy "Default" @@ -287,6 +300,8 @@ library. .It Li MAGIC_PARAM_ELF_NOTES_MAX Ta size_t Ta 256 .It Li MAGIC_PARAM_ELF_PHNUM_MAX Ta size_t Ta 128 .It Li MAGIC_PARAM_ELF_SHNUM_MAX Ta size_t Ta 32768 +.It Li MAGIC_PARAM_REGEX_MAX Ta size_t Ta 8192 +.It Li MAGIC_PARAM_BYTES_MAX Ta size_t Ta 1048576 .El .Pp The diff --git a/doc/magic.man b/doc/magic.man index b6523f2..4c69bca 100644 --- a/doc/magic.man +++ b/doc/magic.man @@ -1,5 +1,5 @@ -.\" $File: magic.man,v 1.85 2015/01/01 17:07:34 christos Exp $ -.Dd January 1, 2015 +.\" $File: magic.man,v 1.91 2017/02/12 15:30:08 christos Exp $ +.Dd February 12, 2017 .Dt MAGIC __FSECTION__ .Os .\" install as magic.4 on USG, magic.5 on V7, Berkeley and Linux systems. @@ -7,7 +7,7 @@ .Nm magic .Nd file command's magic pattern file .Sh DESCRIPTION -This manual page documents the format of the magic file as +This manual page documents the format of magic files as used by the .Xr file __CSECTION__ command, version __VERSION__. @@ -17,13 +17,19 @@ command identifies the type of a file using, among other tests, a test for whether the file contains certain .Dq "magic patterns" . -The file -.Pa __MAGIC__ -specifies what patterns are to be tested for, what message or +The database of these +.Dq "magic patterns" +is usually located in a binary file in +.Pa __MAGIC__.mgc +or a directory of source text magic pattern fragment files in +.Pa __MAGIC__ . +The database specifies what patterns are to be tested for, what message or MIME type to print if a particular pattern is found, and additional information to extract from the file. .Pp -Each line of the file specifies a test to be performed. +The format of the source fragment files that are used to build this database +is as follows: +Each line of a fragment file specifies a test to be performed. A test compares the data starting at a particular offset in the file with a byte value, a string or a numeric value. If the test succeeds, a message is printed. @@ -98,13 +104,13 @@ The following modifiers are supported: .It B A byte length (default). .It H -A 2 byte big endian length. +A 4 byte big endian length. .It h -A 2 byte big little length. +A 2 byte big endian length. .It L -A 4 byte big endian length. +A 4 byte little endian length. .It l -A 4 byte big little length. +A 2 byte little endian length. .It J The length includes itself in its count. .El @@ -200,7 +206,7 @@ interpreted as a UNIX-style date, but interpreted as local time rather than UTC. .It Dv indirect Starting at the given offset, consult the magic database again. -The offset of th +The offset of the .Dv indirect magic is by default absolute in the file, but one can specify .Dv /r @@ -535,13 +541,18 @@ the file. The value at that offset is read, and is used again as an offset in the file. Indirect offsets are of the form: -.Em (( x [.[bislBISL]][+\-][ y ]) . +.Em (( x [[.,][bislBISL]][+\-][ y ]) . The value of .Em x is used as an offset in the file. A byte, id3 length, short or long is read at that offset depending on the .Em [bislBISLm] type specifier. +The value is treated as signed if +.Dq , +is specified or unsigned if +.Dq . +is specified. The capitalized types interpret the number as a big endian value, whereas the small letter versions interpret the number as a little endian value; @@ -564,9 +575,9 @@ That way variable length structures can be examined: \*[Gt]\*[Gt](0x3c.l) string LX\e0\e0 LX executable (OS/2) .Ed .Pp -This strategy of examining has a drawback: You must make sure that -you eventually print something, or users may get empty output (like, when -there is neither PE\e0\e0 nor LE\e0\e0 in the above example) +This strategy of examining has a drawback: you must make sure that you +eventually print something, or users may get empty output (such as when +there is neither PE\e0\e0 nor LE\e0\e0 in the above example). .Pp If this indirect offset cannot be used directly, simple calculations are possible: appending @@ -646,7 +657,7 @@ start of the main indirect offset. \*[Gt]\*[Gt]\*[Gt]\*[Gt](\*[Am]0xe.l+(-4)) string PK\e3\e4 \eb, ZIP self-extracting archive .Ed .Pp -If you have a list of known avalues at a particular continuation level, +If you have a list of known values at a particular continuation level, and you want to provide a switch-like default case: .Bd -literal -offset indent # clear that continuation level match |