2 * collectd - src/utils_config_pids.h
4 * Copyright(c) 2018 Intel Corporation. All rights reserved.
6 * Permission is hereby granted, free of charge, to any person obtaining a copy
7 * of this software and associated documentation files (the "Software"), to deal
8 * in the Software without restriction, including without limitation the rights
9 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10 * copies of the Software, and to permit persons to whom the Software is
11 * furnished to do so, subject to the following conditions:
13 * The above copyright notice and this permission notice shall be included in
14 * all copies or substantial portions of the Software.
16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
25 * Starzyk, Mateusz <mateuszx.starzyk@intel.com>
26 * Wojciech Andralojc <wojciechx.andralojc@intel.com>
30 #include <sys/types.h>
33 * Process name inside comm file is limited to 16 chars.
34 * More info here: http://man7.org/linux/man-pages/man5/proc.5.html
36 #define MAX_PROC_NAME_LEN 16
38 /* Helper typedef for process name array
39 * Extra 1 char is added for string null termination.
41 typedef char proc_comm_t[MAX_PROC_NAME_LEN + 1];
43 /* Linked one-way list of pids. */
44 typedef struct pids_list_s {
46 struct pids_list_s *next;
49 /* Holds process name and list of pids assigned to that name */
50 typedef struct proc_pids_s {
51 proc_comm_t proccess_name;
60 * Free all elements of given pids list
63 * `list' Head of target pids_list.
65 void pids_list_free(pids_list_t *list);
72 * Checks if given string as valid process name.
75 * `name' null-terminated char array
78 * If given name is a valid process name, returns 1,
79 * Otherwise returns 0.
81 int is_proc_name_valid(const char *name);
88 * Adds pid at the end of the pids list.
89 * Allocates memory for new pid element, it is up to user to free it.
92 * `list' Head of target pids_list.
93 * `pid' Pid to be added.
96 * On success, returns 0.
97 * -1 on memory allocation error.
99 int pids_list_add_pid(pids_list_t **list, const pid_t pid);
103 * pids_list_contains_pid
106 * Tests if pids list contains specific pid.
109 * `list' Head of pids_list.
110 * `pid' Pid to be searched for.
113 * If PID found in list, returns 1,
114 * Otherwise returns 0.
116 int pids_list_contains_pid(pids_list_t *list, const pid_t pid);
120 * pids_list_add_pids_list
123 * Adds pids list at the end of the pids list.
124 * Allocates memory for new pid elements, it is up to user to free it.
125 * Increases dst_num by a number of added PIDs.
128 * `dst' Head of target PIDs list.
129 * `src' Head of source PIDs list.
130 * `dst_num' Variable to be increased by a number of appended PIDs.
133 * On success, returns 0.
134 * -1 on memory allocation error.
136 int pids_list_add_pids_list(pids_list_t **dst, pids_list_t *src,
143 * Reads process name from given pid directory.
144 * Strips new-line character (\n).
147 * `procfs_path` Path to systems proc directory (e.g. /proc)
148 * `pid_entry' Dirent for PID directory
149 * `name' Output buffer for process name, recommended proc_comm.
150 * `out_size' Output buffer size, recommended sizeof(proc_comm)
153 * On success, the number of read bytes (includes stripped \n).
154 * -1 on file open error
156 int read_proc_name(const char *procfs_path, const struct dirent *pid_entry,
157 char *name, const size_t out_size);
164 * Gets pid number for given /proc/pid directory entry or
165 * returns error if input directory does not hold PID information.
168 * `entry' Dirent for PID directory
169 * `pid' PID number to be filled
172 * 0 on success. -1 on error.
174 int get_pid_number(struct dirent *entry, pid_t *pid);
181 * Copies element from list to array. Assumes the space for the array is
185 * `array' First element of target array
186 * `list' Head of the list
187 * `array_length' Length (element count) of the target array
189 void pids_list_to_array(pid_t *array, pids_list_t *list,
190 const size_t array_length);
194 * initialize_proc_pids
197 * Helper function to properly initialize array of proc_pids.
198 * Allocates memory for proc_pids structs.
201 * `procs_names_array' Array of null-terminated strings with
202 * process' names to be copied to new array
203 * `procs_names_array_size' procs_names_array element count
204 * `proc_pids_array' Address of pointer, under which new
205 * array of proc_pids will be allocated.
208 * 0 on success. Negative number on error:
209 * -1: allocation error
211 int initialize_proc_pids(const char **procs_names_array,
212 const size_t procs_names_array_size,
213 proc_pids_t **proc_pids_array);
217 * fetch_pids_for_procs
220 * Finds PIDs matching given process's names.
221 * Searches all PID directories in /proc fs and
222 * allocates memory for proc_pids structs, it is up to user to free it.
223 * Output array will have same element count as input array.
226 * `procfs_path' Path to systems proc directory (e.g. /proc)
227 * `procs_names_array' Array of null-terminated strings with
228 * process' names to be copied to new array
229 * `procs_names_array_size' procs_names_array element count
230 * `proc_pids_array' Address of pointer, under which new
231 * array of proc_pids will be allocated.
235 * 0 on success. -1 on error.
237 int fetch_pids_for_procs(const char *procfs_path,
238 const char **procs_names_array,
239 const size_t procs_names_array_size,
240 proc_pids_t **proc_pids_array);
247 * Searches for differences in two given lists
250 * `prev' List of pids before changes
251 * `curr' List of pids after changes
252 * `added' Result array storing new pids which appeared in `curr'
253 * `added_num' `added_num' array length
254 * `removed' Result array storing pids which disappeared in `prev'
255 * `removed_num' `removed' array length
257 * 0 on success. Negative number on error.
259 int pids_list_diff(pids_list_t *prev, pids_list_t *curr, pids_list_t **added,
260 size_t *added_num, pids_list_t **removed,
261 size_t *removed_num);