Man Linux: Main Page and Category List

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