Bump liberty and termo

Lua detection functions used to cause fatal errors on failure to read.

We could also reconsider treating detection errors as fatal.

.clang-format

@@ -0,0 +1,32 @@
+# clang-format is fairly limited, and these rules are approximate:
+#  - array initializers can get terribly mangled with clang-format 12.0,
+#  - sometimes it still aligns with space characters,
+#  - struct name NL { NL ... NL } NL name; is unachievable.
+BasedOnStyle: GNU
+ColumnLimit: 80
+IndentWidth: 4
+TabWidth: 4
+UseTab: ForContinuationAndIndentation
+BreakBeforeBraces: Allman
+SpaceAfterCStyleCast: true
+AlignAfterOpenBracket: DontAlign
+AlignOperands: DontAlign
+AlignConsecutiveMacros: Consecutive
+AllowAllArgumentsOnNextLine: false
+AllowAllParametersOfDeclarationOnNextLine: false
+IndentGotoLabels: false
+
+# IncludeCategories has some potential, but it may also break the build.
+# Note that the documentation says the value should be "Never".
+SortIncludes: false
+
+# This is a compromise, it generally works out aesthetically better.
+BinPackArguments: false
+
+# Unfortunately, this can't be told to align to column 40 or so.
+SpacesBeforeTrailingComments: 2
+
+# liberty-specific macro body wrappers.
+MacroBlockBegin: "BLOCK_START"
+MacroBlockEnd: "BLOCK_END"
+ForEachMacros: ["LIST_FOR_EACH"]

.gitignore

@@ -7,3 +7,5 @@
 /hex.files
 /hex.creator*
 /hex.includes
+/hex.cflags
+/hex.cxxflags

CMakeLists.txt

@@ -1,21 +1,12 @@
-project (hex C)
-cmake_minimum_required (VERSION 2.8.5)
+cmake_minimum_required (VERSION 3.0...3.27)
+project (hex VERSION 0.1.0 LANGUAGES C)
 
 # Moar warnings
 if ("${CMAKE_C_COMPILER_ID}" MATCHES "GNU" OR CMAKE_COMPILER_IS_GNUCC)
