p4 bgtask

Run background commands or triggers on the server.


p4 bgtask [-b retries] [-d] [-i interval] [-m runCount] [-w seconds] {-e command | -t triggerName}

Syntax conventions


Enables a Helix Core superuser on the p4 command-line client to run commands or programs remotely on the server in the background.
The server saves output to the server log file.


To minimize memory consumption on the server, a long-running task should minimize its output to standard output and standard error.

The superuser defines the commands in the triggers table (with -t triggerName) or as string arguments on the command line (with -e command). Can be configured in startup.N configurables so background tasks are spawned at startup. The superuser can specify an interval for re-running the command.

See also Defining background tasks in the triggers table in the Helix Core Server Administrator Guide.


-b retries

Maximum number of execution errors before ceasing to attempt execution. The default is 1.


Detach the client, which means the client does not see the output of the server-side task execution. This is particularly useful for a task that runs for a long period of time. See About detached mode.


This option is not allowed when the background task is specified in a startup.N configurable.

-e command

Command string to execute.

-i interval

Seconds between command invocations. The default is 1 second. The maximum is 2,678,400, the number of seconds in 31 days.

-m runCount

Maximum number of times the command is run. The default is 1.

-t triggerName

Name of the trigger to run in the background.

-w seconds

Seconds to wait after an execution error before attempting the next execution. The default is 5.

Usage Notes

Can File Arguments Use Revision Specifier? Can File Arguments Use Revision Range? Minimal Access Level Required




About detached mode

In detached mode, bgtask creates two separate pairs of log entries:

2017/10/04 14:20:35 pid 22735 user@ws0 [p4/2014.1.main/LINUX26X86_64/576838] 'user-cron -m 5 -d -i 1 -c perl foreground_detached.pl'
2017/10/04 14:21:35 pid 22735 completed .001s 0+0us 0+0io 0+0net 2140k 0pf
2017/10/04 14:20:35 pid 22735 user@ws0 background [p4/2014.1.main/LINUX26X86_64/576838] 'user-cron -m 5 -d -i 1 -c perl foreground_detached.pl'
2017/10/04 14:20:46 pid 22735 completed 10.1s 0+4us 0+8io 0+0net 2164k 0pf

The first two lines record the start and end for the user portion of the command.

The final two lines record the start and end for the background portion.


startup.1=bgtask -t log_checker Upon server startup, run the log_checker task in the background. (See the startup.N configurable)

p4 bgtask -t verify

Immediately run a background task that executes the verify trigger that the superuser has already defined in the triggers table.

p4 bgtask -d -i 86400 -m 5 -t p4dstate

Run the specified trigger every day. (A day has 86400 seconds.)

p4 bgtask -e "top -b -n 1"

Sample the server load.

p4 bgtask -e "powershell -Command Import-Csv C:\p4root\errors.csv"

See the errors that have been logged.