# pmtime

## NAME



           **pmTimeConnect** , **pmTimeDisconnect** , **pmTimeRecv** , **pmTimeSendAck** ,
           **pmTimeShowDialog** - time control functions for synchronizing the
           archive position and update interval between one or more
           applications
    


## C SYNOPSIS



           **#include <pcp/pmtime.h>**
    
           **int pmTimeConnect(int** _port_**, pmTime ***_state_**);**
           **int pmTimeDisconnect(int** _fd_**);**
           **int pmTimeSendAck(int** _fd_**, struct timeval ***_fetchTime_**);**
           **int pmTimeShowDialog(int** _fd_**, int** _show_**);**
           **int pmTimeRecv(int** _fd_**, pmTime ***_state_**);**
    
           **cc ... -lpcp_gui**
    


## DESCRIPTION



           These  functions form part of the Performance Metrics Applications
           Programming Interface (PMAPI) and are intended to provide  a  uni‐
           form  mechanism  for  applications to both replay archive data and
           report live data in a time synchronized manner.
    
           The _pmTime_ structure has the following fields:
             typedef struct {
                 unsigned int        magic;
                 unsigned int        length;
                 pm_tctl_command     command;
                 pm_tctl_source      source;
                 pm_tctl_state       state;
                 pm_tctl_mode        mode;
                 struct timeval      delta;
                 struct timeval      position;
                 struct timeval      start;     /* archive only */
                 struct timeval      end;       /* archive only */
                 char                data[0];   /* arbitrary length info (TZ) */
             } pmTime;
    
           In the simplest case, the application should call **pmTimeConnect** to
           connect to the time control server, pmtime(1), and then repeatedly
           call **pmTimeRecv** in the main loop of the application.  On  success,
           **pmTimeConnect** returns a non-negative file descriptor.  In applica‐
           tions  which  have multiple threads of control, rather than simply
           blocking in **pmTimeRecv** , the file descriptor may be used  in  calls
           to  select(2).  In graphical applications, the file descriptor may
           be used to interface with the event loop.
    
           The _port_ parameter to **pmTimeConnect** is  the  port  number  of  the
           socket  on which the time control server is (or will be) listening
           for new connections.
    
           The state parameter to **pmTimeConnect** is used to initialize  a  new
           time control server or to pass additional information to an exist‐
           ing time control server.  The _start_ and _finish_ fields indicate the
           chronological  bounds interesting to the application.  The _showgui_
           field indicates whether the time control server  should  initially
           show or hide the dialog.  The _position_ , _delta,_ and _data_ fields in‐
           dicate  the  initial  archive position, update interval, time zone
           string and time zone label string.
    
           **pmTimeRecv** blocks until the time control server  sends  a  command
           message.   It  then updates the state parameter and returns one of
           the PM_TCTL_* command identifiers.
    
           The PM_TCTL_SET command indicates the application should  seek  to
           the  archive  position (see pmSetMode(3)) returned in the _position_
           field of the state parameter.
    
           The PM_TCTL_STEP command indicates the application should  perform
           an  update,  i.e. advance (or rewind, if delta is negative) to the
           time indicated by position and then fetch new metric  values,  up‐
           date the display or whatever.  In order for several application to
           remain  synchronized,  the time control server will wait until all
           applications have acknowledged that they have completed  the  step
           command.   Applications  should  call  pmTimeSendAck when the step
           command has been processed.  Note that PM_TCTL_STEP  is  the  only
           command that requires an explicit acknowledgement.
    
           The  PM_TCTL_VCRMODE command is used by the time control server to
           indicate the current VCR mode.
    
           The value is returned in the _mode_ field  of  the  state  parameter
           passed   to   **pmTimeRecv** ,   and   remains  valid  until  the  next
           PM_TCTL_VCRMODE command is received.
    
           The PM_TCTL_TZ command indicates the application should use a  new
           time- zone, as indicated in the _newzone_ field of the state parame‐
           ter.
    
           The  PM_TCTL_BOUNDS  command  is sent to all applications when the
           time control server changes its chronological  bounds.   This  may
           occur  when  a new application connects to the time control server
           or the user changes the bounds manually.  Most  applications  will
           ignore this command.
    
           The  PM_TCTL_GUIHIDE  or  PM_TCTL_GUISHOW commands will be sent to
           all applications when the visibility of the  time  control  server
           changes.   This  allows applications to alter the text in menus or
           buttons to reflect this change.  Applications may change the visi‐
           bility of the time control dialog using the **pmTimeShowDialog** func‐
           tion.  The initial visibility is determined when the time  control
           dialog  is  first  created by an application calling **pmTimeConnect**
           with the _showgui_ field in the state parameter set to  the  desired
           value.
    
           The  **pmTimeDisconnect** function  may  be used to close the command
           socket to the time control server.  This is useful  when  applica‐
           tions need to change the connection mode, e.g. to divorce the cur‐
           rent time control server and connect to a new one.
    


* * *