-	set (wdisabled "-Wno-unused-function -Wno-implicit-fallthrough")
+	set (wdisabled "-Wno-unused-function")
 	set (CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -std=gnu99 -Wall -Wextra ${wdisabled}")
 endif ()
 
-# Version
-set (project_VERSION_MAJOR "0")
-set (project_VERSION_MINOR "1")
-set (project_VERSION_PATCH "0")
-
-set (project_VERSION "${project_VERSION_MAJOR}")
-set (project_VERSION "${project_VERSION}.${project_VERSION_MINOR}")
-set (project_VERSION "${project_VERSION}.${project_VERSION_PATCH}")
-
 # For custom modules
 set (CMAKE_MODULE_PATH ${PROJECT_SOURCE_DIR}/liberty/cmake)
 
@@ -29,29 +20,30 @@ include (AddThreads)
 find_package (Termo QUIET NO_MODULE)
 option (USE_SYSTEM_TERMO
 	"Don't compile our own termo library, use the system one" ${Termo_FOUND})
-
 if (USE_SYSTEM_TERMO)
 	if (NOT Termo_FOUND)
 		message (FATAL_ERROR "System termo library not found")
-	endif (NOT Termo_FOUND)
+	endif ()
 else ()
+	# We don't want the library to install, but EXCLUDE_FROM_ALL ignores tests
 	add_subdirectory (termo EXCLUDE_FROM_ALL)
-	# We don't have many good choices when we don't want to install it and want
-	# to support older versions of CMake; this is a relatively clean approach
-	# (other possibilities: setting a variable in the parent scope, using a
-	# cache variable, writing a special config file with build paths in it and
-	# including it here, or setting a custom property on the targets).
+	file (WRITE ${PROJECT_BINARY_DIR}/CTestCustom.cmake
+		"execute_process (COMMAND ${CMAKE_COMMAND} --build termo)")
+
+	# We don't have many good choices; this is a relatively clean approach
+	# (other possibilities: setting a variable in the parent scope, using
+	# a cache variable, writing a special config file with build paths in it
+	# and including it here, or setting a custom property on the targets)
 	get_directory_property (Termo_INCLUDE_DIRS
 		DIRECTORY termo INCLUDE_DIRECTORIES)
 	set (Termo_LIBRARIES termo-static)
 endif ()
 
-set (project_libraries ${UNISTRING_LIBRARIES}
-	${NCURSESW_LIBRARIES} termo-static)
+set (project_libraries ${Unistring_LIBRARIES}
+	${Ncursesw_LIBRARIES} ${Termo_LIBRARIES})
 
-pkg_search_module (lua lua53 lua5.3 lua-5.3 lua>=5.3)
+pkg_search_module (lua lua53 lua5.3 lua-5.3 lua54 lua5.4 lua-5.4 lua>=5.3)
 option (WITH_LUA "Enable support for Lua plugins" ${lua_FOUND})
-
 if (WITH_LUA)
 	if (NOT lua_FOUND)
 		message (FATAL_ERROR "Lua library not found")
@@ -60,28 +52,37 @@ if (WITH_LUA)
 	list (APPEND project_libraries ${lua_LIBRARIES})
 	include_directories (${lua_INCLUDE_DIRS})
 	link_directories (${lua_LIBRARY_DIRS})
-
-	include (CheckTypeSize)
-	set (CMAKE_REQUIRED_LIBRARIES ${lua_LIBRARIES})
-	set (CMAKE_REQUIRED_INCLUDES ${lua_INCLUDE_DIRS})
-	set (CMAKE_EXTRA_INCLUDE_FILES "lua.h")
-	CHECK_TYPE_SIZE (lua_Integer LUA_INTEGER)
-	if (NOT HAVE_LUA_INTEGER OR LUA_INTEGER LESS 8)
-		message (FATAL_ERROR "Lua must have at least 64-bit integers")
-	endif ()
 endif ()
 
-include_directories (${UNISTRING_INCLUDE_DIRS}
-	${NCURSESW_INCLUDE_DIRS} ${Termo_INCLUDE_DIRS})
+pkg_check_modules (x11 x11 xrender xft fontconfig libpng)
+option (WITH_X11 "Build with X11 support" ${x11_FOUND})
+if (WITH_X11)
+	if (NOT x11_FOUND)
+		message (FATAL_ERROR "Some X11 libraries were not found")
+	endif ()
+
+	list (APPEND project_libraries ${x11_LIBRARIES})
+	include_directories (${x11_INCLUDE_DIRS})
+	link_directories (${x11_LIBRARY_DIRS})
+endif ()
+
+include_directories (${Unistring_INCLUDE_DIRS}
+	${Ncursesw_INCLUDE_DIRS} ${Termo_INCLUDE_DIRS})
 
 # Configuration
+if ("${CMAKE_SYSTEM_NAME}" MATCHES "BSD")
+	# Need this for SIGWINCH in FreeBSD and OpenBSD respectively;
+	# our POSIX version macros make it undefined
+	add_definitions (-D__BSD_VISIBLE=1 -D_BSD_SOURCE=1)
+elseif (APPLE)
+	add_definitions (-D_DARWIN_C_SOURCE)
+endif ()
+
 include (CheckFunctionExists)
-set (CMAKE_REQUIRED_LIBRARIES ${NCURSESW_LIBRARIES})
+set (CMAKE_REQUIRED_LIBRARIES ${Ncursesw_LIBRARIES})
 CHECK_FUNCTION_EXISTS ("resizeterm" HAVE_RESIZETERM)
 
 # Generate a configuration file
-set (HAVE_LUA "${WITH_LUA}")
-
 configure_file (${PROJECT_SOURCE_DIR}/config.h.in
 	${PROJECT_BINARY_DIR}/config.h)
 include_directories (${PROJECT_SOURCE_DIR} ${PROJECT_BINARY_DIR})
@@ -95,21 +96,67 @@ add_threads (${PROJECT_NAME})
 include (GNUInstallDirs)
 install (TARGETS ${PROJECT_NAME} DESTINATION ${CMAKE_INSTALL_BINDIR})
 install (FILES LICENSE DESTINATION ${CMAKE_INSTALL_DOCDIR})
+if (WITH_LUA)
+	install (DIRECTORY plugins
+		DESTINATION ${CMAKE_INSTALL_DATADIR}/${PROJECT_NAME})
+endif ()
+if (WITH_X11)
+	include (IconUtils)
 
-# Generate documentation from program help
-find_program (HELP2MAN_EXECUTABLE help2man)
-if (NOT HELP2MAN_EXECUTABLE)
-	message (FATAL_ERROR "help2man not found")
+	set (icon_base ${PROJECT_BINARY_DIR}/icons)
+	set (icon_png_list)
+	foreach (icon_size 16 32 48)
+		icon_to_png (${PROJECT_NAME} ${PROJECT_SOURCE_DIR}/${PROJECT_NAME}.svg
+			${icon_size} ${icon_base} icon_png)
+		list (APPEND icon_png_list ${icon_png})
+	endforeach ()
+
+	add_custom_target (icons ALL DEPENDS ${icon_png_list})
+
+	install (FILES ${PROJECT_NAME}.svg
+		DESTINATION ${CMAKE_INSTALL_DATADIR}/icons/hicolor/scalable/apps)
+	install (DIRECTORY ${icon_base}
+		DESTINATION ${CMAKE_INSTALL_DATADIR})
+	install (FILES ${PROJECT_NAME}.desktop
+		DESTINATION ${CMAKE_INSTALL_DATADIR}/applications)
+endif ()
+
+# Generate documentation from text markup
+find_program (ASCIIDOCTOR_EXECUTABLE asciidoctor)
+find_program (A2X_EXECUTABLE a2x)
+if (NOT ASCIIDOCTOR_EXECUTABLE AND NOT A2X_EXECUTABLE)
+	message (WARNING "Neither asciidoctor nor a2x were found, "
+		"falling back to a substandard manual page generator")
 endif ()
 
 foreach (page ${PROJECT_NAME})
 	set (page_output "${PROJECT_BINARY_DIR}/${page}.1")
 	list (APPEND project_MAN_PAGES "${page_output}")
-	add_custom_command (OUTPUT ${page_output}
-		COMMAND ${HELP2MAN_EXECUTABLE} -N
-			"${PROJECT_BINARY_DIR}/${page}" -o ${page_output}
-		DEPENDS ${page}
-		COMMENT "Generating man page for ${page}" VERBATIM)
+	if (ASCIIDOCTOR_EXECUTABLE)
+		add_custom_command (OUTPUT ${page_output}
+			COMMAND ${ASCIIDOCTOR_EXECUTABLE} -b manpage
+				-a release-version=${PROJECT_VERSION}
+				-o "${page_output}"
+				"${PROJECT_SOURCE_DIR}/${page}.adoc"
+			DEPENDS ${page}.adoc
+			COMMENT "Generating man page for ${page}" VERBATIM)
+	elseif (A2X_EXECUTABLE)
+		add_custom_command (OUTPUT ${page_output}
+			COMMAND ${A2X_EXECUTABLE} --doctype manpage --format manpage
+				-a release-version=${PROJECT_VERSION}
+				-D "${PROJECT_BINARY_DIR}"
+				"${PROJECT_SOURCE_DIR}/${page}.adoc"
+			DEPENDS ${page}.adoc
+			COMMENT "Generating man page for ${page}" VERBATIM)
+	else ()
+		set (ASCIIMAN ${PROJECT_SOURCE_DIR}/liberty/tools/asciiman.awk)
+		add_custom_command (OUTPUT ${page_output}
+			COMMAND env LC_ALL=C asciidoc-release-version=${PROJECT_VERSION}
+				awk -f ${ASCIIMAN} "${PROJECT_SOURCE_DIR}/${page}.adoc"
+				> ${page_output}
+			DEPENDS ${page}.adoc ${ASCIIMAN}
+			COMMENT "Generating man page for ${page}" VERBATIM)
+	endif ()
 endforeach ()
 
 add_custom_target (docs ALL DEPENDS ${project_MAN_PAGES})
@@ -121,20 +168,17 @@ foreach (page ${project_MAN_PAGES})
 endforeach ()
 
 # CPack
-set (CPACK_PACKAGE_DESCRIPTION_SUMMARY "Hex viewer")
+set (CPACK_PACKAGE_DESCRIPTION_SUMMARY "Interpreting hex viewer")
 set (CPACK_PACKAGE_VENDOR "Premysl Eric Janouch")
 set (CPACK_PACKAGE_CONTACT "Přemysl Eric Janouch <p@janouch.name>")
 set (CPACK_RESOURCE_FILE_LICENSE "${PROJECT_SOURCE_DIR}/LICENSE")
-set (CPACK_PACKAGE_VERSION_MAJOR ${project_VERSION_MAJOR})
-set (CPACK_PACKAGE_VERSION_MINOR ${project_VERSION_MINOR})
-set (CPACK_PACKAGE_VERSION_PATCH ${project_VERSION_PATCH})
 set (CPACK_GENERATOR "TGZ;ZIP")
 set (CPACK_PACKAGE_FILE_NAME
-	"${PROJECT_NAME}-${project_VERSION}-${CMAKE_SYSTEM_NAME}-${CMAKE_SYSTEM_PROCESSOR}")
-set (CPACK_PACKAGE_INSTALL_DIRECTORY "${PROJECT_NAME}-${project_VERSION}")
+	"${PROJECT_NAME}-${PROJECT_VERSION}-${CMAKE_SYSTEM_NAME}-${CMAKE_SYSTEM_PROCESSOR}")
+set (CPACK_PACKAGE_INSTALL_DIRECTORY "${PROJECT_NAME}-${PROJECT_VERSION}")
 set (CPACK_SOURCE_GENERATOR "TGZ;ZIP")
 set (CPACK_SOURCE_IGNORE_FILES "/\\\\.git;/build;/CMakeLists.txt.user")
