SLP_sysman_PG.h

   1 /*
   2  * Copyright (c) 2012 Samsung Electronics Co., Ltd.
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17
  18 /**
  19  *
  20  * @ingroup SLP_PG
  21  * @defgroup SLP_PG_SYSMAN System Manager
  22  * @{
  23
  24 <h1 class="pg">Introduction</h1>
  25
  26 <h2 class="pg">Purpose</h2>
  27 The purpose of the document is to describe how applications can use the System Manager APIs. This document gives programming guidelines to application engineers.
  28
  29 <h2 class="pg">Scope</h2>
  30 The scope of this document is limited to System Manager API usage.
  31
  32 <br>
  33 <h1 class="pg">System Manager Library Overview</h1>
  34 Sysman library provides convenience functions to get data about processes or to run processes.
  35 It reads the proc file system to check whether a process exists or not, gets a command line and execution path, gets the pid of a process etc.
  36 Some APIs of the sysman library use some device files also. If processes which call APIs of sysman library don't have the correct permission, they will fail.
  37 Most functions return -1 on failure and the errno will be set.<br>
  38 Please refer the manual pages of proc(Linux Programmer's Manual - PROC(5) http://www.kernel.org/doc/man-pages/man5/proc.5.html)
  39 or errno(Linux Programmer's Manual - ERRNO(3) http://www.kernel.org/doc/man-pages/man3/errno.3.html) for more details.
  40
  41 <h1 class="pg">System Manager Funtions</h1>
  42
  43 <h2 class="pg">System Manager APIs</h2>
  44 <i><b>API : sysman_get_pid</b></i>
  45 <br><b>Parameter In :</b> const char *execpath
  46 <br><b>Return :</b> int
  47 <br><b>Functionality :</b> This API is used to get the pid of the process which has the specified execpath.<br>
  48 Internally, this API searches /proc/{pid}/cmdline and compares the parameter execpath with 1st argument of cmdline.
  49 If there is no process that has same execpath in /proc/{pid}/cmdline, it will return (-1).
  50 <br><br>
  51 <i><b>API : sysman_get_cmdline_name</b></i>
  52 <br><b>Parameter In :</b> pid_t pid
  53 <br><b>Parameter Out :</b> char *cmdline
  54 <br><b>Parameter In :</b> size_t cmdline_size
  55 <br><b>Return :</b> int
  56 <br><b>Functionality :</b>This API is used to get the file name in the command line.<br>
  57 Caller process MUST allocate enough memory for the cmdline parameter. Its size should be assigned to cmdline_size.<br>
  58 Internally it reads the 1st argument of /proc/{pid}/cmdline and copies it to cmdline.<br>
  59 The function returns 0 on success and a negative value (-1) on failure.
  60 <br><br>
  61 <i><b>API : sysman_get_apppath</b></i>
  62 <br><b>Parameter In :</b> pid_t pid
  63 <br><b>Parameter Out :</b> char *app_path
  64 <br><b>Parameter In :</b> size_t app_path_size
  65 <br><b>Return :</b> int
  66 <br><b>Functionality :</b> This API is used to get the execution path of the process specified by the pid parameter.<br>
  67 Caller process MUST allocate enough memory for the app_path parameter. Its size should be assigned to app_path_size.<br>
  68 Internally it reads a link of /proc/{pid}/exe and copies the path to app_path. <br>
  69 The function returns 0 on success and a negative value (-1) on failure.
  70 <br><br>
  71 <i><b>API : sysconf_set_mempolicy</b></i>
  72 <br><b>Parameter In :</b> enum mem_policy mempol
  73 <br><b>Return :</b> int
  74 <br><b>Functionality :</b> This API is used to set the policy of the caller process for the situation of low available memory.<br>
  75 The function returns 0 on success and a negative value (-1) on failure.<br>
  76 If the caller process has no permission, it will be failed.
  77
  78 <b>Enumerate values</b>
  79 @code
  80 enum mem_policy {
  81         OOM_LIKELY , // For micelloneous applications
  82         OOM_NORMAL , // For fundamental applications
  83         OOM_IGNORE  // For daemon
  84 };
  85 @endcode
  86
  87  @}
  88 **/