Subversion Repositories c0or1k

.TH L4_GETID 7 2009-11-02 "Codezero" "Codezero Programmer's Manual"
.SH NAME
.nf
.BR "l4_getid" " - returns thread id, thread group id and space id of a thread."

.SH SYNOPSIS
.nf
.B #include <l4lib/arch/syscalls.h>
.B #include <l4lib/arch/syslib.h>

.BI "int l4_getid(struct task_ids " "*ids" ");"
.SH DESCRIPTION
.BR "l4_getid() " "returns thread id, thread group id and space id of a thread in a " "struct task_ids " "structure, as shown below."

.nf
.B struct task_ids {
.BI "      int " "tid" ";   /* Fully qualified thread id */"
.BI "      int " "spid" ";  /* Address space id (local to container) */"
.BI "      int " "tgid" ";  /* Thread group id (local, defined by userspace protocol) */"
};

.fi

.in 7
Every thread in the system has a thread id, space id and a thread group id associated with it. Each thread and space id is globally unique across the system. Thread group ids are available for grouping threads in arbitrary groups, via a user-defined protocol. A newly created thread may join an existing thread group or create a new group. This behaviour is defined by the thread's pager. Such a user-defined thread group allocation protocol may be useful for implementing groups of threads by higher level OS services.

Even though both thread and space ids are globally unique across the system, there is an addressability difference between them. Each thread id is a fully qualified id, carrying its container id information with it. Upon a system call that targets a thread id, the system allows addressing threads that reside in other containers. In contrast, space ids are not fully qualified. They are local to a container, and any system call addressing a space id cannot target a space in another container. For thread ids,
.BI "__cid("tid ")"
macro extracts the Container ID information from the fully qualified thread id, whereas the
.BI " __raw_tid("tid ")"
macro provides the raw Thread ID, which omits the container ID information from the thread id. Such a raw ID still uniquely identifies the thread across containers, i.e. there is one such raw id per thread across the system.

.SH FUTURE
.BR "l4_getid() " "call is currently not subject to capability checking, as every thread has a natural right to discover their ids. In the future, it is possible that this system call is used for naming discovery for other addressable entities. If such a role is given to this call, it may also become subject to capability checking, as access control would prove beneficial over naming discovery services."


.SH L4 USERSPACE LIBRARY

.nf
.B #include <l4lib/arch/syslib.h>

/*
 * Returns Thread ID of current thread
 */
.BI "static inline l4id_t self_tid(" "void" ")"

.SH RETURN VALUE
.BR "l4_getid()" " always succeeds with a return value of 0."