-set (CPACK_SOURCE_PACKAGE_FILE_NAME "${PROJECT_NAME}-${project_VERSION}")
+set (CPACK_SOURCE_PACKAGE_FILE_NAME "${PROJECT_NAME}-${PROJECT_VERSION}")
 
 set (CPACK_SET_DESTDIR TRUE)
 include (CPack)

LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2016 - 2017, Přemysl Eric Janouch <p@janouch.name>
+Copyright (c) 2016 - 2024, Přemysl Eric Janouch <p@janouch.name>
 
 Permission to use, copy, modify, and/or distribute this software for any
 purpose with or without fee is hereby granted.

README.adoc

@@ -3,7 +3,7 @@ hex
 
 'hex' is yet another hex viewer.  It automatically interprets fields within
 files using a set of Lua scripts, colorizing them and showing descriptions on
-the side.
+the side.  It also runs equally well in the terminal, or as an X11 client.
 
 At the moment there aren't that many features and we only have a few decoders.
 
@@ -11,14 +11,23 @@ image::hex.png[align="center"]
 
 Packages
 --------
-Regular releases are sporadic.  git master should be stable enough.  You can get
-a package with the latest development version from Archlinux's AUR.
+Regular releases are sporadic.  git master should be stable enough.
+You can get a package with the latest development version using Arch Linux's
+https://aur.archlinux.org/packages/hex-git[AUR],
+or as a https://git.janouch.name/p/nixexprs[Nix derivation].
+
+Documentation
+-------------
+See the link:hex.adoc[man page] for information about usage.
+The rest of this README will concern itself with externalities.
 
 Building and Running
 --------------------
