Linux Kernel Architecture

Chapter 1: Introduction and Overview

put_mnt_ns(new_nsp->mnt_ns);

out_ns:

kmem_cache_free(nsproxy_cachep, new_nsp);

return ERR_PTR(err);

}

What the code does in detail is irrelevant right now; I come back to this in the following chapter. What
is essential is that the routine tries to clone various parts of the namespace depending on some flags that
control the cloning operation. Each type of namespace is handled in a separate function, for instance, in
copy_mnt_nsfor the filesystem namespace.

Each time the kernel copies a namespace, errors can occur, and these must be detected and passed
on to the calling function. Either the error is detected directly by the return code of a function, as for
clone_nsproxy, or the error is encoded in a pointer return value, which can be detected using the
ERR_PTRmacro, which allows for decoding the error value (I also discuss this mechanism below). In many
cases, it is not sufficient to just detect an error and return this information to the caller. It is also essen-
tial that previously allocated resources that are not required anymore because of the error are released
again. The standard technique of the kernel to handle this situation is as follows: Jump to a special label
and free all previously allocated resources, or put down references to objects by decrementing the refer-
ence count. Handling such cases as this is one of the valid applications for thegotostatement. There are
various possibilities to describe what is going on in the function:

❑ Talk the reader directly through thecodeinhugestep-by-steplists:

1. create_new_namespacecallsclone_nsproxy. If this fails, return-ENOMEM;otherwise,
   continue.


2. create_new_namespacethen callscopy_mnt_ns. If this fails, obtain the error value encoded
   in the return value ofcopy_mnt_nsand jump to the labelout_ns; otherwise, proceed.


3. create_new_namespacethen callscopy_utsname. If this fails, obtain the error value
   encoded in the return value ofcopy_utsnameand jump to the labelout_ns;otherwise,
   proceed.


4. ...

While this approach is favored by a number of kernel texts, it conveys only little information

in addition to what is directly visible from the source code anyway. It is appropriate to discuss

some of the most complicated low-level parts of the kernel this way, but this will foster an under-

standing of neither the big picture in general nor the code snippet involved in particular.

❑ Summarize what the function does with words, for instance, by remarking that ‘‘create_new_

namespacesis responsible to create copies or clones of the parent namespaces.’’ We use this

approach for less important tasks of the kernel that need to be done somehow, but do not pro-

vide any specific insights or use particularly interesting tricks.

❑ Use a flow diagram to illustrate what is going on in a function. With more than 150 code flow

diagrams in this book, this is one of my preferred ways of dealing with code. It is important to

note that these diagramsare not supposedto be a completely faithful representation of the opera-

tion. This would hardly simplify matters. Consider Figure 1-15, which illustrates how a faithful

representation ofcopy_namespacescould look. It is not at all simpler to read than the source

itself, so there is not much purpose in providing it.