The Sleuth Kit  4.11.1
Library Basics

This page describes some of the basic concepts of the TSK library. It is assumed that you have built and installed the TSK library based on either the instructions in the INSTALL.txt file or via a package. Refer to the files in the samples directory for examples on the topics in this and later sections.


TSK is organized into several layers (and sub-layers). These layers represent layers of abstraction that are used with data storage. The User's Guide and API Reference are organized based on these layers.

The lowest layer that TSK has is the Base Layer, which contains common programming and data structure functions that can be applied to all layers. This is where error handling, types, and convenience functions are defined.

The next layer up is the Disk Image Layer, which allows disk images in various formats to be opened and processed. This layer hides the details associated with split, compressed, and encrypted image files from the other layers. All disk images must be first opened by the Disk Image Layer functions before they can be processed by other layers.

The next layer up is the Volume System Layer. This layer focuses on processing data as a volume system, such as DOS partition tables or BSD disk label structures. If the disk image being analyzed has a volume system on it, then this set of functions will tell you starting and ending location of its partitions.

The next layer up is the File System Layer. This layer focuses on processing data as a file system, such as FAT or NTFS. File systems can be located in a partition or can be the full disk image file. These set of functions allow you to read arbitrary data from the file system, list files, and open files. There are several sub-layers in the File System Layer and they are described in File System Layers.

There is an independent Hash Database Layer that handles hash databases, such as NSRL and md5sum outputs. This API allows you to create an index of hashes and perform fast lookups of them. These functions do not depend on the Disk Image, Volume System, or File System Layers.

There is also an Automation Layer that integrates all of the previous layers in an automated fashion. It defines a C++ class named TskAuto that hides a lot of the details about analyzing file and volume systems.

A basic diagram of the relationship between these layers is shown here. Note that if a disk image file does not have a volume system, then we can use the File System Layer functions directly on it.

 |                                                          | 
 |                       +================+                 |
 |                       |      Base      |                 |
 |                       +================+                 |
 |                         /            \                   |
 |                        /              \                  |
 |              +==============+      +==================+  |
 |              |  Disk Image  |      |   Hash Database  |  |
 |              +==============+      +==================+  |
 |                 /       |                                |
 |                /        |                                |
 |   +===============+     |                                |
 |   | Volume System |     |                                |
 |   +===============+     |                                |
 |               \         |                                |
 |                \        |                                |
 |               +===============+                          |
 |               |  File System  |                          |
 |               +===============+                          |
 |                                                          |
 |                                                          |
 |                        Automation                        |

Build Environment

This section describes how to incorporate the TSK library into your application. In general, all you need to do is include a TSK header file and link in the library.


This document assumes that you used 'make install' to install the library and header files and that you used the default location of /usr/local/. If you specified a different location, you will need to do the obvious path replacements in this document.

To include the API definitions, you will need to include the tsk/libtsk.h file in your source code. Depending on system configuration, you may need to add /usr/local/include to the list of directories that your compiler looks in for header files (using -I for example).

#include <tsk/libtsk.h>

To include the library in your application during the linking phase, you will need to add -ltsk to add the libtsk library. Depending on system configuration, you may need to add /usr/local/lib/ to the list of directories that your compiler looks in for libraries (using -L for example).

Note that if you built TSK with support for AFFLIB and libewf then you will also need to include -lewf and/or -lafflib. You may also need to include other libraries that AFFLIB and libewf require (my current system requires -lcrypto -lssl -lz -lncurses -lreadlin). Refer to the libewf and AFFLIB documentation for details.


The Windows setup is similar to the Unix setup, except that you need to include more libraries and there is no automated install or build process.

The Visual Studio solution file is located in win32/tsk-win.sln. There is a libtsk project for the five library layers (as described in Layers). Build this to create a static library in the Debug, Release, or Debug_NoLibs folder (depending on which version you built). The Debug_NoLibs configuration does not have any dependencies on libewf or afflib.

To include the header files, configure your build environment to search in the root TSK directory (i.e. sleuthkit-3.0.0) and include the tsk/libtsk.h file in your source code. The location of the TSK directory will depend on where you unpacked it.

To link with the libraries, you must configure your environment to include the libtsk library. You will need to specify the directory where the library is located, which could be the Debug or Release subdirectories in the win32 directory. You can also move the library to a different location.

Note that your Windows application must have UNICODE support enabled.

C++ Wrapers

Nearly all of the TSK code is written in C and the original API is a collection of C functions and structs. There are also C++ classes that are wrappers around the C code. The C++ class allocates the C structs and provides getter and setter methods to access the public data. The remainder of this doc primarily refers to the C functions, but will provide a link to the corresponding C++ class when one exists.

Next to Base Functions

Back to Table of Contents

Copyright © 2007-2020 Brian Carrier. (carrier -at- sleuthkit -dot- org)
This work is licensed under a Creative Commons Attribution-Share Alike 3.0 United States License.