-Build dependencies: CMake, pkg-config, help2man, liberty (included),
-                    termo (included) +
-Runtime dependencies: ncursesw, libunistring, Lua >= 5.3 (for highlighting)
+Build-only dependencies: CMake, pkg-config, awk, liberty (included),
+ termo (included), asciidoctor or asciidoc (recommended but optional),
+ rsvg-convert (X11) +
+Runtime dependencies: ncursesw, libunistring, Lua >= 5.3 (for highlighting) +
+Optional runtime dependencies: x11 + xft + libpng (X11)
 
  $ git clone --recursive https://git.janouch.name/p/hex.git
  $ mkdir hex/build
@@ -35,28 +44,9 @@ Or you can try telling CMake to make a package for you.  For Debian it is:
  $ cpack -G DEB
  # dpkg -i hex-*.deb
 
-Note that for versions of CMake before 2.8.9, you need to prefix `cpack` with
-`fakeroot` or file ownership will end up wrong.
-
 Having the program installed, optionally create a configuration file and run it
 on a file of your choice.
 
-Configuration
--------------
-Create _~/.config/hex/hex.conf_ with contents like the following:
-
-....
-colors = {
-	footer     = ""
-	footer_hl  = "bold"
-	bar        = "reverse"
-	bar_hl     = "reverse bold"
-	even       = ""
-	odd        = ""
-	selection  = "reverse"
-}
-....
-
 Terminal caveats
 ----------------
 Terminals are somewhat tricky to get consistent results on, so be aware of the
@@ -73,9 +63,13 @@ Since we need Lua 5.3 features (64-bit integers), LuaJIT can't help us here.
 
 Similar software
 ----------------
