Branch data     Line data    Source code

       1                 :            : /* SPDX-License-Identifier: GPL-2.0 */
       2                 :            : #ifndef _LINUX_PID_H
       3                 :            : #define _LINUX_PID_H
       4                 :            : 
       5                 :            : #include <linux/rculist.h>
       6                 :            : #include <linux/wait.h>
       7                 :            : #include <linux/refcount.h>
       8                 :            : 
       9                 :            : enum pid_type
      10                 :            : {
      11                 :            :         PIDTYPE_PID,
      12                 :            :         PIDTYPE_TGID,
      13                 :            :         PIDTYPE_PGID,
      14                 :            :         PIDTYPE_SID,
      15                 :            :         PIDTYPE_MAX,
      16                 :            : };
      17                 :            : 
      18                 :            : /*
      19                 :            :  * What is struct pid?
      20                 :            :  *
      21                 :            :  * A struct pid is the kernel's internal notion of a process identifier.
      22                 :            :  * It refers to individual tasks, process groups, and sessions.  While
      23                 :            :  * there are processes attached to it the struct pid lives in a hash
      24                 :            :  * table, so it and then the processes that it refers to can be found
      25                 :            :  * quickly from the numeric pid value.  The attached processes may be
      26                 :            :  * quickly accessed by following pointers from struct pid.
      27                 :            :  *
      28                 :            :  * Storing pid_t values in the kernel and referring to them later has a
      29                 :            :  * problem.  The process originally with that pid may have exited and the
      30                 :            :  * pid allocator wrapped, and another process could have come along
      31                 :            :  * and been assigned that pid.
      32                 :            :  *
      33                 :            :  * Referring to user space processes by holding a reference to struct
      34                 :            :  * task_struct has a problem.  When the user space process exits
      35                 :            :  * the now useless task_struct is still kept.  A task_struct plus a
      36                 :            :  * stack consumes around 10K of low kernel memory.  More precisely
      37                 :            :  * this is THREAD_SIZE + sizeof(struct task_struct).  By comparison
      38                 :            :  * a struct pid is about 64 bytes.
      39                 :            :  *
      40                 :            :  * Holding a reference to struct pid solves both of these problems.
      41                 :            :  * It is small so holding a reference does not consume a lot of
      42                 :            :  * resources, and since a new struct pid is allocated when the numeric pid
      43                 :            :  * value is reused (when pids wrap around) we don't mistakenly refer to new
      44                 :            :  * processes.
      45                 :            :  */
      46                 :            : 
      47                 :            : 
      48                 :            : /*
      49                 :            :  * struct upid is used to get the id of the struct pid, as it is
      50                 :            :  * seen in particular namespace. Later the struct pid is found with
      51                 :            :  * find_pid_ns() using the int nr and struct pid_namespace *ns.
      52                 :            :  */
      53                 :            : 
      54                 :            : struct upid {
      55                 :            :         int nr;
      56                 :            :         struct pid_namespace *ns;
      57                 :            : };
      58                 :            : 
      59                 :            : struct pid
      60                 :            : {
      61                 :            :         refcount_t count;
      62                 :            :         unsigned int level;
      63                 :            :         /* lists of tasks that use this pid */
      64                 :            :         struct hlist_head tasks[PIDTYPE_MAX];
      65                 :            :         /* wait queue for pidfd notifications */
      66                 :            :         wait_queue_head_t wait_pidfd;
      67                 :            :         struct rcu_head rcu;
      68                 :            :         struct upid numbers[1];
      69                 :            : };
      70                 :            : 
      71                 :            : extern struct pid init_struct_pid;
      72                 :            : 
      73                 :            : extern const struct file_operations pidfd_fops;
      74                 :            : 
      75                 :            : struct file;
      76                 :            : 
      77                 :            : extern struct pid *pidfd_pid(const struct file *file);
      78                 :            : 
      79                 :            : static inline struct pid *get_pid(struct pid *pid)
      80                 :            : {
      81                 :          3 :         if (pid)
      82                 :          3 :                 refcount_inc(&pid->count);
      83                 :            :         return pid;
      84                 :            : }
      85                 :            : 
      86                 :            : extern void put_pid(struct pid *pid);
      87                 :            : extern struct task_struct *pid_task(struct pid *pid, enum pid_type);
      88                 :            : extern struct task_struct *get_pid_task(struct pid *pid, enum pid_type);
      89                 :            : 
      90                 :            : extern struct pid *get_task_pid(struct task_struct *task, enum pid_type type);
      91                 :            : 
      92                 :            : /*
      93                 :            :  * these helpers must be called with the tasklist_lock write-held.
      94                 :            :  */
      95                 :            : extern void attach_pid(struct task_struct *task, enum pid_type);
      96                 :            : extern void detach_pid(struct task_struct *task, enum pid_type);
      97                 :            : extern void change_pid(struct task_struct *task, enum pid_type,
      98                 :            :                         struct pid *pid);
      99                 :            : extern void transfer_pid(struct task_struct *old, struct task_struct *new,
     100                 :            :                          enum pid_type);
     101                 :            : 
     102                 :            : struct pid_namespace;
     103                 :            : extern struct pid_namespace init_pid_ns;
     104                 :            : 
     105                 :            : /*
     106                 :            :  * look up a PID in the hash table. Must be called with the tasklist_lock
     107                 :            :  * or rcu_read_lock() held.
     108                 :            :  *
     109                 :            :  * find_pid_ns() finds the pid in the namespace specified
     110                 :            :  * find_vpid() finds the pid by its virtual id, i.e. in the current namespace
     111                 :            :  *
     112                 :            :  * see also find_task_by_vpid() set in include/linux/sched.h
     113                 :            :  */
     114                 :            : extern struct pid *find_pid_ns(int nr, struct pid_namespace *ns);
     115                 :            : extern struct pid *find_vpid(int nr);
     116                 :            : 
     117                 :            : /*
     118                 :            :  * Lookup a PID in the hash table, and return with it's count elevated.
     119                 :            :  */
     120                 :            : extern struct pid *find_get_pid(int nr);
     121                 :            : extern struct pid *find_ge_pid(int nr, struct pid_namespace *);
     122                 :            : 
     123                 :            : extern struct pid *alloc_pid(struct pid_namespace *ns);
     124                 :            : extern void free_pid(struct pid *pid);
     125                 :            : extern void disable_pid_allocation(struct pid_namespace *ns);
     126                 :            : 
     127                 :            : /*
     128                 :            :  * ns_of_pid() returns the pid namespace in which the specified pid was
     129                 :            :  * allocated.
     130                 :            :  *
     131                 :            :  * NOTE:
     132                 :            :  *      ns_of_pid() is expected to be called for a process (task) that has
     133                 :            :  *      an attached 'struct pid' (see attach_pid(), detach_pid()) i.e @pid
     134                 :            :  *      is expected to be non-NULL. If @pid is NULL, caller should handle
     135                 :            :  *      the resulting NULL pid-ns.
     136                 :            :  */
     137                 :            : static inline struct pid_namespace *ns_of_pid(struct pid *pid)
     138                 :            : {
     139                 :            :         struct pid_namespace *ns = NULL;
     140                 :          3 :         if (pid)
     141                 :          3 :                 ns = pid->numbers[pid->level].ns;
     142                 :            :         return ns;
     143                 :            : }
     144                 :            : 
     145                 :            : /*
     146                 :            :  * is_child_reaper returns true if the pid is the init process
     147                 :            :  * of the current namespace. As this one could be checked before
     148                 :            :  * pid_ns->child_reaper is assigned in copy_process, we check
     149                 :            :  * with the pid number.
     150                 :            :  */
     151                 :            : static inline bool is_child_reaper(struct pid *pid)
     152                 :            : {
     153                 :          3 :         return pid->numbers[pid->level].nr == 1;
     154                 :            : }
     155                 :            : 
     156                 :            : /*
     157                 :            :  * the helpers to get the pid's id seen from different namespaces
     158                 :            :  *
     159                 :            :  * pid_nr()    : global id, i.e. the id seen from the init namespace;
     160                 :            :  * pid_vnr()   : virtual id, i.e. the id seen from the pid namespace of
     161                 :            :  *               current.
     162                 :            :  * pid_nr_ns() : id seen from the ns specified.
     163                 :            :  *
     164                 :            :  * see also task_xid_nr() etc in include/linux/sched.h
     165                 :            :  */
     166                 :            : 
     167                 :            : static inline pid_t pid_nr(struct pid *pid)
     168                 :            : {
     169                 :            :         pid_t nr = 0;
     170                 :          3 :         if (pid)
     171                 :          3 :                 nr = pid->numbers[0].nr;
     172                 :            :         return nr;
     173                 :            : }
     174                 :            : 
     175                 :            : pid_t pid_nr_ns(struct pid *pid, struct pid_namespace *ns);
     176                 :            : pid_t pid_vnr(struct pid *pid);
     177                 :            : 
     178                 :            : #define do_each_pid_task(pid, type, task)                               \
     179                 :            :         do {                                                            \
     180                 :            :                 if ((pid) != NULL)                                      \
     181                 :            :                         hlist_for_each_entry_rcu((task),                \
     182                 :            :                                 &(pid)->tasks[type], pid_links[type]) {
     183                 :            : 
     184                 :            :                         /*
     185                 :            :                          * Both old and new leaders may be attached to
     186                 :            :                          * the same pid in the middle of de_thread().
     187                 :            :                          */
     188                 :            : #define while_each_pid_task(pid, type, task)                            \
     189                 :            :                                 if (type == PIDTYPE_PID)                \
     190                 :            :                                         break;                          \
     191                 :            :                         }                                               \
     192                 :            :         } while (0)
     193                 :            : 
     194                 :            : #define do_each_pid_thread(pid, type, task)                             \
     195                 :            :         do_each_pid_task(pid, type, task) {                             \
     196                 :            :                 struct task_struct *tg___ = task;                       \
     197                 :            :                 for_each_thread(tg___, task) {
     198                 :            : 
     199                 :            : #define while_each_pid_thread(pid, type, task)                          \
     200                 :            :                 }                                                       \
     201                 :            :                 task = tg___;                                           \
     202                 :            :         } while_each_pid_task(pid, type, task)
     203                 :            : #endif /* _LINUX_PID_H */