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 uniform 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
       applications 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 existing time control  server.   The  start  and  finish
       fields  indicate  the chronological bounds interesting to the application.  The showdialog
       field indicates whether the time control server should initially show or hide the  dialog.
       The  position,  delta,  and  data  fields  indicate  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, update 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 vcrmode 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 tz and tzlabel fields of the state parameter.

       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_SHOWDIALOG command 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  visibility  of  the  time
       control  dialog using the pmTimeShowDialog function.  The initial visibility is determined
       when the time control dialog is first created by an application calling pmTimeConnect with
       the showdialog 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 applications need to change  the  connection  mode,  e.g.  to
       divorce the current time control server and connect to a new one.

SEE ALSO

       pmtime(1), PMAPI(3) and pmSetMode(3).