Horizontal Position Absolute (HPA)

The parameter x must be an integer greater than or equal to 1. If x is less than or equal to 0, adjust x to be 1. If x is omitted, x defaults to 1. The column value is one-based: the leftmost column is column 1.

This sequence always unsets the pending wrap state.

HPA is functionally equivalent to Cursor Position (CUP) with the row set to the current cursor row and the column set to x. Because it takes the same absolute positioning path as CUP, the row is re-resolved along with the column. With origin mode off the row is unchanged, but with origin mode on the current row is read as an origin-relative row and the cursor can end up on a different row.

If origin mode is NOT set, the cursor is moved to column x clamped to the rightmost screen column.

If origin mode is set, x = 1 corresponds to the left margin and the maximum value for x is the right margin. When origin mode is set, it is impossible to position the cursor outside the horizontal scroll region with this sequence.

Origin mode shifts the row the same way. The current row is offset by the top margin and clamped to the bottom margin, so with a scroll region of rows 2 through 3, origin mode set and the cursor on absolute row 2, a bare CSI 5 G leaves the cursor on row 3.

Note

Two final bytes are accepted for HPA: G and ` (backtick). The backtick form is a legacy alias accepted by xterm and most modern terminals; both forms are equivalent. Other references call CSI Px G CHA (Cursor Horizontal Absolute); that is a second name for this sequence rather than a different one, and both final bytes are handled by a single implementation here.

printf "\033[1;1H" # move to top-left
printf "\033[0J" # clear screen
printf "\033[2;1H" # move to row 2, column 1
printf "A"
printf "\033[5G" # HPA to column 5
printf "X"

|__________|
|A___Xc____|

printf "\033[1;1H" # move to top-left
printf "\033[0J" # clear screen
printf "\033[3\`" # HPA (backtick form) to column 3
printf "X"

|__Xc______|

printf "\033[1;1H" # move to top-left
printf "\033[0J" # clear screen
printf "\033[500G" # HPA past the right edge
printf "X"

|_________Xc

printf "\033[1;1H" # move to top-left
printf "\033[0J" # clear screen
printf "\033[?69h" # enable left/right margins
printf "\033[3;5s" # scroll region columns 3..5
printf "\033[?6h" # origin mode
printf "\033[1;1H" # origin-relative top-left
printf "\033[500G" # HPA past the right margin
printf "X"

|____Xc____|

cols=$(tput cols)
printf "\033[${cols}G" # move to last column
printf "A" # set pending wrap state
printf "\033[3G" # HPA cancels pending wrap
printf "X"

|__Xc_____A|