GMT_SHELL_FUNCTIONS.SH(1)

💖 GMT_SHELL_FUNCTIONS.SH 💖

okay so bestie, this is the manual page for gmt_shell_functions.sh, living in the GMT manual (section 1). It's a shell-scripting glow-up package, and honestly? it ate. 🫶

---

✨ NAME ✨

gmt_shell_functions.sh — practical functions to be used in GMT bourne shell scripts. no cap, that's the whole vibe. 🎀

---

✨ 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 hands a whole little toolkit to Bourne (Again) shell scripts, all in support of GMT. 🧚 Before you can use any of it, your calling shell script has to source it first — like, this exact line, before anything else works:

. gmt_shell_functions.sh

Once it's included in a shell script, gmt_shell_functions.sh lets GMT users do some scripting way more easily than they could otherwise. Main character energy. The functions it makes 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. bye bestie 👋
• 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. 💀 it's giving "we're done here"
• 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 -Idx/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 -Idx/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). 🚨

bestie listen. parallel is cute until two commands write the same file. that's on you, not on the function. 💅

• 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. 😭 so if you're on csh… thoughts and prayers fr fr
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 https://github.com/GenericMappingTools/gmt. 🫶 they want your ideas, periodt.

---

✨ SEE ALSO ✨

gmt, gmt.conf, gmtinfo, grdinfo

---

✨ COPYRIGHT ✨

2024, The GMT Team

---

okay that's the whole page bestie, you're welcome 💖 it was GMT version 6.5, dated Jan 07, 2024, and yes that's the source/version + date sign-off, mwah 🎀✨