diff options
Diffstat (limited to 'libmagic.man')
| -rw-r--r-- | libmagic.man | 140 |
1 files changed, 89 insertions, 51 deletions
diff --git a/libmagic.man b/libmagic.man index e39a61053ced..2f218db2216c 100644 --- a/libmagic.man +++ b/libmagic.man @@ -1,4 +1,4 @@ -.\" $File: libmagic.man,v 1.19 2008/10/06 20:16:04 christos Exp $ +.\" $File: libmagic.man,v 1.24 2011/05/13 22:11:44 christos Exp $ .\" .\" Copyright (c) Christos Zoulas 2003. .\" All Rights Reserved. @@ -12,7 +12,7 @@ .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. -.\" +.\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE @@ -25,20 +25,20 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd October 6, 2008 -.Dt MAGIC 3 +.Dd January 14, 2011 +.Dt LIBMAGIC 3 .Os .Sh NAME .Nm magic_open , .Nm magic_close , .Nm magic_error , -.Nm magic_file , +.Nm magic_descriptor , .Nm magic_buffer , .Nm magic_setflags , .Nm magic_check , .Nm magic_compile , .Nm magic_load -.Nd Magic number recognition library. +.Nd Magic number recognition library .Sh LIBRARY .Lb libmagic .Sh SYNOPSIS @@ -52,17 +52,19 @@ .Ft int .Fn magic_errno "magic_t cookie" .Ft const char * +.Fn magic_descriptor "magic_t cookie, "int fd" +.Ft const char * .Fn magic_file "magic_t cookie, const char *filename" .Ft const char * -.Fn magic_buffer "magic_t cookie, const void *buffer, size_t length" +.Fn magic_buffer "magic_t cookie" "const void *buffer" "size_t length" .Ft int -.Fn magic_setflags "magic_t cookie, int flags" +.Fn magic_setflags "magic_t cookie" "int flags" .Ft int -.Fn magic_check "magic_t cookie, const char *filename" +.Fn magic_check "magic_t cookie" "const char *filename" .Ft int -.Fn magic_compile "magic_t cookie, const char *filename" +.Fn magic_compile "magic_t cookie" "const char *filename" .Ft int -.Fn magic_load "magic_t cookie, const char *filename" +.Fn magic_load "magic_t cookie" "const char *filename" .Sh DESCRIPTION These functions operate on the magic database file @@ -72,8 +74,11 @@ in .Pp The function .Fn magic_open -creates a magic cookie pointer and returns it. It returns NULL if -there was an error allocating the magic cookie. The +creates a magic cookie pointer and returns it. +It returns +.Dv NULL +if there was an error allocating the magic cookie. +The .Ar flags argument specifies how the other magic functions should behave: .Bl -tag -width MAGIC_COMPRESS @@ -92,41 +97,45 @@ and try to look in its contents. Return a MIME type string, instead of a textual description. .It Dv MAGIC_MIME_ENCODING Return a MIME encoding, instead of a textual description. +.It Dv MAGIC_MIME +A shorthand for MAGIC_MIME_TYPE | MAGIC_MIME_ENCODING. .It Dv MAGIC_CONTINUE Return all matches, not just the first. .It Dv MAGIC_CHECK Check the magic database for consistency and print warnings to stderr. .It Dv MAGIC_PRESERVE_ATIME On systems that support -.Xr utime 2 +.Xr utime 3 or .Xr utimes 2 , -attempt to preserve the access time of files analyzed. +attempt to preserve the access time of files analysed. .It Dv MAGIC_RAW Don't translate unprintable characters to a \eooo octal representation. .It Dv MAGIC_ERROR 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_NO_CHECK_APPTYPE -Check for +Don't check for .Dv EMX application type (only on EMX). -.It Dv MAGIC_NO_CHECK_ASCII -Check for various types of ascii files. +.It Dv MAGIC_NO_CHECK_CDF +Don't get extra information on MS Composite Document Files. .It Dv MAGIC_NO_CHECK_COMPRESS -Don't look for, or inside compressed files. +Don't look inside compressed files. .It Dv MAGIC_NO_CHECK_ELF -Don't print elf details. -.It Dv MAGIC_NO_CHECK_FORTRAN -Don't look for fortran sequences inside ascii files. +Don't print ELF details. +.It Dv NO_CHECK_ENCODING +Don't check text encodings. .It Dv MAGIC_NO_CHECK_SOFT Don't consult magic files. .It Dv MAGIC_NO_CHECK_TAR Don't examine tar files. +.It Dv MAGIC_NO_CHECK_TEXT +Don't check for various types of text files. .It Dv MAGIC_NO_CHECK_TOKENS Don't look for known tokens inside ascii files. -.It Dv MAGIC_NO_CHECK_TROFF -Don't look for troff sequences inside ascii files. .El .Pp The @@ -137,8 +146,9 @@ database and deallocates any resources used. .Pp The .Fn magic_error -function returns a textual explanation of the last error, or NULL if there was -no error. +function returns a textual explanation of the last error, or +.Dv NULL +if there was no error. .Pp The .Fn magic_errno @@ -150,10 +160,22 @@ The .Fn magic_file function returns a textual description of the contents of the .Ar filename -argument, or NULL if an error occurred. +argument, or +.Dv NULL +if an error occurred. If the .Ar filename -is NULL, then stdin is used. +is +.Dv NULL , +then stdin is used. +.Pp +The +.Fn magic_descriptor +function returns a textual description of the contents of the +.Ar fd +argument, or +.Dv NULL +if an error occurred. .Pp The .Fn magic_buffer @@ -165,9 +187,10 @@ bytes size. .Pp The .Fn magic_setflags -function sets the +function sets the .Ar flags -described above. Note that using both MIME flags together can also +described above. +Note that using both MIME flags together can also return extra information on the charset. .Pp The @@ -175,16 +198,21 @@ The function can be used to check the validity of entries in the colon separated database files passed in as .Ar filename , -or NULL for the default database. It returns 0 on success and -1 on -failure. +or +.Dv NULL +for the default database. +It returns 0 on success and \-1 on failure. .Pp The .Fn magic_compile function can be used to compile the the colon separated list of database files passed in as .Ar filename , -or NULL for the default database. It returns 0 on success and -1 on -failure. The compiled files created are named from the +or +.Dv NULL +for the default database. +It returns 0 on success and \-1 on failure. +The compiled files created are named from the .Xr basename 1 of each file argument with .Dq .mgc @@ -195,11 +223,12 @@ The function must be used to load the the colon separated list of database files passed in as .Ar filename , -or NULL for the default database file -before any magic queries can performed. +or +.Dv NULL +for the default database file before any magic queries can performed. .Pp -The default database file is named by the MAGIC environment variable. If -that variable is not set, the default database file name is __MAGIC__. +The default database file is named by the MAGIC environment variable. +If that variable is not set, the default database file name is __MAGIC__. .Fn magic_load adds .Dq .mgc @@ -207,27 +236,35 @@ to the database filename as appropriate. .Sh RETURN VALUES The function .Fn magic_open -returns a magic cookie on success and NULL on failure setting errno to -an appropriate value. It will set errno to EINVAL if an unsupported -value for flags was given. +returns a magic cookie on success and +.Dv NULL +on failure setting errno to an appropriate value. +It will set errno to +.Er EINVAL +if an unsupported value for flags was given. The .Fn magic_load , .Fn magic_compile , and .Fn magic_check -functions return 0 on success and -1 on failure. +functions return 0 on success and \-1 on failure. The .Fn magic_file , and -.Fn magic_buffer -functions return a string on success and NULL on failure. The +.Fn magic_buffer +functions return a string on success and +.Dv NULL +on failure. +The .Fn magic_error function returns a textual description of the errors of the above -functions, or NULL if there was no error. +functions, or +.Dv NULL +if there was no error. Finally, .Fn magic_setflags -returns -1 on systems that don't support -.Xr utime 2 , +returns \-1 on systems that don't support +.Xr utime 3 , or .Xr utimes 2 when @@ -242,8 +279,9 @@ The compiled default magic database. .El .Sh SEE ALSO .Xr file __CSECTION__ , -.Xr magic __FSECTION__ +.Xr magic __FSECTION__ .Sh AUTHORS -Måns Rullgård Initial libmagic implementation, -and configuration. -Christos Zoulas API cleanup, error code and allocation handling. +.An M\(oans Rullg\(oard +Initial libmagic implementation, and configuration. +.An Christos Zoulas +API cleanup, error code and allocation handling. |