include/linux/pid.h

0001 /* SPDX-License-Identifier: GPL-2.0 */
0002 #ifndef _LINUX_PID_H
0003 #define _LINUX_PID_H
0004
0005 #include <linux/rculist.h>
0006 #include <linux/wait.h>
0007 #include <linux/refcount.h>
0008
0009 enum pid_type
0010 {
0011     PIDTYPE_PID,
0012     PIDTYPE_TGID,
0013     PIDTYPE_PGID,
0014     PIDTYPE_SID,
0015     PIDTYPE_MAX,
0016 };
0017
0018 /*
0019  * What is struct pid?
0020  *
0021  * A struct pid is the kernel's internal notion of a process identifier.
0022  * It refers to individual tasks, process groups, and sessions.  While
0023  * there are processes attached to it the struct pid lives in a hash
0024  * table, so it and then the processes that it refers to can be found
0025  * quickly from the numeric pid value.  The attached processes may be
0026  * quickly accessed by following pointers from struct pid.
0027  *
0028  * Storing pid_t values in the kernel and referring to them later has a
0029  * problem.  The process originally with that pid may have exited and the
0030  * pid allocator wrapped, and another process could have come along
0031  * and been assigned that pid.
0032  *
0033  * Referring to user space processes by holding a reference to struct
0034  * task_struct has a problem.  When the user space process exits
0035  * the now useless task_struct is still kept.  A task_struct plus a
0036  * stack consumes around 10K of low kernel memory.  More precisely
0037  * this is THREAD_SIZE + sizeof(struct task_struct).  By comparison
0038  * a struct pid is about 64 bytes.
0039  *
0040  * Holding a reference to struct pid solves both of these problems.
0041  * It is small so holding a reference does not consume a lot of
0042  * resources, and since a new struct pid is allocated when the numeric pid
0043  * value is reused (when pids wrap around) we don't mistakenly refer to new
0044  * processes.
0045  */
0046
0047
0048 /*
0049  * struct upid is used to get the id of the struct pid, as it is
0050  * seen in particular namespace. Later the struct pid is found with
0051  * find_pid_ns() using the int nr and struct pid_namespace *ns.
0052  */
0053
0054 struct upid {
0055     int nr;
0056     struct pid_namespace *ns;
0057 };
0058
0059 struct pid
0060 {
0061     refcount_t count;
0062     unsigned int level;
0063     spinlock_t lock;
0064     /* lists of tasks that use this pid */
0065     struct hlist_head tasks[PIDTYPE_MAX];
0066     struct hlist_head inodes;
0067     /* wait queue for pidfd notifications */
0068     wait_queue_head_t wait_pidfd;
0069     struct rcu_head rcu;
0070     struct upid numbers[1];
0071 };
0072
0073 extern struct pid init_struct_pid;
0074
0075 extern const struct file_operations pidfd_fops;
0076
0077 struct file;
0078
0079 extern struct pid *pidfd_pid(const struct file *file);
0080 struct pid *pidfd_get_pid(unsigned int fd, unsigned int *flags);
0081 struct task_struct *pidfd_get_task(int pidfd, unsigned int *flags);
0082 int pidfd_create(struct pid *pid, unsigned int flags);
0083
0084 static inline struct pid *get_pid(struct pid *pid)
0085 {
0086     if (pid)
0087         refcount_inc(&pid->count);
0088     return pid;
0089 }
0090
0091 extern void put_pid(struct pid *pid);
0092 extern struct task_struct *pid_task(struct pid *pid, enum pid_type);
0093 static inline bool pid_has_task(struct pid *pid, enum pid_type type)
0094 {
0095     return !hlist_empty(&pid->tasks[type]);
0096 }
0097 extern struct task_struct *get_pid_task(struct pid *pid, enum pid_type);
0098
0099 extern struct pid *get_task_pid(struct task_struct *task, enum pid_type type);
0100
0101 /*
0102  * these helpers must be called with the tasklist_lock write-held.
0103  */
0104 extern void attach_pid(struct task_struct *task, enum pid_type);
0105 extern void detach_pid(struct task_struct *task, enum pid_type);
0106 extern void change_pid(struct task_struct *task, enum pid_type,
0107             struct pid *pid);
0108 extern void exchange_tids(struct task_struct *task, struct task_struct *old);
0109 extern void transfer_pid(struct task_struct *old, struct task_struct *new,
0110              enum pid_type);
0111
0112 struct pid_namespace;
0113 extern struct pid_namespace init_pid_ns;
0114
0115 extern int pid_max;
0116 extern int pid_max_min, pid_max_max;
0117
0118 /*
0119  * look up a PID in the hash table. Must be called with the tasklist_lock
0120  * or rcu_read_lock() held.
0121  *
0122  * find_pid_ns() finds the pid in the namespace specified
0123  * find_vpid() finds the pid by its virtual id, i.e. in the current namespace
0124  *
0125  * see also find_task_by_vpid() set in include/linux/sched.h
0126  */
0127 extern struct pid *find_pid_ns(int nr, struct pid_namespace *ns);
0128 extern struct pid *find_vpid(int nr);
0129
0130 /*
0131  * Lookup a PID in the hash table, and return with it's count elevated.
0132  */
0133 extern struct pid *find_get_pid(int nr);
0134 extern struct pid *find_ge_pid(int nr, struct pid_namespace *);
0135
0136 extern struct pid *alloc_pid(struct pid_namespace *ns, pid_t *set_tid,
0137                  size_t set_tid_size);
0138 extern void free_pid(struct pid *pid);
0139 extern void disable_pid_allocation(struct pid_namespace *ns);
0140
0141 /*
0142  * ns_of_pid() returns the pid namespace in which the specified pid was
0143  * allocated.
0144  *
0145  * NOTE:
0146  *  ns_of_pid() is expected to be called for a process (task) that has
0147  *  an attached 'struct pid' (see attach_pid(), detach_pid()) i.e @pid
0148  *  is expected to be non-NULL. If @pid is NULL, caller should handle
0149  *  the resulting NULL pid-ns.
0150  */
0151 static inline struct pid_namespace *ns_of_pid(struct pid *pid)
0152 {
0153     struct pid_namespace *ns = NULL;
0154     if (pid)
0155         ns = pid->numbers[pid->level].ns;
0156     return ns;
0157 }
0158
0159 /*
0160  * is_child_reaper returns true if the pid is the init process
0161  * of the current namespace. As this one could be checked before
0162  * pid_ns->child_reaper is assigned in copy_process, we check
0163  * with the pid number.
0164  */
0165 static inline bool is_child_reaper(struct pid *pid)
0166 {
0167     return pid->numbers[pid->level].nr == 1;
0168 }
0169
0170 /*
0171  * the helpers to get the pid's id seen from different namespaces
0172  *
0173  * pid_nr()    : global id, i.e. the id seen from the init namespace;
0174  * pid_vnr()   : virtual id, i.e. the id seen from the pid namespace of
0175  *               current.
0176  * pid_nr_ns() : id seen from the ns specified.
0177  *
0178  * see also task_xid_nr() etc in include/linux/sched.h
0179  */
0180
0181 static inline pid_t pid_nr(struct pid *pid)
0182 {
0183     pid_t nr = 0;
0184     if (pid)
0185         nr = pid->numbers[0].nr;
0186     return nr;
0187 }
0188
0189 pid_t pid_nr_ns(struct pid *pid, struct pid_namespace *ns);
0190 pid_t pid_vnr(struct pid *pid);
0191
0192 #define do_each_pid_task(pid, type, task)               \
0193     do {                                \
0194         if ((pid) != NULL)                  \
0195             hlist_for_each_entry_rcu((task),        \
0196                 &(pid)->tasks[type], pid_links[type]) {
0197
0198             /*
0199              * Both old and new leaders may be attached to
0200              * the same pid in the middle of de_thread().
0201              */
0202 #define while_each_pid_task(pid, type, task)                \
0203                 if (type == PIDTYPE_PID)        \
0204                     break;              \
0205             }                       \
0206     } while (0)
0207
0208 #define do_each_pid_thread(pid, type, task)             \
0209     do_each_pid_task(pid, type, task) {             \
0210         struct task_struct *tg___ = task;           \
0211         for_each_thread(tg___, task) {
0212
0213 #define while_each_pid_thread(pid, type, task)              \
0214         }                           \
0215         task = tg___;                       \
0216     } while_each_pid_task(pid, type, task)
0217 #endif /* _LINUX_PID_H */