---
name: "pmtime"
section: "3"
platform: "linux"
package: "pcp"
version: "7.2.2-2"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/pmtime/3"
---

# pmtime(3)

time control functions for synchronizing the archive position and update interval between one or more applications

## 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)](/pmtime/1.md), 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)](/select/2.md). 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 *showgui* 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)](/pmSetMode/3.md)) 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 *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 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\_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 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 *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 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)](/pmtime/1.md), [**PMAPI**(3)](/PMAPI/3.md) and [**pmSetMode**(3)](/pmSetMode/3.md).