.TH rtapi_clock_set_period "3rtapi" "2006-10-12" "LinuxCNC Documentation" "RTAPI"
.SH NAME

rtapi_clock_set_period \- set the basic time interval for realtime tasks

.SH SYNTAX
.HP
 rtapi_clock_set_period(long int \fInsec\fR)

.SH ARGUMENTS
.IP \fInsec\fB
The desired basic time interval for realtime tasks.

.SH DESCRIPTION
\fBrtapi_clock_set_period\fR sets the basic time interval for realtime tasks.
All periodic tasks will run at an integer multiple of this period.  The first
call to \fBrtapi_clock_set_period\fR with \fInsec\fR greater than zero will
start the clock, using \fInsec\fR as the clock period in nano-seconds.  Due to
hardware and RTOS limitations, the actual period may not be exactly what was
requested.  On success, the function will return the actual clock period if it
is available, otherwise it returns the requested period.  If the requested
period is outside the limits imposed by the hardware or RTOS, it returns
\fB-EINVAL\fR and does not start the clock.  Once the clock is started,
subsequent calls with non-zero \fInsec\fR return \fB-EINVAL\fR and have no
effect.  Calling \fBrtapi_clock_set_period\fR with \fInsec\fR set to zero
queries the clock, returning the current clock period, or zero if the clock has
not yet been started.  

.SH REALTIME CONSIDERATIONS
Call only from within init/cleanup code, not from realtime tasks.  This
function is not available from user (non-realtime) code.

.SH RETURN VALUE
The actual period provided by the RTOS, which may be different than the
requested period, or a RTAPI status code.