8
edits
Changes
no edit summary
The main intention of this system call is to allow a user space process get the beancounters statistics ''periodically''. This statistics includes the fields observed in the <code>/proc/user_beancounters</code> file and one more field - the so called <code>minheld</code> value which is opposite to the <code>maxheld</code> one. As long as exporting the statistics the system call also notifies the task about the desired period has elapsed. The notification is performed by sending a signal to a process and this notification is one-shot.
The typical usage of this call is in performing the following steps.
# Request the amount of resources
In a signal handler one should just perform a respective system call to get the stats and schedule the next notification (yes, they are performed in one go; see below for more details).
The system call description is
<presource lang="c">
long ubstat(int func, unsigned long luid, void *notif, void *buf, int size);
</presource>
The macros and data typed used are declared in <code>include/ub/ub_stat.h</code> file.
=== Arguments description ===
'''<code>func</code>''' is like <code>cmd</code> in the <code>ioctl</code> system call. It can be one of
'''<code>size</code>''' is the <code>buf</code> memory size.
=== The statistics format ===The format of data rerurned returned into the buffer depends on the function requested.
'''1. <code>UBSTAT_READ_ONE</code>''' format is
<presource lang="c">
typedef unsigned long ubstattime_t;
ubstatparm_t param[1];
}
</presource>
It contains the time period for which the stats are returned and the <code>maxheld</code> and <code>failcnt</code> for the resource.
'''2. <code>UBSTAT_READ_ALL</code>''' format is
<presource lang="c">
typedef unsigned long ubstattime_t;
ubstatparm_t param[UB_RESOURCES];
}
</presource>
It contains the same info as the <code>UBSTAT_READ_ONE</code> does, but for all the resources.
'''3. <code>UBSTAT_READ_FULL</code>''' format is
<presource lang="c">
typedef unsigned long ubstattime_t;
ubstatparmf_t param[UB_RESOURCES];
}
</presource>
It contains the extended info for all the resources.
'''6. UBSTAT_GETTIME''' format is
<presource lang="c">
typedef unsigned long ubstattime_t;
ubstattime_t cur_time;
};
</presource>
It returns the time interval within which the stats are collected and the current time.
The <code>notif</code> should point to
<presource lang="c">
typedef struct {
long maxinterval;
int signum;
} ubnotifrq_t;
</presource>
The <code>maxinterval</code> is the time after which the notification will be delivered. It should be more than 1 (second).
=== Return value ===
The system call returns -1 in case error has occurred. In case of <code>UBSTAT_UBPARMNUM</code > it returns <code>UB_RESOURCES</code> and in all other cases it returns the amount of bytes written to the <code>buf</code>.
== Demo ==
The following program demonstrates how you can (but not should) use the described API. This example is deliberately made very stupid and simple to demonstrate the main idea and will only work on x86_64.
<presource lang="c">
#include <stdio.h>
#include <unistd.h>
return 0;
}
</presource>
== Implementation constraints ==
