What You Will Learn

Prerequisites

The Kernel Task List: How Linux Knows About Every Process

When the Linux kernel boots, one of the very first things it creates is a process — process number 1, known as init (or systemd on modern distros). From that moment on, every single process and thread that ever runs on the system gets registered in a global doubly-linked circular list maintained by the kernel. This is called the task list.

Each entry in this list is a structure of type task_struct. Think of task_struct as the kernel’s “file” on a running entity. It stores everything the kernel needs to know: the process ID, scheduling information, memory mappings, open file descriptors, signal handlers, the kernel-mode stack address, the thread’s name, and much more.

The important thing to understand early is that in Linux, both processes and threads are represented by a task_struct. There is no separate “thread descriptor.” A process with four threads will have four task_struct instances in the task list. The kernel distinguishes threads from standalone processes using the TGID field, explained below.

The Special Case: the CPU Idle Thread

Every CPU core has one very special thread that runs when there is absolutely nothing else to do: the idle thread, named swapper/N where N is the CPU core number. Core 0’s idle thread is called swapper/0, core 1’s is swapper/1, and so on.

The idle thread is anchored by a global variable called init_task which is always exported by the kernel. This is why, when you write a kernel module that walks the task list, you can always rely on init_task as a known starting point. The idle thread does not show up in ps or top in normal usage, but it absolutely exists and runs at the lowest scheduling priority.

PID vs TGID: Understanding Linux Threading at the Kernel Level

This is a concept that trips up many people learning Linux kernel internals for the first time, so let’s be very clear about it.

When you call pthread_create() from a C program to spawn a new thread, the kernel actually creates a new task_struct for that thread. From the kernel’s point of view, this new thread is almost like a new process — it gets its own unique PID (Process ID). However, all threads that belong to the same process share the same TGID (Thread Group ID).

This is a very important insight: when you call getpid() from a user-space thread, the C library returns the TGID, not the kernel-level PID. This is by design — POSIX defines that all threads in a process should share the same process ID from the user’s perspective.

Kernel Threads vs User-Space Threads: How to Tell the Difference

The kernel itself runs many background threads to handle work like flushing dirty pages to disk, managing software RAID, processing network packets, and running workqueues. These are called kernel threads. You can see them in ps aux output — they are the ones with names wrapped in square brackets like [kworker/0:0], [kswapd0], and [migration/0].

From inside a kernel module, distinguishing a kernel thread from a user-space thread is straightforward: look at the mm pointer inside task_struct. This pointer refers to the memory map of the process — all its virtual address space regions. For a user-space process, this will always be a valid (non-NULL) pointer. For a kernel thread, it will be NULL because kernel threads live entirely in kernel address space and do not have a separate user-space memory map.

Displaying Thread Names from a Kernel Module

Every task_struct has a field called comm which holds the short name of the thread (up to 15 characters plus a null terminator). For user-space tasks this is typically the executable name. For kernel threads it is the kernel thread function name.

You might wonder: “Why not use the get_task_comm() helper function?” The reason is a real-world pitfall — get_task_comm() acquires a task lock internally, and if you are already holding that lock (which you would be inside the thread-walking loop), calling it again will cause a deadlock. The safe approach inside the iteration loop is to read t->comm directly after acquiring the lock yourself with task_lock().

Walking Every Thread in the Linux Kernel: do_each_thread and while_each_thread

Now we reach the practical core of this lecture in our free Linux kernel development course. How do you actually iterate over every living thread from inside a kernel module?

The Linux kernel provides a pair of macros specifically for this purpose: do_each_thread(g, t) and while_each_thread(g, t). These form a nested loop construct. You declare two task_struct pointers — by convention called g (for “group leader” / process) and t (for thread) — and these macros drive the iteration.

The outer pointer g walks through the process group leaders (one per process). The inner pointer t walks through all the individual threads belonging to that process. Together, they enumerate every single thread on the entire system.

Setting Up the Required Headers

Before writing the module code, you need to include the right headers. The kernel’s scheduling and task-struct definitions have been reorganized across kernel versions. Here is how to handle it correctly for both older and modern kernels:

#include <linux/module.h>
#include <linux/kernel.h>
#include <linux/init.h>
#include <linux/sched.h>       /* task_struct, current */
#include <linux/version.h>     /* LINUX_VERSION_CODE */

#if LINUX_VERSION_CODE > KERNEL_VERSION(4, 10, 0)
#include <linux/sched/signal.h>  /* do_each_thread, while_each_thread */
#endif

The conditional include is necessary because the kernel moved several scheduling-related declarations to linux/sched/signal.h in version 4.11. On kernels 4.10 and older, linux/sched.h alone was enough. On anything newer (which is almost everything you will work with today, given that 6.x is the current LTS series), you need both.

Writing the Thread-Walking Function

Here is a clean, well-commented function that walks the entire task list and prints information about every thread it finds. This is original code for learning purposes — it demonstrates the concepts clearly:

#include <linux/module.h>
#include <linux/kernel.h>
#include <linux/init.h>
#include <linux/sched.h>
#include <linux/version.h>
#if LINUX_VERSION_CODE > KERNEL_VERSION(4, 10, 0)
#include <linux/sched/signal.h>
#endif

MODULE_LICENSE("GPL");
MODULE_AUTHOR("EmbeddedPathashala");
MODULE_DESCRIPTION("Walk the kernel task list and display all threads");

#define BUFMAX 256
#define TMPMAX 64

static void display_idle_thread(void)
{
    /*
     * init_task is the task_struct of the idle thread on CPU core 0.
     * It is always exported by the kernel and is a safe starting point.
     * The idle thread (swapper/0) runs when no other work is available.
     */
    pr_info("[swapper/0] PID=0 TGID=0  [idle/CPU0]\n");
}

