Provided by: libpcp3-dev_5.0.3-1_amd64 bug

NAME

       pmtime,  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).

Performance Co-Pilot                                 Aconex                                            PMTIME(3)