.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "GMT_SHELL_FUNCTIONS.SH" "1" "Jan 07, 2024" "6.5" "GMT"
.SH NAME
gmt_shell_functions.sh \- Practical functions to be used in GMT bourne shell scripts
.SH SYNOPSIS
.sp
\fBgmt_init_tmpdir\fP
.sp
\fBgmt_remove_tmpdir\fP
.sp
\fBgmt_clean_up\fP [ \fIprefix\fP ]
.sp
\fBgmt_message\fP \fImessage\fP
.sp
\fBgmt_abort\fP \fImessage\fP
.sp
\fBgmt_build_movie\fP [ \fB\-d\fP \fIdirectory\fP ] [ \fB\-n\fP ] [ \fB\-r\fP \fIframerate\fP ] [ \fB\-v\fP ] \fInamestem\fP
.sp
\fBgmt_build_gif\fP [ \fB\-d\fP \fIdirectory\fP ] [ \fB\-l\fP \fIloop\fP ] [ \fB\-r\fP \fIdelay\fP ] \fInamestem\fP
.sp
\fBgmt_build_kmz\fP \fB\-p\fP \fIprefix\fP [ \fB\-r\fP ] \fIfiles\fP
.sp
\fBgmt_get_nrecords\fP \fIfile(s)\fP
.sp
\fBgmt_get_ndatarecords\fP \fIfile(s)\fP
.sp
\fBgmt_get_nfields\fP \fIstring\fP
.sp
\fBgmt_get_field\fP \fIstring\fP
.sp
\fBgmt_get_region\fP \fIfile(s)\fP [ \fIoptions\fP ]
.sp
\fBgmt_get_gridregion\fP \fIfile\fP [ \fIoptions\fP ]
.sp
\fBgmt_get_map_width\fP \fB\-R\fP \fB\-J\fP
.sp
\fBgmt_get_map_height\fP \fB\-R\fP \fB\-J\fP
.INDENT 0.0
.TP
\fBgmt_movie_script\fP [ \fB\-c\fP \fIcanvas\fP OR \fB\-e\fP \fIdpi\fP \fB\-h\fP \fIheight\fP \fB\-w\fP \fIwidth\fP ] [ \fB\-f\fP \fIformat\fP ]
[ \fB\-g\fP \fIfill\fP ] [ \fB\-n\fP \fIframes\fP ] [ \fB\-m\fP \fImargin\fP ] [ \fB\-r\fP \fIrate\fP ] \fInamestem\fP
.UNINDENT
.sp
\fBgmt_launch_jobs\fP [ \fB\-c\fP \fIn_cores\fP ] [ \fB\-l\fP \fInlines_per_cluster\fP ] [ \fB\-n\fP ] [ \fB\-v\fP ] [ \fB\-w\fP ] \fIcommandfile\fP
.sp
\fBgmt_set_psfile\fP \fIscriptfile\fP
.sp
\fBgmt_set_pdffile\fP \fIscriptfile\fP
.sp
\fBgmt_set_framename\fP \fIprefix framenumber\fP
.sp
\fBgmt_set_framenext\fP \fIframenumber\fP
.SH DESCRIPTION
.sp
\fBgmt_shell_functions.sh\fP 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:
.sp
\fB\&. gmt_shell_functions.sh\fP
.sp
Once included in a shell script, \fBgmt_shell_functions.sh\fP allows
GMT users to do some scripting more easily than otherwise. The
functions made available are:
.INDENT 0.0
.TP
\fBgmt_init_tmpdir\fP
Creates a temporary directory in \fB/tmp\fP or (when defined) in the
directory specified by the environment variable \fBTMPDIR\fP\&. The name
of the temporary directory is returned as environment variable
\fBGMT_TMPDIR\fP\&. This function also causes GMT to run in
\(aqisolation mode\(aq, i.e., all temporary files will be created in
\fBGMT_TMPDIR\fP and the \fI\%gmt.conf\fP file will not be adjusted.
.TP
\fBgmt_remove_tmpdir\fP
Removes the temporary directory and unsets the \fBGMT_TMPDIR\fP
environment variable.
.TP
\fBgmt_cleanup\fP
Remove all files and directories in which the current process number
is part of the file name. If the optional \fIprefix\fP is given then we
also delete all files and directories that begins with the given prefix.
.TP
\fBgmt_message\fP
Send a message to standard error.
.TP
\fBgmt_abort\fP
Send a message to standard error and exit the shell.
.TP
\fBgmt_get_nrecords\fP
Returns the total number of lines in \fIfile(s)\fP
.TP
\fBgmt_get_ndatarecords\fP
Returns the total number of data records in \fIfile(s)\fP, i.e., not counting headers.
.TP
\fBgmt_get_nfields\fP
Returns the number of fields or words in \fIstring\fP
.TP
\fBgmt_get_field\fP
Returns the given \fIfield\fP in a \fIstring\fP\&. Must pass \fIstring\fP between
double quotes to preserve it as one item.
.TP
\fBgmt_get_region\fP
Returns the region in the form w/e/s/n based on the data in table
\fIfile(s)\fP\&. Optionally add \fB\-I\fP\fIdx\fP/\fIdy\fP to round off the answer.
.TP
\fBgmt_get_gridregion\fP
Returns the region in the form w/e/s/n based on the header of a grid
\fIfile\fP\&. Optionally add \fB\-I\fP\fIdx\fP/\fIdy\fP to round off the answer.
.TP
\fBgmt_get_map_width\fP
Expects the user to give the desired \fB\-R\fP \fB\-J\fP settings and
returns the map width in the current measurement unit.
.TP
\fBgmt_get_map_height\fP
Expects the user to give the desired \fB\-R\fP \fB\-J\fP settings and
returns the map height in the current measurement unit.
.TP
\fBgmt_movie_script\fP
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.
.TP
\fBgmt_launch_jobs\fP
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.  \fBNote\fP: It is your responsibility
to make sure no race conditions occur (i.e., multiple commands
writing to the same file).
.TP
\fBgmt_set_psfile\fP
Create the output PostScript file name based on the base name of a
given file (usually the script name \fB$0\fP).
.TP
\fBgmt_set_framename\fP
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.
.TP
\fBgmt_set_framenext\fP
Accepts the current frame integer counter and returns the next
integer counter.
.TP
\fBgmt_build_movie\fP
Accepts a \fInamestem\fP which gives the prefix of a series of image files
with names \fIdir\fP/\fInamestem\fP_*.*.  Optional argument sets the
directory [same as \fInamestem\fP ], and frame rate [24].
Without arguments the function will display its usage.
.TP
\fBgmt_build_gif\fP
Accepts a \fInamestem\fP which gives the prefix of a series of image files
with names \fIdir\fP/\fInamestem\fP_*.*.  Optional argument sets the
directory [same as \fInamestem\fP], loop count and frame rate [24].
Without arguments the function will display its usage.
.TP
\fBgmt_build_kmz\fP
Accepts \fB\-p\fP \fIprefix\fP [ \fB\-r\fP ] and any number of KML files and
and the images they may refer to, and builds a single KMZ file with
the name \fIprefix\fP\&.kmz.
Without arguments the function will display its usage.
.UNINDENT
.SH NOTES
.sp
1. These functions only work in the Bourne shell (\fBsh\fP) and their
derivatives (like \fBash\fP, \fBbash\fP, \fBksh\fP and \fBzsh\fP). These
functions do not work in the C shell (\fBcsh\fP) or their derivatives
(like \fBtcsh\fP), and cannot be used in DOS batch scripts either.
.sp
2. \fBgmt_shell_functions.sh\fP 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 \fI\%https://github.com/GenericMappingTools/gmt\fP\&.
.SH SEE ALSO
.sp
\fI\%gmt\fP, \fI\%gmt.conf\fP,
\fI\%gmtinfo\fP, \fI\%grdinfo\fP
.SH COPYRIGHT
2024, The GMT Team
.\" Generated by docutils manpage writer.
.