static int walk_all_threads(void)
{
    struct task_struct *g, *t;
    char buf[BUFMAX], tmp[TMPMAX];
    int total = 0;
    unsigned int nr_thrds;

    display_idle_thread();

    /*
     * do_each_thread / while_each_thread: the canonical kernel macro
     * pair for iterating every live thread on the system.
     *
     * 'g' = group leader (the "main" task_struct representing the process)
     * 't' = individual thread within that process
     *
     * For a single-threaded process, g == t for that one iteration.
     */
    do_each_thread(g, t) {
        /*
         * task_lock() acquires a per-task spinlock, making it safe
         * to read the task's fields without them changing under us.
         */
        task_lock(t);

        memset(buf, 0, sizeof(buf));
        memset(tmp, 0, sizeof(tmp));

        /* Print TGID (process ID seen from user space) and PID (thread ID) */
        snprintf(buf, BUFMAX - 1, "TGID=%6d  PID=%6d", g->tgid, t->pid);

        /* Print the kernel virtual address of this task_struct */
        snprintf(tmp, TMPMAX - 1, "  task=%px", t);
        strncat(buf, tmp, TMPMAX);

        /* Print the start address of this thread's kernel-mode stack */
        snprintf(tmp, TMPMAX - 1, "  kstack=%px", t->stack);
        strncat(buf, tmp, TMPMAX);

        /*
         * Determine if this is a kernel thread or a user-space thread.
         * Kernel threads have g->mm == NULL (no user virtual address space).
         * User-space threads have a valid mm_struct pointer.
         *
         * We read t->comm directly instead of using get_task_comm()
         * because get_task_comm() tries to acquire the task lock again
         * -- causing a deadlock since we already hold it.
         */
        if (!g->mm) {
            /* Kernel thread: display name in square brackets (like ps does) */
            snprintf(tmp, TMPMAX - 1, "  [%-15s]", t->comm);
        } else {
            /* User-space thread */
            snprintf(tmp, TMPMAX - 1, "   %-15s ", t->comm);
        }
        strncat(buf, tmp, TMPMAX);

        /*
         * If this is the main thread of a multi-threaded user-space process
         * (TGID == PID and thread count > 1), print the thread count.
         * get_nr_threads() returns the number of threads in the group.
         */
        nr_thrds = get_nr_threads(g);
        if (g->mm && (g->tgid == t->pid) && (nr_thrds > 1)) {
            snprintf(tmp, TMPMAX - 1, "  [%u threads]", nr_thrds);
            strncat(buf, tmp, TMPMAX);
        }

        pr_info("%s\n", buf);
        total++;

        task_unlock(t);

    } while_each_thread(g, t);

    return total;
}

static int __init tasklist_walk_init(void)
{
    int count;
    pr_info("=== EmbeddedPathashala: Walking the Kernel Task List ===\n");
    pr_info("%-10s  %-10s  %-18s  %-18s  %-17s\n",
            "TGID", "PID", "task_struct addr", "kernel stack addr", "name");
    count = walk_all_threads();
    pr_info("Total threads counted: %d\n", count);
    return 0;
}

static void __exit tasklist_walk_exit(void)
{
    pr_info("Module unloaded.\n");
}

module_init(tasklist_walk_init);
module_exit(tasklist_walk_exit);

Writing the Makefile

obj-m += tasklist_walk.o

KDIR := /lib/modules/$(shell uname -r)/build

all:
	make -C $(KDIR) M=$(PWD) modules

clean:
	make -C $(KDIR) M=$(PWD) clean

Build it with make and load it with sudo insmod tasklist_walk.ko.

Understanding the Key Fields: task_struct, mm, comm, and stack

Let’s take a closer look at each field we used in the walking function, because understanding these fields is foundational for Linux kernel and device driver development.

How This Connects to the /proc Filesystem

Everything we have discussed connects directly to what you see in the /proc filesystem. Each process gets a numbered directory under /proc — for example, /proc/1234/ for a process with TGID 1234. Inside that directory, there is a task/ subdirectory. Each thread in that process gets its own subdirectory inside task/ named by its kernel PID.

So if process 1234 has three threads with PIDs 1234, 1235, and 1236, you will find:

/proc/1234/task/1234/
/proc/1234/task/1235/
/proc/1234/task/1236/

This is exactly how tools like ps, top, htop, and pidstat get their thread information — they read from /proc, which is the kernel exposing its own task list through a virtual filesystem. When you write a kernel module that walks the task list directly, you are doing the same thing but without the /proc indirection layer.

Modern Kernel Considerations (Linux 5.x / 6.x)

If you are using a modern LTS kernel (5.15, 6.1, or 6.6 at the time of writing), there are a few things to be aware of beyond the header changes covered above.

rcu_read_lock();
do_each_thread(g, t) {
    /* safe reads here */
} while_each_thread(g, t);
rcu_read_unlock();

Common Mistakes and How to Avoid Them

Summary & Key Takeaways

In this lecture from the free Linux kernel development course at EmbeddedPathashala, you learned how the kernel maintains and iterates its internal task list. You now understand why task_struct is the single most important data structure in the Linux kernel, how PID and TGID relate to user-space thread IDs, how to detect kernel threads programmatically, and how to safely traverse every live thread from inside a loadable kernel module.

This knowledge is directly applicable to writing device drivers, debugging multi-threaded application issues at the kernel level, and building kernel tools and diagnostics. Understanding the task list is also the prerequisite for the next major topic: Linux kernel memory management internals.

Frequently Asked Questions