---
name: "halsampler"
section: "1"
platform: "linux"
package: "linuxcnc-uspace"
version: "1:2.9.4-2+deb13u1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/halsampler"
---

# halsampler(1)

sample data from HAL in realtime

## NAME

halsampler - sample data from HAL in realtime

## SYNOPSIS

**halsampler** \[*options*\]

## DESCRIPTION

[**sampler**(9)](/sampler/9.md) and **halsampler** are used together to sample HAL data in real time and store it in a file. **sampler** is a realtime HAL component that exports HAL pins and creates a FIFO in shared memory. It then begins sampling data from the HAL and storing it to the FIFO. **halsampler** is a non-realtime program that copies data from the FIFO to stdout, where it can be redirected to a file or piped to some other program.

## OPTIONS

- **-c** *CHAN*

  instructs  **halsampler** to read from FIFO *CHAN*. FIFOs are numbered from zero, and the default value is zero, so this option is not needed unless multiple FIFOs have been created.

- **-n** *COUNT*

  instructs  **halsampler** to read *COUNT* samples from the FIFO, then exit.  If **-n** is not specified, **halsampler** will read continuously until it is killed.

- **-t**

  instructs  **halsampler** to tag each line by printing the sample number in the first column.

- **FILENAME**

  instructs **halsampler** to write to **FILENAME** instead of to stdout.

## USAGE

A FIFO must first be created by loading  [**sampler**(9)](/sampler/9.md) with  **halcmd loadrt** or a **loadrt** command in a HAL file.  Then **halsampler** can be invoked to begin printing data from the FIFO to stdout.

Data is printed one line per sample.  If **-t** was specified, the sample number is printed first.  The data follows, in the order that the pins were defined in the config string.  For example, if the **sampler** config string was "ffbs" then a typical line of output (without **-t**) would look like:

123\.55 33.4 0 -12

**halsampler** prints data as fast as possible until the FIFO is empty, then it retries at regular intervals, until it is either killed or has printed *COUNT* samples as requested by **-n**. Usually, but not always, data printed by **halsampler** will be redirected to a file or piped to some other program.

The FIFO size should be chosen to absorb samples captured during any momentary disruptions in the flow of data, such as disk seeks, terminal scrolling, or the processing limitations of subsequent program in a pipeline.  If the FIFO gets full and **sampler** is forced to overwrite old data, **halsampler** will print 'overrun' on a line by itself to mark each gap in the sampled data.  If **-t** was specified, gaps in the sequential sample numbers in the first column can be used to determine exactly how many samples were lost.

The data format for **halsampler** output is the same as for [**halstreamer**(1)](/halstreamer/1.md) input, so 'waveforms' captured with **halsampler** can be replayed using **halstreamer**. The **-t** option should not be used in this case.

## EXIT STATUS

If a problem is encountered during initialization, **halsampler** prints a message to stderr and returns failure.

Upon printing *COUNT* samples (if **-n** was specified) it will shut down and return success.  If it is terminated before printing the specified number of samples, it returns failure.  This means that when **-n** is not specified, it will always return failure when terminated.

## SEE ALSO

[**sampler**(9)](/sampler/9.md) [**streamer**(9)](/streamer/9.md) [**halstreamer**(1)](/halstreamer/1.md)

## AUTHOR

Original version by John Kasunich, as part of the LinuxCNC project.  Improvements by several other members of the LinuxCNC development team.

## REPORTING BUGS

Report bugs at https://github.com/LinuxCNC/linuxcnc/issues

## COPYRIGHT

Copyright © 2006 John Kasunich.\
 This is free software; see the source for copying conditions.  There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.