What You Will Learn

Prerequisites

1. The Linux Kernel Task List

Every time a process or thread is created on a Linux system, the kernel allocates a data structure called task_struct. This structure holds everything the kernel needs to know about a running task — its state, its memory map, its open files, its identity, and much more.

All of these task_struct instances are linked together through a circular doubly-linked list. Think of it like a ring — you can start at any point and keep walking forward until you arrive back where you started. The kernel provides a fixed entry point into this ring called init_task, which represents the very first process on the system (historically init, on modern systems systemd with PID 1).

The kernel provides macros that hide the complexity of walking this circular list safely. You do not dereference pointers manually — you use these macros and let the kernel abstractions do the heavy lifting.

2. Iterating Over All Processes with for_each_process()

The first macro to know is for_each_process(). It walks the task list and gives you the task_struct pointer for the main thread of every process. It does not visit the individual threads that may exist within a multithreaded process. That distinction is important and we will come back to it shortly.

How to Use for_each_process() in a Kernel Module

Here is a minimal but complete kernel module that iterates over all processes and prints some basic information about each one:

// prcs_show.c — Linux kernel module to list all processes
// Tested on Linux 6.x kernels

#include <linux/init.h>
#include <linux/module.h>
#include <linux/sched.h>         // task_struct, for_each_process
#include <linux/sched/signal.h>  // signal_struct
#include <linux/cred.h>          // current_uid()

MODULE_LICENSE("GPL");
MODULE_AUTHOR("EmbeddedPathashala");
MODULE_DESCRIPTION("List all processes using for_each_process()");

static int __init prcs_show_init(void)
{
    struct task_struct *p;

    pr_info("prcs_show: loaded\n");
    pr_info("%-20s  %6s  %6s  %6s  %6s\n",
            "Name", "TGID", "PID", "RUID", "EUID");

    /*
     * for_each_process(p) expands to a for-loop over the circular
     * task list. Each iteration gives us the main thread of one process.
     * The RCU read lock protects the list from being modified while
     * we are reading it.
     */
    rcu_read_lock();
    for_each_process(p) {
        const struct cred *cred = __task_cred(p);
        pr_info("%-20s  %6d  %6d  %6u  %6u\n",
                p->comm,
                p->tgid,
                p->pid,
                from_kuid(&init_user_ns, cred->uid),
                from_kuid(&init_user_ns, cred->euid));
    }
    rcu_read_unlock();

    return 0;
}

static void __exit prcs_show_exit(void)
{
    pr_info("prcs_show: removed\n");
}

module_init(prcs_show_init);
module_exit(prcs_show_exit);

When you build and load this module (sudo insmod prcs_show.ko), the kernel log (dmesg) will show one line per process. The key thing to notice is that the TGID and PID columns will always be equal for every row — because for_each_process() only hands you the main thread of each process, and for the main thread those two values are always the same.

3. Iterating Over All Threads with do_each_thread()

If you want to visit every single thread on the system — not just the main thread of each process — you need a different pair of macros: do_each_thread(g, t) and while_each_thread(g, t).

These macros use two task_struct pointers: g (the group leader / main thread) and t (the individual thread being visited). The outer loop walks processes; the inner loop walks the threads within each process. Together they visit every thread alive on the system.

Kernel Module Using do_each_thread()

// thrd_show.c — List every thread on the system
// Linux 6.x compatible

#include <linux/init.h>
#include <linux/module.h>
#include <linux/sched.h>
#include <linux/sched/signal.h>

MODULE_LICENSE("GPL");
MODULE_AUTHOR("EmbeddedPathashala");
MODULE_DESCRIPTION("List every thread using do_each_thread / while_each_thread");

static int __init thrd_show_init(void)
{
    struct task_struct *g, *t;  // g = group leader, t = thread
    unsigned long total = 0;

    pr_info("thrd_show: loaded\n");
    pr_info("%-20s  %6s  %6s\n", "Thread Name", "TGID", "PID");

    rcu_read_lock();
    do_each_thread(g, t) {
        /*
         * If PID == TGID, this is the main thread of the process.
         * We mark kernel threads with square brackets (like ps does).
         */
        if (t->mm == NULL) {
            /* kernel thread — no user-space memory map */
            pr_info("[%-18s]  %6d  %6d\n", t->comm, t->tgid, t->pid);
        } else {
            pr_info("%-20s  %6d  %6d\n", t->comm, t->tgid, t->pid);
        }
        total++;
    } while_each_thread(g, t);
    rcu_read_unlock();

    pr_info("thrd_show: total threads on system = %lu\n", total);
    return 0;
}

static void __exit thrd_show_exit(void)
{
    pr_info("thrd_show: removed\n");
}

module_init(thrd_show_init);
module_exit(thrd_show_exit);

