Debian Codegraph @

src/utils/proc_pids/proc_pids.h

raw
1 /**
2 * collectd - src/utils/proc_pids/proc_pids.h
3 *
4 * Copyright(c) 2018-2019 Intel Corporation. All rights reserved.
5 *
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:
12 *
13 * The above copyright notice and this permission notice shall be included in
14 * all copies or substantial portions of the Software.
15 *
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
22 * SOFTWARE.
23 *
24 * Authors:
25 * Starzyk, Mateusz <[email protected]>
26 * Wojciech Andralojc <[email protected]>
27 * Michał Aleksiński <[email protected]>
28 **/
29
30 #ifndef UTILS_PROC_PIDS_PROC_PIDS_H
31 #define UTILS_PROC_PIDS_PROC_PIDS_H 1
32
33 #include <dirent.h>
34 #include <sys/types.h>
35
36 /*
37 * Process name inside comm file is limited to 16 chars.
38 * More info here: http://man7.org/linux/man-pages/man5/proc.5.html
39 */
40 #define MAX_PROC_NAME_LEN 16
41
42 /* Helper typedef for process name array
43 * Extra 1 char is added for string null termination.
44 */
45 typedef char proc_comm_t[MAX_PROC_NAME_LEN + 1];
46
47 /* List of pids. */
48 typedef struct pids_list_s {
49 pid_t *pids;
50 size_t size;
51 size_t allocated;
52 } pids_list_t;
53
54 /* Holds process name and list of pids assigned to that name */
55 typedef struct proc_pids_s {
56 proc_comm_t process_name;
57 pids_list_t *prev;
58 pids_list_t *curr;
59 } proc_pids_t;
60
61 /*
62 * NAME
63 * pids_list_free
64 *
65 * DESCRIPTION
66 * Free all elements of given pids list
67 *
68 * PARAMETERS
69 * `list' Head of target pids_list.
70 */
71 void pids_list_free(pids_list_t *list);
72
73 /*
74 * NAME
75 * pids_list_add_pid
76 *
77 * DESCRIPTION
78 * Adds pid at the end of the pids array.
79 * Reallocates memory for new pid element, it is up to user to free it.
80 *
81 * PARAMETERS
82 * `list' Target pids_list.
83 * `pid' Pid to be added.
84 *
85 * RETURN VALUE
86 * On success, returns 0.
87 * -1 on memory allocation error.
88 */
89 int pids_list_add_pid(pids_list_t *list, const pid_t pid);
90
91 /*
92 * NAME
93 * pids_list_clear
94 *
95 * DESCRIPTION
96 * Remove all pids from the list
97 *
98 * PARAMETERS
99 * `list' Target pids_list.
100 *
101 * RETURN VALUE
102 * On success, return 0
103 */
104 int pids_list_clear(pids_list_t *list);
105
106 /*
107 * NAME
108 * pids_list_add_list
109 *
110 * DESCRIPTION
111 * Adds pids list at the end of the pids list.
112 * Allocates memory for new pid elements, it is up to user to free it.
113 *
114 * PARAMETERS
115 * `dst' Target PIDs list.
116 * `src' Source PIDs list.
117 *
118 * RETURN VALUE
119 * On success, returns 0.
120 * -1 on memory allocation error.
121 */
122 int pids_list_add_list(pids_list_t *dst, pids_list_t *src);
123
124 /*
125 * NAME
126 * pids_list_contains_pid
127 *
128 * DESCRIPTION
129 * Tests if pids list contains specific pid.
130 *
131 * PARAMETERS
132 * `list' pids_list to check.
133 * `pid' Pid to be searched for.
134 *
135 * RETURN VALUE
136 * If PID found in list, returns 1,
137 * Otherwise returns 0.
138 */
139 int pids_list_contains_pid(pids_list_t *list, const pid_t pid);
140
141 /*
142 * NAME
143 * pids_list_diff
144 *
145 * DESCRIPTION
146 * Searches for differences in two given lists
147 *
148 * PARAMETERS
149 * `proc' List of pids
150 * `added' New pids which appeared
151 * `removed' Result array storing pids which disappeared
152 * RETURN VALUE
153 * 0 on success. Negative number on error.
154 */
155 int pids_list_diff(proc_pids_t *proc, pids_list_t *added, pids_list_t *removed);
156
157 /*
158 * NAME
159 * proc_pids_is_name_valid
160 *
161 * DESCRIPTION
162 * Checks if given string is valid process name.
163 *
164 * PARAMETERS
165 * `name' null-terminated char array
166 *
167 * RETURN VALUE
168 * If given name is a valid process name, returns 1,
169 * Otherwise returns 0.
170 */
171 int proc_pids_is_name_valid(const char *name);
172
173 /*
174 * NAME
175 * proc_pids_init
176 *
177 * DESCRIPTION
178 * Helper function to properly initialize array of proc_pids.
179 * Allocates memory for proc_pids structs.
180 *
181 * PARAMETERS
182 * `procs_names_array' Array of null-terminated strings with
183 * process' names to be copied to new array
184 * `procs_names_array_size' procs_names_array element count
185 * `proc_pids' Address of pointer, under which new
186 * array of proc_pids will be allocated.
187 * Must be NULL.
188 * RETURN VALUE
189 * 0 on success. Negative number on error:
190 * -1: allocation error
191 */
192 int proc_pids_init(const char **procs_names_array,
193 const size_t procs_names_array_size,
194 proc_pids_t **proc_pids[]);
195
196 /*
197 * NAME
198 * proc_pids_update
199 *
200 * DESCRIPTION
201 * Updates PIDs matching processes's names.
202 * Searches all PID directories in /proc fs and updates current pids_list.
203 *
204 * PARAMETERS
205 * `procfs_path' Path to systems proc directory (e.g. /proc)
206 * `proc_pids' Array of proc_pids pointers to be updated.
207 * `proc_pids_num' proc_pids element count
208 *
209 * RETURN VALUE
210 * 0 on success. -1 on error.
211 */
212 int proc_pids_update(const char *procfs_path, proc_pids_t *proc_pids[],
213 size_t proc_pids_num);
214
215 /*
216 * NAME
217 * proc_pids_free
218 *
219 * DESCRIPTION
220 * Releses memory allocatd for proc_pids
221 *
222 * PARAMETERS
223 * `proc_pids' Array of proc_pids
224 * `proc_pids_num' proc_pids element count
225 *
226 * RETURN VALUE
227 * 0 on success. -1 on error.
228 */
229 int proc_pids_free(proc_pids_t *proc_pids[], size_t proc_pids_num);
230
231 #endif /* UTILS_PROC_PIDS_PROC_PIDS_H */