docs/func.txt

   1 Following is the list of functions that are currently exported in libresourced.so
   2
   3 Types:
   4 ======
   5
   6 /**
   7  * @brief Datausage quota
   8  */
   9 typedef struct {
  10         int time_period;
  11         int64_t snd_quota;
  12         int64_t rcv_quota;
  13         resman_state_t quota_type;
  14 } resman_datausage_quota;
  15
  16 /**
  17  * @brief return type of the counters callback
  18  */
  19 typedef enum {
  20         PCL_CANCEL = 0,                 /**< cancel */
  21         PCL_CONTINUE = 1,               /**< continue */
  22 } resman_cb_ret;
  23
  24 /**
  25  * @brief callback for enumerate counters and restrictions
  26  */
  27 typedef resman_cb_ret(*resman_perf_info_cb) (const resman_perf_info * info,
  28                                        void *user_data);
  29
  30 /**
  31  * @brief Selection rule applied for data usage enumeration
  32  */
  33 typedef struct {
  34         time_t from;
  35         time_t to;
  36         char *iface;
  37         int granularity;
  38 } data_usage_selection_rule;
  39
  40 typedef struct {
  41         resman_sql_exec exec;
  42 } resman_base_query;
  43
  44 typedef resman_ret_c(*resman_sql_exec) (const resman_exec_context *context);
  45
  46 typedef struct {
  47         resman_perf_info_cb info_cb;
  48         void *user_data;
  49         resman_perf_selection_rule *rule;
  50 } resman_exec_context;
  51
  52 typedef resman_cb_ret(*resman_perf_info_cb) (const resman_perf_info * info,
  53                                        void *user_data);
  54 /**
  55  * @brief Bundle structure for bringing all together application identification
  56  *     and properties.
  57  * app_id - application identification - copy it if you in
  58  *   callback function, don't store raw pointer on it
  59  * iface - interface name, NULL means all interfaces,
  60  *   don't store raw pointer on it in the callback function, copy it by value
  61  * interval - time interval for given result, NULL means entire interval
  62  * foreground - foreground restrictions and counters
  63  * background - background restrictions and counters
  64  */
  65 typedef struct {
  66         const char *app_id;
  67         const char *iface;
  68         resman_tm_interval *interval;
  69         resman_common_info foreground;
  70         resman_common_info background;
  71 } resman_perf_info;
  72
  73 /**
  74  * @brief Commulative structure for holding data usage information
  75  */
  76 typedef struct {
  77         resman_counters cnt;
  78         resman_restrictions rst;
  79 } resman_common_info;
  80
  81 typedef struct {
  82         time_t from;
  83         time_t to;
  84 } resman_tm_interval;
  85
  86 resman_ret_c - return value of most functions.
  87
  88 typedef enum {
  89         PCL_ERROR_NOTIMPL = -7,
  90         PCL_ERROR_UNINITIALIZED = -6,
  91         PCL_ERROR_NO_DATA = -5,
  92         PCL_ERROR_INVALID_PARAMETER = -4,
  93         PCL_ERROR_OUT_OF_MEMORY = -3,
  94         PCL_ERROR_DB_FAILED = -2,
  95         PCL_ERROR_FAIL = -1,
  96         PCL_ERROR_OK = 0
  97 } resman_ret_c;
  98
  99 /*
 100  * cpu_usage: percent of cpu usage
 101  * mem_usage: percent of mem usage
 102  * incomming_rate_limit: rate limit for incomming packets in bytes per second
 103  * outgoing_rate_limit: rate limit for outgoing packets in bytes per second
 104  */
 105 typedef struct {
 106         int cpu_usage;
 107         int mem_usage;
 108         int incoming_rate_limit;
 109         int outgoing_rate_limit;
 110 } resman_restrictions;
 111
 112 /**
 113  * @brief Selection rule applied for enumeration
 114  * order - order field resman_order_t
 115  * filter - fiter field resman_filter
 116  * groupping - on what we should groupping our result
 117  */
 118 typedef struct {
 119         unsigned char version;
 120         u_int32_t order;
 121         resman_filter filter;
 122         u_int32_t groupping;
 123 } resman_perf_selection_rule;
 124
 125 Functions:
 126 ==========
 127
 128 int apply_net_restriction(u_int32_t classid, int incoming_rate_limit, int outgoing_rate_limit)
 129
 130 Applies network rate limit to application having the supplied network class ID
 131
 132 classid - network class ID
 133 incoming_rate_limit - rate limit for incoming traffic
 134 outgoing_rate_limit - rate limit for outgoing traffic
 135
 136 Return values:
 137 Non-zero values mean errors while communicating with kernel module
 138
 139 TODO:
 140 - Currently incoming_rate_limit must be 0, otherwise PCL_ERROR_NOTIMPL will be returned
 141
 142 --------------------------------------------------------------------------------
 143 resman_ret_c apply_restriction(const char *app_id, const resman_restrictions *foreground, const resman_restrictions *background)
 144
 145 Stores restrictions into database to be applied when application is started again.
 146
 147 app_id - zero-terminated string containing package name of application to be restricted
 148 foreground - set of restrictions applied to application while in foreground
 149 background - set of restrictions applied to application while in background
 150
 151 Non-OK return values:
 152 PCL_ERROR_INVALID_PARAMETER - app_id is NULL
 153 PCL_ERROR_INVALID_PARAMETER - both foreground and background are NULL
 154 PCL_ERROR_FAIL - could not determine network class ID for the application
 155 PCL_ERROR_DB_FAILED - error while storing restrictions to database
 156 PCL_ERROR_NOTIMPL - incoming_rate_limit is set
 157 ???? - apply_net_restriction can return any non-zero integer value (see above) which will be returned as is
 158
 159 TODO:
 160 - Does not apply CPU and memory restrictions if application is already running
 161 - Background settings are ignored
 162 - Return meaningful result in case apply_net_restriction fails
 163
 164 --------------------------------------------------------------------------------
 165 resman_ret_c bind_statement(sqlite3_stmt *stm, const resman_perf_selection_rule *rule)
 166
 167 Applies selection rule to the statement.
 168
 169 stm - sqlite statement to bind parameters to
 170 rule - ???? parameters to be bound to statement
 171
 172 Non-OK return values:
 173 PCL_ERROR_INVALID_PARAMETER - stm is NULL
 174 PCL_ERROR_INVALID_PARAMETER - rule filter type is not PCL_FILTER_UNDEF and rule filter value is NULL
 175 PCL_ERROR_DB_FAILED - database error
 176
 177 TODO:
 178 The function assumes that bound parameter is always the first parameter to bind. This might break on some statements.
 179
 180 --------------------------------------------------------------------------------
 181 resman_base_query create_exec(const resman_perf_selection_rule *rule)
 182
 183 Returns a query to be executed based on rule supplied
 184
 185 --------------------------------------------------------------------------------
 186 int create_netlink(int protocol, int groups)
 187
 188 Create netlink socket.
 189
 190 Results: Created socket on success and -1 on failure.
 191
 192 --------------------------------------------------------------------------------
 193 resman_ret_c data_usage_details_foreach(const char *app_id,
 194                                      data_usage_selection_rule *rule,
 195                                      resman_perf_info_cb info_cb, void *user_data)
 196
 197 Process data usage details for application on given interval.
 198
 199 app_id  - null-terminated string containing package name of the application or NULL for all applications
 200 rule    - parameters of query
 201  - from - start of interval
 202  - to - end of interval
 203  - iface - name of interface or NULL for all interfaces
 204  - granularity - split data usage into granularity-sized chunks
 205 info_cb - pointer to callback to be executed on each record
 206 user_data - pointer to data which will be passed as argument 3 to callback
 207
 208 Interval is given as a pair of unix timestamps.
 209 If granularity is not supplied the result is the total data usage on the whole interval. Otherwise there will be one record for each chunk.
 210 If iface is not supplied there will be one record for each interface.
 211 If app_id is not supplied then records will contain total amount of data usage by all applications.
 212
 213 info_cb must return PCL_CONTINUE to keep processing results or PCL_CANCEL to stop processing and discard the rest.
 214
 215 Notes:
 216 Callbacks are issued synchronously. When data_usage_details_foreach returns, all callbacks are guaranteed to have been executed already.
 217 The function is not thread-safe.
 218 If granularity is supplied, interval is split into chunks and each record contains traffic during that chunk.
 219 If interface or granularity is supplied and a record contains no traffic, the record is omitted.
 220
 221 Errors:
 222 PCL_ERROR_INVALID_PARAMETER     - rule or info_cb is NULL
 223 PCL_ERROR_DB_FAILED             - database error
 224
 225 --------------------------------------------------------------------------------
 226 void data_usage_finalize(void)
 227
 228 Finalizes queries used in data usage functions
 229
 230 --------------------------------------------------------------------------------
 231 resman_ret_c data_usage_foreach(const data_usage_selection_rule *rule,
 232                              resman_perf_info_cb info_cb, void *user_data)
 233
 234 Process data usage on given interval.
 235
 236 rule    - parameters of query
 237  - from - start of interval
 238  - to - end of interval
 239  - iface - name of interface or NULL for all interfaces
 240  - granularity - split data usage into granularity-sized chunks
 241 info_cb - pointer to callback to be executed on each record
 242 user_data - pointer to data which will be passed as argument 3 to callback
 243
 244 Interval is given as a pair of unix timestamps. The result contains records for all applications that used network during that interval.
 245 If granularity is not supplied each record is the total data usage on the whole interval. Otherwise there is a record for each chunk.
 246 If iface is supplied the result is limited to that interface. Otherwise the result is a total of all interfaces.
 247
 248 info_cb must return PCL_CONTINUE to keep processing results or PCL_CANCEL to stop processing and discard the rest.
 249
 250 Notes:
 251 Callbacks are issued synchronously. When data_usage_foreach returns, all callbacks are guaranteed to have been executed already.
 252 The function is not thread-safe.
 253 If granularity is supplied, interval is split into chunks and each record contains traffic during that chunk. If any record contains no traffic, the record is omitted.
 254
 255 Errors:
 256 PCL_ERROR_INVALID_PARAMETER     - rule or info_cb is NULL
 257 PCL_ERROR_DB_FAILED             - database error
 258
 259 --------------------------------------------------------------------------------
 260 int data_usage_init(sqlite3 *db)
 261
 262 Initializes queries used in data usage functions.
 263
 264 --------------------------------------------------------------------------------
 265 void datausage_quota_finalize(void)
 266
 267 Finalizes queries used in data usage quota functions.
 268
 269 --------------------------------------------------------------------------------
 270 int datausage_quota_init(sqlite3 *db)
 271
 272 Initializes queries used in data usage quota functions.
 273
 274 --------------------------------------------------------------------------------
 275 u_int32_t get_classid_by_pkg_name(const char *pkg_name, int create)
 276
 277 Converts application package name to network class.
 278
 279 pkg_name - zero-terminated string containing the package name
 280 create - if non-zero attempts to create the cgroup for pkg_name before fetching network class ID
 281
 282 Returns class ID or 0 in case of error.
 283
 284 --------------------------------------------------------------------------------
 285 sqlite3 *resourced_get_database(void)
 286
 287 Returns the handler to PCL database containing restrictions and statistics.
 288
 289 --------------------------------------------------------------------------------
 290 int get_family_id(int sock, pid_t pid)
 291
 292 Probe the controller in genetlink to find the family id for the TRAF_STAT family. (Helper function)
 293
 294 --------------------------------------------------------------------------------
 295 void get_in_info(int sock, const pid_t pid, const int family_id,
 296             in_traffic_event_list **list)
 297
 298 Get list of incoming traffic records from the kernel module.
 299
 300 --------------------------------------------------------------------------------
 301 void get_out_info(int sock, const pid_t pid,
 302         const int family_id, out_traffic_event_list **list)
 303
 304 Get list of outgoing traffic records from the kernel module.
 305
 306 --------------------------------------------------------------------------------
 307 int make_cgroup_with_pid(char *dpg_name, char *app_path)
 308
 309 Creates a cgroup named dkg_name if needed and place current process to that cgroup.
 310
 311 dpkg_name - name of cgroup
 312 app_path - used only for debugging
 313
 314 Returns 0 on success -errno on error
 315
 316 Notes:
 317 The name is misleading, PID is not even accepted as a parameter.
 318 app_path is used only for debugging and not anywhere in the code
 319
 320 --------------------------------------------------------------------------------
 321 void notify_daemon(void)
 322
 323 Sends SIGUSR1 to the daemon.
 324
 325 --------------------------------------------------------------------------------
 326 resman_ret_c resman_perf_info_foreach(const resman_perf_selection_rule *rule,
 327                                 resman_perf_info_cb info_cb, void *user_data)
 328
 329 Processes network usage statistics based on supplied rule.
 330
 331 rule - the rule used for statistics selection
 332 info_cb - callback performed on each record
 333 user_data - pointer passed as argument 3 to the callback
 334
 335 Notes:
 336 Actual behavior depends largely on the rule.
 337
 338 --------------------------------------------------------------------------------
 339 resman_ret_c resman_sql_rules_exec(const resman_exec_context *context)
 340
 341 Performs the actual query and calls callback on each record.
 342
 343 context - contains the rule and callback
 344
 345 Note:
 346 Internal function.
 347
 348 --------------------------------------------------------------------------------
 349 resman_ret_c resman_sql_simple_exec(const resman_exec_context *context)
 350
 351 Performs the basic statistics query and calls callback on each record.
 352
 353 context - contains the rule and callback
 354
 355 Note:
 356 Internal function.
 357
 358 --------------------------------------------------------------------------------
 359 void put_attr(rt_param *arg, int type, const void *data, int data_len)
 360
 361 Write attribute to netlink packet. Helper function.
 362
 363 --------------------------------------------------------------------------------
 364 int receive_answer(int sock, const int attr_type, char **out_buffer, __u16 *arg_count)
 365
 366 Read answer from kernel module. Helper function.
 367
 368 --------------------------------------------------------------------------------
 369 int revert_net_restriction(u_int32_t classid)
 370
 371 Removes network restrictions set by apply_net_restriction.
 372
 373 classid - network class ID which will be unrestricted
 374
 375 Returns 0 on success, non-zero on failure.
 376
 377 Note:
 378 Name is a bit misleading in that it removes restrictions, not reverts to previous ones.
 379
 380 --------------------------------------------------------------------------------
 381 resman_ret_c revert_restriction(const char *app_id)
 382
 383 Removes restrictions set by apply_restriction.
 384
 385 app_id - zero-terminated string containing package name of application.
 386
 387 Returns 0 on success
 388 PCL_ERROR_DB_FAILED - database error
 389 ???? - any non-zero value could be returned by revert_net_restriction
 390
 391 Notes:
 392 Does not actually modify CPU or memory limits, only writes new settings to database.
 393 Name is misleading in that the function removes restrictions, not reverts to previous ones.
 394
 395 --------------------------------------------------------------------------------
 396 int send_command(int sock, const pid_t pid, const int family_id, __u8 cmd)
 397
 398 Helper function for sending commands to kernel module.
 399
 400 --------------------------------------------------------------------------------
 401 int send_restriction(int sock, const pid_t pid, const int family_id,
 402                  const u_int32_t *classids, const u_int16_t classid_count,
 403                  const enum traffic_restriction_type restriction_type)
 404
 405 Internal function used for setting network restrictions.
 406
 407 --------------------------------------------------------------------------------
 408 void send_start(int sock, const pid_t pid, const int family_id)
 409
 410 Helper function used in communicating with kernel module.
 411
 412 --------------------------------------------------------------------------------
 413 resman_ret_c set_datausage_quota(const char *app_id,
 414                               const resman_datausage_quota *quota)
 415
 416 Sets network traffic quota for application.
 417
 418 app_id - zero-terminated string containing package name of the application.
 419 quota - network traffic quota to be applied to the application
 420
 421 Returns:
 422 PCL_ERROR_OK - success
 423 PCL_ERROR_INVALID_PARAMETER - app_id or quota is NULL
 424
 425 Note:
 426 Currently only writes quota limits to the database.
 427