---
name: "gmt_shell_functions.sh"
section: "1gmt"
platform: "linux"
package: "gmt-common"
version: "5.4.5+dfsg-2"
release: "Debian 10 (Buster)"
platforms: ["linux"]
url: "https://new.carta.tech/gmt_shell_functions.sh"
---

# gmt\_shell\_functions.sh(1gmt)

Practical functions to be used in GMT bourne shell scripts

## NAME

gmt\_shell\_functions.sh - Practical functions to be used in GMT bourne shell scripts

## SYNOPSIS

**gmt\_init\_tmpdir**

**gmt\_remove\_tmpdir**

**gmt\_clean\_up** \[*prefix*\]

**gmt\_message** *message*

**gmt\_abort** *message*

**gmt\_build\_movie** \[**-d** *directory*\] \[**-n**\] \[**-r** *framerate*\] \[**-v**\] *namestem*

**gmt\_build\_gif** \[**-d** *directory*\] \[**-l** *loop*\] \[**-r** *delay*\] *namestem*

**gmt\_build\_kmz** **-p** *prefix* \[ **-r** \] *files*

**gmt\_get\_nrecords** *file(s)*

**gmt\_get\_ndatarecords** *file(s)*

**gmt\_get\_nfields** *string*

**gmt\_get\_field** *string*

**gmt\_get\_region** *file(s)* \[*options*\]

**gmt\_get\_gridregion** *file* \[*options*\]

**gmt\_get\_map\_width** **-R** **-J**

**gmt\_get\_map\_height** **-R** **-J**

- **gmt\_movie\_script** \[**-c** *canvas* OR **-e** *dpi* **-h** *height* **-w** *width*\] \[**-f** *format*\]

  \[**-g** *fill*\] \[**-n** *frames*\] \[**-m** *margin*\] \[**-r** *rate*\] *namestem*

**gmt\_launch\_jobs** \[**-c** *n\_cores*\] \[**-l** *nlines\_per\_cluster*\] \[**-n**\] \[**-v**\] \[**-w**\] *commandfile*

**gmt\_set\_psfile** *scriptfile*

**gmt\_set\_pdffile** *scriptfile*

**gmt\_set\_framename** *prefix framenumber*

**gmt\_set\_framenext** *framenumber*

## DESCRIPTION

**gmt\_shell\_functions.sh** provides a set of functions to Bourne (again) shell scripts in support of GMT. The calling shell script should include the following line, before the functions can be used:

**. gmt\_shell\_functions.sh**

Once included in a shell script, **gmt\_shell\_functions.sh** allows GMT users to do some scripting more easily than otherwise. The functions made available are:

- **gmt\_init\_tmpdir**

  Creates a temporary directory in **/tmp** or (when defined) in the directory specified by the environment variable **TMPDIR**. The name of the temporary directory is returned as environment variable **GMT\_TMPDIR**. This function also causes GMT to run in 'isolation mode', i.e., all temporary files will be created in **GMT\_TMPDIR** and the gmt.conf file will not be adjusted.

- **gmt\_remove\_tmpdir**

  Removes the temporary directory and unsets the **GMT\_TMPDIR** environment variable.

- **gmt\_cleanup**

  Remove all files and directories in which the current process number is part of the file name. If the optional *prefix* is given then we also delete all files and directories that begins with the given prefix.

- **gmt\_message**

  Send a message to standard error.

- **gmt\_abort**

  Send a message to standard error and exit the shell.

- **gmt\_get\_nrecords**

  Returns the total number of lines in *file(s)*

- **gmt\_get\_ndatarecords**

  Returns the total number of data records in *file(s)*, i.e., not counting headers.

- **gmt\_get\_nfields**

  Returns the number of fields or words in *string*

- **gmt\_get\_field**

  Returns the given *field* in a *string*. Must pass *string* between double quotes to preserve it as one item.

- **gmt\_get\_region**

  Returns the region in the form w/e/s/n based on the data in table *file(s)*. Optionally add **-I***dx*/*dy* to round off the answer.

- **gmt\_get\_gridregion**

  Returns the region in the form w/e/s/n based on the header of a grid *file*. Optionally add **-I***dx*/*dy* to round off the answer.

- **gmt\_get\_map\_width**

  Expects the user to give the desired **-R** **-J** settings and returns the map width in the current measurement unit.

- **gmt\_get\_map\_height**

  Expects the user to give the desired **-R** **-J** settings and returns the map height in the current measurement unit.

- **gmt\_movie\_script**

  Creates an animation bash script template based on the arguments that set size, number of frames, video format etc. Without arguments the function will display its usage.

- **gmt\_launch\_jobs**

  Takes a file with a long list of commands and splits them into many chunks that can be executed concurrently. Without arguments the function will display its usage.  Note: It is your responsibility to make sure no race conditions occur (i.e., multiple commands writing to the same file).

- **gmt\_set\_psfile**

  Create the output PostScript file name based on the base name of a given file (usually the script name **$0**).

- **gmt\_set\_framename**

  Returns a lexically ordered filename stem (i.e., no extension) given the file prefix and the current frame number, using a width of 6 for the integer including leading zeros. Useful when creating animations and lexically sorted filenames are required.

- **gmt\_set\_framenext**

  Accepts the current frame integer counter and returns the next integer counter.

- **gmt\_build\_movie**

  Accepts a *namestem* which gives the prefix of a series of image files with names *dir*/*namestem*\_\*.\*.  Optional argument sets the directory \[same as *namestem*\], and frame rate \[24\]. Without arguments the function will display its usage.

- **gmt\_build\_gif**

  Accepts a *namestem* which gives the prefix of a series of image files with names *dir*/*namestem*\_\*.\*.  Optional argument sets the directory \[same as *namestem*\], loop count and frame rate \[24\]. Without arguments the function will display its usage.

- **gmt\_build\_kmz**

  Accepts **-p** *prefix* \[ **-r** \] and any number of KML files and and the images they may refer to, and builds a single KMZ file with the name *prefix*.kmz. Without arguments the function will display its usage.

## NOTES

1\. These functions only work in the Bourne shell (**sh**) and their derivatives (like **ash**, **bash**, **ksh** and **zsh**). These functions do not work in the C shell (**csh**) or their derivatives (like **tcsh**), and cannot be used in DOS batch scripts either.

2\. **gmt\_shell\_functions.sh** were first introduced in GMT version 4.2.2 and have since been regularly expanded with other practical scripting short-cuts. If you want to suggest other functions, please do so by adding a New Issue request on gmt.soest.hawaii.edu.

## SEE ALSO

gmt , gmt.conf , gmtinfo , grdinfo

## COPYRIGHT

2019, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe