C-Kermit Built-in Functions

Frank da Cruz, fdc@kermitproject.org
Most recent update: Thu Feb 29 08:37:06 2024

Function names can be shortened from the right as long as the result is still unique; for example you can use \Fchar() for \Fcharacter(). The F after the backslash means the following name is a function and the items in the parentheses are its arguments. The F need not be capitalized, nor does the function name need to be lowercase. The Returns column tells the data type returned by the function: int = integer, txt = text, chr = a single character, fn = filename, ip = IP address. A filespec (file specification), as opposed to filename, can include a directory path.

Some functions require a longer explanation; these show up as links in the Name column. Also you can see documentation for any function by typing "help function xxx" at the C-Kermit prompt, where xxx is the function name, e.g. "help function arraylook" ("h fu ar" is sufficient).

Name	Returns	Description
\Faaconvert(name,&a,&b)	int	Converts named associative array to scalar arrays &a and &b
\Fabsolute(n1)	int	Absolute (unsigned) value of integer n1
\Farraylook(pattern,&a)	int	Looks up a string or pattern (wildcard) in an array
\Fb64decode(s)	txt	Converts Base-64 encoded string s into clear text
\Fb64encode(s)	txt	Encodes clear-text string s in Base-64.
\Fbasename(filespec)	txt	Filename extracted from filespec
\Fbreak(s1,s2)	txt	s1 up to first character that is in s2
\Fcapitalize(s1)	txt	s1 with first letter capitalized and the rest lowercase
\Fcharacter(n)	chr	Character whose numeric code is n
\Fchecksum(s1)	int	Kermit 6-bit checksum of text s1 (also see \fcrc16())
\Fcmdstack(n1,n2)	int or txt	Name or type of object at command stack level n1
\Fcmpdates(d1,d2)	int	Compares free-format dates and/or times d1 and d2
\Fcode(c)	int	Numeric code value of character c
\Fcommand(s)	txt	Returns the output of shell command s and sets \v(pexitstat)
\Fcontents(variable)	txt	Value of variable, unevaluated
\Fcount(s1,s2,n1)	int	Number of occurrences of string s1 in s2, 0 or more.
\Fcrc16(txt)	int	16-bit cyclic redundancy check of text string s1
\Fcvtdate(s,n)	txt	Converts free-format date s to format n
\fcvtdate() format codes 0-6: C-Kermit> for i 0 6 1 { echo \m(i). \fcvtdate(,i) } 0. 20190822 07:59:29 1. 2019-Aug-22 07:59:29 2. 22-Aug-2019 07:59:29 3. 20190822075929 4. Thu Aug 22 07:59:29 2019 5. 2019:08:22:07:59:29 6. 22 August 2019 07:59:29 When the second argument is negative, only the date is shown; for example \fcvtdate(,-6) for the same date is "22 August 2019".
\Fcvtcset(s,cs1,cs2)	txt	Converts string s from character set cs1 to cs2 (see list)
\Fdate(file)	txt	Returns modification date/time of file as yyyymmdd hh:mm:ss
\Fday(s)	txt	Returns 3-letter day of week for date given (default=today)
\Fdayname(s)	txt	Like \Fday but with language and full-name options
\Fdayofyear(s)	int	Given free-format date s, returns day of year as yyyynnn
\Fdecodehex(s1,s2)	txt	Decodes string s1 that contains hexadecimal bytes with prefix s2
\Fdefinition(macro)	txt	Returns definition of given macro evaluated one level deep
\Fdelta2secs(s1,s2)	int	Converts delta time to seconds (see link)
\Fdialconvert(s)	txt	Convert phone number s to modem-dial format
\Fdiffdates(d1,d2)	dt	Returns difference between two dates in delta time
\Fdimension(&a)	int	Returns the dimension (number of elements) in array &a.
\Fdirectories(filespec,&a)	int,array	Number of directories that match filespec, with names in array &a
\Fdirname(filespec)	txt	The full directory (path) for the given filespec
\Fdostounixpath(s)	txt	Converts a DOS/Windows pathname into a Unix one
\Fdoytodate(n)	txt	Converts day of year yyyynnn to date yyyymmdd
\Femailaddress(s)	txt	Extracts email address from email From or Sender header line
\Ferrstring(n)	txt	Converts platform-dependent error code to error message
\Fevaluate(expression)	int	Value of arithmetic expression such as 2*(5+6) (integers only)
\Fexecute(macro args)	any	Invokes given marcro with given args and returns its RETURN value
\Ffilecompare(fn1,fn2)	int	Compares contents and lengths of file fn1 and fn2
\Ffileinfo(fn,&a)	int,array	Returns attributes of given file in array &a
\Ffiles(filespec,&a)	int,array	Returns number of files that match filespec with names in array &a
\Ffunction(s)	int	Returns 1 if s is the name of a built-in function, otherwise 0
\Fhextoip(s)	ipa	Converts hexadecimal s to decimal dotted IP address
\Fhexify(s1)	hex	Returns character string s1 encoded in hexadecimal. Note: this does not convert decimal numbers to hex; use \fradix() for that.
\Findex(s1,s2,n)	int	Returns position of leftmost occurrence of s1 in s2 starting at n
\Fiptohex(s)	ipa	Converts the decimal dotted IP address s to hexadecimal
\Fipaddress(s1,n)	ip	Extracts first IP address from s1 starting at n
\Fjoin(&a,s,n1,n2)	txt	Joins array elements into a string, s = optional separator, n's are options
\Fkeywordvalue(s1,s2)	txt	Converts string like 'name=value' into macro with given value
\Fleft(s,n)	txt	Returns the leftmost n characters of string s
\Flength(s1)	int	Length of string s1
\Fliteral(s1)	txt	Protects string s1 from evaluation
\Flop(s1,c,n)	txt	Chops off beginning of string s1 at nth leftmost occurrence of char c
\Flopx(s1,c,n)	txt	Chops off beginning of string s1 at nth rightmost occurrence of char c
\Flower(s1)	txt	Converts all uppercase letters in s1 to lowercase
\Flpad(s1,n,c)	txt	Returns s1 left-padded to length n with char c
\Fltrim(s1,s2)	txt	s1 with all characters from s2 trimmed from left; also see \ftrim()
\Fmaximum(n1,n2)	int	Returns the larger of the two numbers
\Fminimum(n1,n2)	int	Returns the smaller of the two numbers
\Fmjd(s)	int	Converts free-format date s into numeric Modified Julian Date
\Fmjdtodate(n)	date	Converts Modified Julian Date to yyymmdd (and optional time)
\Fmodulus(n1,n2)	int	Returns the remainder when n1 is divided by n2
\Fmonthname(s,n)	txt	Extracts month from date s and returns its name
\Fntotime(n)	txt	Converts seconds since midnight n into hh:mm:ss
\Fnday(s)	int	Returns numeric day of the week from free-format date s (Monday=1)
\Fntime(s)	int	Returns time portion of date-time s as seconds since midnight
\Fnextfile()	txt	Returns next filename from \Ffiles() list
\Fpathname(fn)	txt	Returns full pathname of file
\Fpattern(s)	txt	INPUT command only: Declares that s is a pattern ("wildcard").
\Fpermissions(fn)	txt	Returns the file's permissions (Unix and VMS).
\Fpictureinfo(fn,&a)	int,array	Extracts dimensions, orientation, and date from JPG image
Returns:   0 if file not found or not recognized;   1 if orientation is landscape;   2 if orientation is portrait;   3 if the image is square. Note: experience shows that the orientation is not necessarily reliable, depending on the camera, scanner, phone, or other device that that encoded the image. If an array name is included, and if the function's return value is greater than 0, the array elements are:   1 width in pixels   2 height in pixels   3 'date taken' (if present) in 'yyyy:mm:dd hh:mm:ss' format
\Fpidinfo(n)	int	Given Process ID (PID) n, checks if process exists
\Fradix(n1,n2,n3)	int	Converts number n1 from radix n2 to radix n3
\Frandom(n)	int	Returns a random integer between 0 and n-1
\Frawcommand(s)	txt	Returns output from system command s without stripping final newline
\Frdirectories(s,&a)	int,array	Recursive directory list is returned array &a
\Frecurse(s)	txt	Returns string s with any and all variables evaluated recursively
\Frepeat(s,n)	txt	Returns a string composed of n repetitions of s
\Freplace(s1,s2,s3,n)	txt	In string s1 replace nth occurrence of s2 with s3; if n=0, replace all.
\Freverse(s)	txt	Returns string s reversed
\Frfiles(s,&a)	int,array	Recursive file list is returned array &a
\Fright(s,n)	txt	Returns rightmost n characters of txt
\Frindex(s1,s2,n)	int	Position of rightmost instance of s1 in s2 ignoring rightmost n characters
\Frpad(s,n,c)	txt	Returns s right-padded to length n with character c
\Frsearch(s1,s2,n1,n2)	int	Pattern (wildcard) string search from right.
\Fsearch(s1,s2,n1,n2)	int	Pattern (wildcard) string search from left.
\Fsexpression(s)	any	Returns the result of evaluating S-Expression s
\Fsize(fn)	int	Size of file fn in bytes
\Fspan(s1,s2)	txt	s1 up to 1st char that is not in s2
\Fsplit(s1,&a,s2,s3,n1,n2)	int,array	Splits elements of a text string (e.g. comma-separated list) into array &a
\Fsqueeze(s)	txt	Removes extra whitespace from string s
\Fstrcmp(s1,s2,n1,n2,n3)	int	Compares strings s1 and s2
\Fstringtype(s)	txt	Tells whether string s is 7-bit, 8-bit, or UTF-8 text, or binary.
\Fstripb(s,c1,c2)	txt	Strips enclosing parens, brackets, braces, or quotes from string s
\Fstripn(s,n)	txt	Strips n characters from the end of string s
\Fstripx(s,c)	txt	Strips string s up to the rightmost occurrence of character c
\Fsubstitute(s1,s2,s3)	txt	Substitute characters in string s1 according strings s2 and s3
\Fsubstring(s,n1,n2)	txt	Returns the part of string s starting at position n1, length n2
Compact substring notation ... A shorter and more flexible approach to substrings:
\s(name[n:m])	Substring of \m(name) starting at position n, length m
\s(name[n_m])	Substring of \m(name) from position n to position m
\s(name[n]) or \s(name[n:])	Substring of \m(name) from position n to the end
\s(name[n.])	The character at position n
\Ftablelook(s,&a,c)	int	Looks up tag in array of tag=value pairs, c = separator
\Ftime(date-time)	hh:mm:ss	Extracts the time from a free-format date-time string
\Ftodtosecs(hh:mm:ss)	int	Converts time of day to seconds since midnight
\Ftrim(s1,s2)	txt	s1 with all chars from s2 trimmed from the right.
\Funhexify(s)	txt	Decodes hexadecimal string s Note: this does not convert hex numbers to decimal; use \fradix() for that.
\Funixtodospath(s)	txt	Unix pathname s is converted to DOS/Windows format
\Funtabify(s)	txt	Converts Tabs in s to spaces, assuming tab stops every 8 spaces
\Fupper(s1)	txt	Letters in s1 converted to uppercase
\Futcdate(s)	txt	Free-format date-time s converted to UTC (GMT) yyyymmdd hh:mm:ss
\Fverify(s1,s2,n)	int	Pos of 1st char in s2 starting at n that's not also in s1
\Fword(s1,n1,s2,s3,n2,n3))	txt	Extracts word number n1 from string s1, many options
File Input/Output functions [see documentation]
\F_eof(n)	int	Returns 1 if channel n file pointer is at at end of file, 0 otherwise
\F_errmsg(n)	txt	Converts error code to associated error message text string
\F_getblock(n1,n2)	txt	Reads a block of n2 characters from channel n1 and returns it
\F_getchar(n)	chr	Reads one character from file open on channel n
\F_getline(n)	txt	Reads a line of text from file open on channel n
\F_handle(n)	int	Returns operating system's file handle for file open on channel n
\F_line(n)	int	Returns the current line number for the file open on channel n
\F_pos(n)	int	Returns the current character position for the file open on channel n
\F_putblock(n,s)	int	Writes string(s) to the file open on channel n
\F_putchar(n,c)	int	Writes character c to the file open on channel n
\F_putblock(n,s)	int	Write string(s) to the file open on channel n
\F_putline(n,s)	int	Like \F_putblock() but adds a line terminator
\F_status(n)	int	Returns open modes for channel n
Floating-point functions... many are superfluous since S-Expressions were added in C-Kermit 8.0
\Ffpabsolute(fp,d)	fp	Returns absolute value of floating-point number fp to d decimal places
\Ffpadd(fp1,fp2,d))	fp	Returns sum of two floating-point numbers rounded to d decimal places
\Ffpcosine(f1,d)	fp	The cosine of angle f1 (in radians) to d decimal places
\Ffpdivide(f1,f2,d)	fp	Floating-point result of f1 divided by f2 to d places
\Ffpexp(f1,d)	fp	e (the base of natural logarithms) raised to the f1 power, to d places.
\Ffpint(f1)	int	The integer part of f1
\Ffplog10(f1,d)	fp	The base 10 logarithm of f1 to d places
\Ffplogn(f1,d)	fp	The natural logarithm of f1 to d places
\Ffpmaximum(f1,f2,d)	fp	The maximum f1 and f2 to d places
\Ffpminimum(f1,f2,d)	fp	The minimum f1 and f2 to d places
\Ffpmodulus(f1,f2,d)	fp	The modulus f1 and f2 to d places
\Ffpmultiply(f1,f2,d)	fp	The product f1 and f2 to d places
\Ffpraise(f1,f2,d)	fp	f1 raised to the power f2 to d places
\Ffpround((f1,d)	fp	f1 rounded to d decimal places
\Ffpsine(f1,d)	fp	The sine of angle f1 (in radians) to d decimal places
\Ffpsqrt(f1,d)	fp	The square root of f1 to d decimal places
\Ffpsubtract(fp1,fp2,d)	fp	f1 minus f2 to d places
\Ffptangent(f1,d)	fp	The tangent of angle f1 (in radians) to d decimal places