- * https://codisec.com/veles/ can also highlight files but it's not scriptable
- * https://bitbucket.org/haypo/hachoir/wiki/Home seems to be strictly
-   hierarchical, which may not work for file formats like ELF
+ * https://ide.kaitai.io/ and https://codisec.com/veles/ are essentially what
+   this project wanted to be but the description language is purely declarative
+ * https://github.com/wader/fq goes a step above, allowing transformations
+   of identified data
+ * https://hachoir.readthedocs.io/en/latest/ seems to be strictly hierarchical,
+   which may not work for file formats like ELF
+ * https://github.com/ruslashev/elfcat is a more interactive viewer for ELF
 
 Contributing and Support
 ------------------------

config.h.in

@@ -1,11 +1,12 @@
 #ifndef CONFIG_H
 #define CONFIG_H
 
-#define PROGRAM_NAME "${CMAKE_PROJECT_NAME}"
-#define PROGRAM_VERSION "${project_VERSION}"
+#define PROGRAM_NAME "${PROJECT_NAME}"
+#define PROGRAM_VERSION "${PROJECT_VERSION}"
 
 #cmakedefine HAVE_RESIZETERM
-#cmakedefine HAVE_LUA
+#cmakedefine WITH_LUA
+#cmakedefine WITH_X11
 
 #endif  // ! CONFIG_H
 

hex.adoc

@@ -0,0 +1,85 @@
+hex(1)
+======
+:doctype: manpage
+:manmanual: hex Manual
+:mansource: hex {release-version}
+
+Name
+----
+hex - Interpreting hex viewer
+
+Synopsis
+--------
+*hex* [_OPTION_]... [_PATH_]
+
+Description
+-----------
+*hex* is a hex viewer that uses Lua scripts to interpret fields within files,
+colorizes them, and shows their descriptions on the side.
+
+When run without arguments, it reads from its standard input stream.
+
+Options
+-------
+*-o*, *--offset* _OFFSET_::
+	Byte offset into the file.  All preceding data will be ignored.
+
+*-s*, *--size* _SIZE_::
+	Size limit in bytes.  Any following data will be ignored.
++
+The _SIZE_ argument accepts similar suffixes as in *dd*(1): _c_=1,
+_w_=2, _b_=512, _K_=1024, _KB_=1000, _M_=1024K, _MB_=1000KB,
+_G_=1024M, and _GB_=1000M.  The default value is 1G.
+
+*-t*, *--type* _TYPE_::
+	Force interpretation as the given type, skipping autodetection.
+	Pass in "list" for a listing of all available decoders.
+
+*-d*, *--debug*::
+	Run in debug mode.
+
+*-x*, *--x11*::
+	Use an X11 interface even when run from a terminal.
+	Note that the application may be built with this feature disabled.
+
+*-h*, *--help*::
+	Display a help message and exit.
+
+*-V*, *--version*::
+	Output version information and exit.
+
+Configuration
+-------------
+Create _~/.config/hex/hex.conf_ with contents like the following:
+
+....
+colors = {
+	footer     = ""
+	footer_hl  = "bold"
+	bar        = "reverse"
+	bar_hl     = "reverse bold"
+	even       = ""
+	odd        = ""
+	selection  = "reverse"
+}
+....
+
+Terminal attributes are accepted in a format similar to that of *git-config*(1),
+only named colours aren't supported.
+
+Files
+-----
+*hex* follows the XDG Base Directory Specification.
+
+_~/.config/hex/hex.conf_::
+	The configuration file.
+
+_~/.local/share/hex/plugins/_::
+_/usr/local/share/hex/plugins/_::
+_/usr/share/hex/plugins/_::
+	Plugins are loaded from these directories, in order.
+
+Reporting bugs
+--------------
+Use https://git.janouch.name/p/hex to report bugs, request features,
+or submit pull requests.

hex.desktop

@@ -0,0 +1,9 @@
+[Desktop Entry]
+Type=Application
+Name=hex
+GenericName=Interpreting hex viewer
+Icon=hex
+Exec=hex %f
+NoDisplay=true
+StartupNotify=false
+Categories=Utility;

hex.svg

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg version="1.0" width="48" height="48" viewBox="0 0 48 48"
+   xmlns="http://www.w3.org/2000/svg">
+  <g transform="translate(24 24) scale(2 2)">
+    <path d="M 0 0 -10 0 -10 -10 0 -10 Z" stroke-width="0" fill="#c6ffd6" />
+    <path d="M 0 0  10 0  10 -10 0 -10 Z" stroke-width="0" fill="#ffd8d8" />
+    <path d="M 0 0 -10 0 -10  10 0  10 Z" stroke-width="0" fill="#d8d8ff" />
+    <path d="M 0 0  10 0  10  10 0  10 Z" stroke-width="0" fill="#ffffac" />
+  </g>
+</svg>

