other calls1.txt

Linux C 语言函数

acct

SYNOPSIS
int acct(const char *filename); 


PARAMETERS
filename: [in] contains the path of the accounting file, or NULL. 


DESCRIPTION
This call is not part of the plain Linux distribution. If the acct package is not installed,
the call always return -1 and errno is set to ENOSYS. If the package is installed then the 
call function normally. In that case, if filename points to a valid path, the termination 
time of each process will be loggued in the filename it points to. Otherwise, if filename 
is NULL, then the accounting function is turned off. 


RETURN VALUE
On success zero is returned. On error -1 is returned and errno is set to reflect the kind 
of error that occured.



*****************************************************************************************
alarm

SYNOPSIS
long alarm(long seconds); 


PARAMETERS
seconds: [in] the delay. 


DESCRIPTION
If the call completes successfully, the taks will receive a SIGALARM signal after a delay of
seconds seconds. A delay of zero seconds simply cancel the alarm. If an previous alarm was 
activated when the call is made then the previous alarm is cancelled. 

Internally, the call just sets an interruption timer. 


RETURN VALUE
If a previous alarm was activated, the call returns the time delay before the expiration of
that previous alarm (now canceled). Otherwise, it returns zero.


*****************************************************************************************
getgroups and setgroups

SYNOPSIS
int getgroups(int size, gid_t list[]); 

int setgroups(size_t size, const gid_t *list); 


PARAMETERS
size: [in] the maximum size of list. 

list: (For getgroups) [out] the array where to put the groups returned. 
	(For setgroups) [in] the new supplemental groups. 


DESCRIPTION
getgroups: up to size supplemental group entries of the current task are returned in list. 
If size is zero, no groups but instead the total number of supplemental groups is returned.
 

setgroups: sets the supplemental groups for the current task. Only the superuser may call 
this function. 


RETURN VALUE
On success, for getgroups, the number of groups returned in list is returned. If size is 
zero, then the number of supplemental groups is returned. In the case of setgroups, zero is
returned on success. 

On error, -1 is returned and errno is set to one of the following values: 

For both calls: EFAULT. 

For setgroups: 


EPERM: the current taks does not have superuser permission. 
EINVAL: size is greater than the maximum possible number of supplemental groups. 



*****************************************************************************************
getitimer and setitimer

SYNOPSIS
int getitimer(int which, struct itimerval *value); 

int setitimer(int which, const struct itimerval *value, struct itimerval *ovalue); 


PARAMETERS
which: [in] the timer to access. 

value: (For getitimer) [out] the value of the timer. (For setitimer) [in] the new value of 
the timer. 

ovalue: [out] the old value of the timer. 


DESCRIPTION
Each task posess 3 interval timers: 


ITIMER_REAL 
Real time timer. It delivers SIGALRM upon expiration. 

ITIMER_VIRTUAL 
Runs only during the time the task is actually running on the processor. It delivers 
SIGVTALRM upon expiration. 

ITIMER_PROF 
Runs only during the time the taks is actually running on the processor or during the 
operating system is running on behalf of the task. It delivers SIGPROF upon expiration. 
The structure itimerval has the following structure: 


struct  itimerval {
        struct  timeval it_interval;    /* timer interval */
        struct  timeval it_value;       /* current value */
};


struct timeval {
        long    tv_sec;         /* seconds */
        long    tv_usec;        /* microseconds */
};

getitimer gets those values for a specific timer and setitimer sets those values for a 
specific timer (and also retrieve the old values). If it_value or it_interval is set to 0 
the timer is deactivated. The timers always expire at or after the requested time. If the 
requesting process is active at the moment of expiration a signal is immediately delivered 
otherwise the delivery may be delayed. 


RETURN VALUE
On success zero is returned. On error -1 is returned and errno is set to one of the 
following values: 


EINVAL: which has an invalid value. 
EFAULT. 



*****************************************************************************************
getrlimit, getrusage and setrlimit

SYNOPSIS
int getrlimit (int resource, struct rlimit *rlim); 

int getrusage (int who, struct rusage *usage); 

int setrlimit (int resource, const struct rlimit *rlim); 


PARAMETERS
resource: [in] which resource to access. 

rlim: (For getrlimit) [in] points to a buffer where to put the limit. (For setrlimit) [out]
	 points to a buffer where the new limits are. 

who: [in] specifies from what process(es) we want to get the ressource usage. 

usage: [out] points to a buffer where the ressource usage is saved. 


DESCRIPTION
getrlimit gets the resources limits and setrlimit sets them. The resource variable is one of
: 


RLIMIT_CPU 
CPU time in miliseconds. 

RLIMIT_FSIZE 
The maximum file size (in bytes). 

RLIMIT_DATA 
The maximum data size (in bytes). 

RLIMIT_STACK 
The maximum stack size (in bytes). 

RLIMIT_CORE 
The maximum core file size (in bytes). 

RLIMIT_RSS 
The maximum resident set size (in bytes). 

Privision is made for a future implementation of the additionnal following values of 
resource: 


RLIMIT_MEMLOCK 
The maximum size of wired memory space. 

