src/utils/proc_pids/proc_pids.h

   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 <mateuszx.starzyk@intel.com>
  26  *   Wojciech Andralojc <wojciechx.andralojc@intel.com>
  27  *   Michał Aleksiński <michalx.aleksinski@intel.com>
  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 */