When you load this module you will see many more rows than the process-only version. A typical desktop Linux system runs 150–300 threads across perhaps 80–120 processes. Every thread gets its own row, and threads belonging to the same process share the same TGID value but have different PID values.

4. Understanding TGID vs PID — The Core Concept of This Free Linux Kernel Development Course

This is the most important concept in this lecture, so let us spend time on it.

Inside the Linux kernel, every thread — whether it is the main thread of a process or a worker thread — has its own task_struct. And every task_struct has a pid field. This means, at the kernel level, every thread has a unique identifier called a PID.

Now here is where POSIX comes in. The POSIX standard (pthreads) says that all threads of the same process must share a common process ID. But the kernel was giving every thread a unique PID internally. This contradiction meant Linux was, for a time, not compliant with the POSIX threading standard and caused porting problems.

The fix was elegant: add a new field to task_struct called tgid — the Thread Group IDentifier. Here is how it works:

So when user space asks “what is the PID of this process?”, the kernel returns tgid. When user space asks “what is this thread’s LWP (lightweight process) number?”, the kernel returns pid. This is exactly what you see in the output of ps -LA:

# Run this in your terminal to see the TGID/PID split for all threads:
$ ps -LA

# Output columns:
#  PID  — the kernel's tgid (shown as "process ID" to user space)
#  LWP  — the kernel's pid  (the unique thread/lightweight-process ID)

# Example: a multithreaded app might show:
#   PID    LWP  TTY   CMD
#   1500  1500  pts/0  myapp       ← main thread: PID == LWP (TGID == PID)
#   1500  1501  pts/0  myapp       ← child thread: PID same, LWP different
#   1500  1502  pts/0  myapp       ← child thread: PID same, LWP different

From inside the kernel module, you access the same data directly:

// Inside a kernel module, for any task_struct pointer 't':

t->pid   // the kernel's internal unique thread ID (== LWP in ps output)
t->tgid  // the process group ID shown as PID to user space

// Check if this is the main thread:
if (t->pid == t->tgid) {
    pr_info("%s is the main thread\n", t->comm);
} else {
    pr_info("%s is a child thread of TGID %d\n", t->comm, t->tgid);
}

5. Identifying Kernel Threads vs User-Space Threads

When you iterate the task list, you will encounter two kinds of tasks: kernel threads and user-space processes/threads. A simple and reliable way to tell them apart is by checking the mm pointer inside task_struct.

Every user-space task has a memory map — a struct mm_struct that describes the virtual address space for that process. Kernel threads have no user-space memory map at all; they run entirely in kernel space. So t->mm == NULL means it is a kernel thread.

// How to detect a kernel thread vs a user-space thread:

rcu_read_lock();
do_each_thread(g, t) {
    if (t->mm == NULL) {
        // This is a kernel thread (e.g., kworker, ksoftirqd, kswapd)
        pr_info("[%s]  tgid=%d  pid=%d  (kernel thread)\n",
                t->comm, t->tgid, t->pid);
    } else {
        // This is a user-space process or thread
        pr_info("%s  tgid=%d  pid=%d  (user space)\n",
                t->comm, t->tgid, t->pid);
    }
} while_each_thread(g, t);
rcu_read_unlock();

By convention (the same one ps uses), kernel threads are displayed with their name in square brackets: [kworker/0:0], [ksoftirqd/0], etc. Your kernel module output will look cleaner and more professional if you follow this same convention.

6. Building Your Kernel Modules — Makefile

Here is a generic Makefile you can use for any of the modules above. Save it in the same directory as your .c file:

# Makefile for simple kernel modules

# Change this to your module's .c filename (without extension)
MODULE_NAME := prcs_show

obj-m += $(MODULE_NAME).o

# Kernel build directory — adjust if your kernel source is elsewhere
KDIR := /lib/modules/$(shell uname -r)/build

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

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

# Build, load, check output, then unload:
make
sudo insmod prcs_show.ko
dmesg | tail -60
sudo rmmod prcs_show

7. Common Mistakes and Troubleshooting

8. Best Practices for Task List Iteration in Linux Kernel Programming

9. Quick Reference — for_each_process vs do_each_thread

10. Key Takeaways

Conclusion

In this lecture of our free Linux kernel development course, you learned how the Linux kernel organises all processes and threads into a single circular doubly-linked list rooted at init_task. You saw how to use for_each_process() to visit main threads and do_each_thread() / while_each_thread() to visit every thread. You now understand why the kernel has both a pid and a tgid inside every task_struct — the answer goes back to the need to be POSIX-compliant while still giving every thread a unique internal identifier.

You can verify all of this directly from user space using ps -LA, where the PID column shows tgid and the LWP column shows the kernel’s internal pid for each thread. Write the sample modules, load them, read the dmesg output, and compare it against ps -LA — everything will match perfectly.

In the next lecture we will go deeper into task_struct itself and look at how the kernel manages process state transitions. Keep building, keep exploring!

FAQ

Further Reading & References