RLIMIT_NPROC 
The maximum number of processes. 

RLIMIT_OFILE 
The maximum number of opened files. 
The rlimit structure has the following format: 


struct rlimit {
        int     rlim_cur; /* current limit */
        int     rlim_max; /* maximum limit */
};

By setting the limit to RLIM_INFINITY a limit can be set to infinity. 

getrusage gets the ressource usage of the current task (for who set to RUSAGE_SELF) or of 
the child of the current task (for who set to RUSAGE_CHILDREN). The rusage structure has the
following definition: 


struct  rusage {
        struct timeval ru_utime;        /* user time used */
        struct timeval ru_stime;        /* system time used */
        long    ru_maxrss;              /* maximum resident set size */
        long    ru_ixrss;               /* integral shared memory size */
        long    ru_idrss;               /* integral unshared data size */
        long    ru_isrss;               /* integral unshared stack size */
        long    ru_minflt;              /* page reclaims */
        long    ru_majflt;              /* page faults */
        long    ru_nswap;               /* swaps */
        long    ru_inblock;             /* block input operations */
        long    ru_oublock;             /* block output operations */
        long    ru_msgsnd;              /* messages sent */
        long    ru_msgrcv;              /* messages received */
        long    ru_nsignals;            /* signals received */
        long    ru_nvcsw;               /* voluntary context switches */
        long    ru_nivcsw;              /* involuntary " */
};


RETURN VALUE
On success zero is returned. On error -1 is returned and errno is set to one of the 
following values: 

For setrlimit: EPERM if the task does not have superuser privileges. 

For setrlimit and getrlimit: EINVAL if the ressource value is invalid. 

For getrusage: EINVAL if the who value is invalid. 



*****************************************************************************************
gettimeofday and settimeofday

SYNOPSIS
int gettimeofday(struct timeval *tv, struct timezone *tz); 

int settimeofday(const struct timeval *tv, const struct timezone *tz); 


PARAMETERS
tv: for gettimeofday, [out] points to a buffer that will contain the time. For settimeofday,
 [in] points to a buffer containing the new time. 

tz: for gettimeofday, [out] points to a buffer that will contain the timezone information. 
	For settimeofday, [in] points to a buffer containing the new timezone information. 


DESCRIPTION
gettimeofday retreives the current time and timezone information. settimeofday sets the 
current time and timezone information. Only the superuser may call settimeofday. A value of
NULL for a parameter of settimeofday specifies not to change this parameter. 


RETURN VALUE
On success zero is returned. On error -1 is returned and errno is set to one of the 
following values: 


EPERM: settimeofday was called but the task has not superuser privileges. 
EINVAL.


*****************************************************************************************
idle

SYNOPSIS
int idle(void); 


DESCRIPTION
Try to give the processor to another task. 


RETURN VALUE
Always zero. 


*****************************************************************************************
ioperm

SYNOPSIS
int ioperm(unsigned long from, unsigned long num, int turn_on); 


PARAMETERS
from: [in] begining of the range of ports to modify. 

num: [in] number of ports to modify. 

turn_on: [in] new permission value of the new ports. 


DESCRIPTION
Modify the permission bits of a range of ports for the current task. The task must have 
superuser privileges to use the call. The range of ports that can be modified is limited 
to [0,3FFh]. 


RETURN VALUE
On success zero is returned. On error -1 is returned and errno is set to a value reflecting
the kind of error. 


*****************************************************************************************
iopl

SYNOPSIS
int iopl(int level); 


PARAMETERS
level: [in] the new io level of the process, in the range [0,3]. 


DESCRIPTION
Changes the io privilege level of the current task. The task must have superuser privileges 
to use the call. The task can get total io privileges this way. 


RETURN VALUE
On success zero is returned. On error -1 is returned and errno is set to one of the 
following values: 


EINVAL: level has an invalid value. 
EPERM: the calling process is not superuser. 


*****************************************************************************************
kill

SYNOPSIS
int kill(pit_t pid, int sig); 


PARAMETERS
pid: [in] the process or process group to send the signal to. 

sig: [in] the signal to send. 


DESCRIPTION
Sends a signal to a process or a process group. If pid is positive then it is send to the 
process with pid equal to pid. If pid is -1, the signal is send to every process except the
first. If pid is less than -1, the signal is send to the process group with group pid equals
to -pid. 


RETURN VALUE
On success, for pid less than -1, the number of processes that received the signal is 
returned, for other values of pid, zero is returned. On error -1 is returned and errno is 
set to one of the following values: 


EINVAL: the value of sig is invalid. 
EPERM: the taks does not have superuser privileges and tried to send a signal to a process 
with an effective uid different than the effective uid of the current task. 


*****************************************************************************************
killpg
Killpg is not a syscall but a wrapper to a kill in libc.

*****************************************************************************************
pause

SYNOPSIS
int pause(void); 


DESCRIPTION
The task sleeps until a signal is received. 


RETURN VALUE
Always return -1, and errno is always set to ERESTARNOTHAND which have meaning only for this
syscall. 


*****************************************************************************************