plugins/elf.lua

@@ -18,7 +18,7 @@
 -- See man 5 elf, /usr/include/elf.h and /usr/include/llvm/Support/ELF.h
 
 local detect = function (c)
-	return c:read (4) == "\x7FELF"
+	return #c >= 4 and c:read (4) == "\x7FELF"
 end
 
 local ph_type_table = {
@@ -63,7 +63,7 @@ local decode_ph = function (elf, c)
 	ph.vaddr = elf.uwide (c, "virtual address: %#x")
 	ph.paddr = elf.uwide (c, "physical address: %#x")
 	ph.filesz = elf.uwide (c, "size in file: %d")
-	ph.memsz = elf.uwide (c, "sise in memory: %d")
+	ph.memsz = elf.uwide (c, "size in memory: %d")
 	if elf.class == 1 then ph.flags = c:u32 ("flags: %s", xform_ph_flags) end
 	ph.align = elf.uwide (c, "alignment: %d")
 	return ph

plugins/gzip.lua

@@ -16,7 +16,7 @@
 --
 
 local detect = function (c)
-	return c:read (2) == "\x1f\x8b"
+	return #c >= 2 and c:read (2) == "\x1f\x8b"
 end
 
 local function latin1_to_utf8 (s)

plugins/pcap.lua

@@ -16,11 +16,17 @@
 --
 
 local detect = function (c)
+	if #c < 4 then
+		return false
+	end
 	local magic = c:u32 ()
 	return magic == 0xa1b2c3d4 or magic == 0xd4c3b2a1
 end
 
 local detect_ng = function (c)
+	if #c < 8 then
+		return false
+	end
 	local magic = c (9):u32 ()
 	return c:u32 () == 0x0a0d0d0a
 		and (magic == 0x1a2b3c4d or magic == 0x4d3c2b1a)

plugins/pdf.lua

@@ -335,7 +335,7 @@ end
 -- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 
 local detect = function (c)
-	return c:read (5) == "%PDF-"
+	return #c >= 5 and c:read (5) == "%PDF-"
 end
 
 local decode_xref_subsection = function (lex, start, count, result)

plugins/vdi.lua

@@ -16,6 +16,9 @@
 --
 
 local detect = function (c)
+	if #c < 68 then
+		return false
+	end
 	c.position = 65
 	return c:read (4) == "\x7F\x10\xDA\xBE"
 end

plugins/xcursor.lua

@@ -0,0 +1,54 @@
+--
+-- xcursor.lua: X11 cursors
+--
+-- Copyright (c) 2021, Přemysl Eric Janouch <p@janouch.name>
+--
+-- Permission to use, copy, modify, and/or distribute this software for any
+-- purpose with or without fee is hereby granted.
+--
+-- THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+-- WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+-- MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
+-- SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+-- WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
+-- OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
+-- CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+--
+
+local detect = function (c)
+	return #c >= 4 and c:read (4) == "Xcur"
+end
+
+-- https://www.x.org/releases/current/doc/man/man3/Xcursor.3.xhtml
+local decode = function (c)
+	if not detect (c) then error ("not an Xcursor file") end
+
+	-- libXcursor shows that they are always little-endian
+	c (1, 4):mark ("Xcursor magic")
+	c.endianity = "le"
+
+	local size = c:u32 ("header size: %d")
+	-- TODO: check the version, although it is essentially set in stone
+	--   as 1.0, with X.org being a nearly abandoned project
+	local version = c:u32 ("file version: %s", function (u32)
+		return "%d.%d", u32 >> 16, u32 & 0xffff
+	end)
+	local ntoc = c:u32 ("number of ToC entries: %d")
+
+	local i
+	for i = 1, ntoc do
+		local start = c.position
+		local type = c:u32 ("entry type: %s", function (u32)
+			if u32 == 0xfffe0001 then return "comment" end
+			if u32 == 0xfffd0002 then return "image" end
+			return "unknown: %d", u32
+		end)
+		local subtype = c:u32 ("entry subtype: %d")
+		local position = c:u32 ("chunk position: %d")
+		c (start, c.position - 1):mark (("ToC entry %d"):format (i))
+	end
+
+	-- TODO: decode all entries as well
+end
+
+hex.register { type="xcursor", detect=detect, decode=decode }