# findstr, substr and getfield explainer > Run F5's findstr, substr or getfield on your string and see the match, the skip, the terminator and the result marked on a ruler, next to the plain Tcl that does the same job. Cases F5 does not document are flagged. Local, no network. - Tool: https://ronutz.com/en/tools/f5-irules-string-extract - Family: Networking --- ## What it does `findstr`, `substr` and `getfield` are commands F5 adds to iRules for cutting a piece out of a value. The tool runs the one you pick on your string and marks the result on a ruler: the search string found, the characters skipped, the terminator, the separators and the field returned. Beside it, the plain Tcl that does the same job runs in the same engine, so you can see whether the two really agree. ## The three commands - `findstr string search ?skip? ?terminator?` finds `search`, moves `skip` characters on from the start of the match, then returns up to the terminator. F5's example: `findstr "" "@" 1 ">"` returns `sip.example.com`. - `substr string skip ?terminator?` starts at index `skip`, where 0 is the first character. `substr "abcdefghijklm" 2 "gh"` returns `cdef`. - `getfield string separator field` splits at every occurrence of the separator, which can be one character or a string, and returns that field, counting from 1. For `findstr` and `substr`, a terminator that is a number is a length (up to that many characters, fewer when the string ends first); any other terminator is text to stop before. All of F5's published examples for these commands are reproduced exactly by the tool's tests. ## What F5 does not document Where F5's pages are silent, the tool states the assumption it made, marked "Not documented by F5": - `findstr` when the search string is absent. The tool returns an empty string. F5 calls `findstr` equivalent to `string range` with `string first`, but that equivalent returns the whole string in this case, so the two descriptions cannot both be right. - A count of 0. F5's rule ("that many characters") would return nothing, but F5's own `substr` example with 0 returns the rest of the string; the tool follows the example, and a contributor note on F5's API reference page reports that 0 did not work on 11.5.4 and 11.6.0. - A skip past the end, a negative skip or count, an empty terminator, and a `getfield` field number outside the fields. Check these cases on a BIG-IP before relying on them. ## Sources - [F5 tmsh reference: findstr](https://clouddocs.f5.com/cli/tmsh-reference/latest/modules/ltm/ltm_rule_command_findstr.html) (read 2026-10-03) - [F5 tmsh reference: substr](https://clouddocs.f5.com/cli/tmsh-reference/latest/modules/ltm/ltm_rule_command_substr.html) (read 2026-10-03) - [F5 tmsh reference: getfield](https://clouddocs.f5.com/cli/tmsh-reference/latest/modules/ltm/ltm_rule_command_getfield.html) (read 2026-10-03) - [F5 iRules reference: substr, with the contributor note on the 0 count](https://clouddocs.f5.com/api/irules/substr.html) (read 2026-10-02) - [Tcl 8.4 manual: string](https://www.tcl-lang.org/man/tcl8.4/TclCmd/string.htm) (read 2026-10-03) ## Standards and references - [F5 tmsh reference: findstr](https://clouddocs.f5.com/cli/tmsh-reference/latest/modules/ltm/ltm_rule_command_findstr.html) - findstr syntax, skip_count and terminator rules, and the two published examples the vectors reproduce - [F5 tmsh reference: substr](https://clouddocs.f5.com/cli/tmsh-reference/latest/modules/ltm/ltm_rule_command_substr.html) - substr syntax, the count and terminator rules, and the five published examples the vectors reproduce - [F5 tmsh reference: getfield](https://clouddocs.f5.com/cli/tmsh-reference/latest/modules/ltm/ltm_rule_command_getfield.html) - getfield syntax: field numbers start at 1 and the separator may be a character or a string - [F5 iRules reference: substr (API reference page)](https://clouddocs.f5.com/api/irules/substr.html) - the same examples, with a contributor note that the 0 count did not work for them on 11.5.4 and 11.6.0 - [F5 K6091: The version of Tcl used to develop iRules](https://my.f5.com/manage/s/article/K6091) - the iRules command set was developed from Tcl base version 8.4.6, which is used in all BIG-IP versions; the engine models that version - [Tcl 8.4 manual: string](https://www.tcl-lang.org/man/tcl8.4/TclCmd/string.htm) - the subcommands, index forms (integer, end, end-N), map ordering and its single pass, compare and bytelength - [Tcl 8.4.6 source code, tag core-8-4-6 on GitHub](https://github.com/tcltk/tcl/tree/core-8-4-6) - the reference interpreter: the engine was differential-tested against tclsh built from this tag (commit bf3eeadc) ## Related reading - [findstr, substr and getfield: what F5 documents, and what it leaves open](https://ronutz.com/en/learn/irules-findstr-substr-getfield.md): F5 adds three commands to iRules for cutting a piece out of a value. findstr finds and skips, substr starts at an index, getfield splits on a separator, and two of them take a terminator that is either a length or a stop text. Here is each rule with F5's own examples, the plain Tcl that does the same job, and the cases F5's pages do not settle. - [scan in iRules: taking values apart without regular expressions](https://ronutz.com/en/learn/irules-scan-command.md): F5's own reference recommends string commands such as scan over regular expressions. scan is short and fast, but its result counts conversions rather than matches, -1 and 0 mean different things, and Tcl 8.4.6 stores integers through a 32-bit C int. Here is how to read a format, and the checks that make a scan reliable. - [Tcl string commands in iRules: indexes, map, match, compare and trim](https://ronutz.com/en/learn/irules-string-commands.md): The string command does most of the text work in an iRule, and each subcommand has one rule people get wrong: indexes that read 010 as octal, a map that is a single pass, a trim that removes a set of characters rather than a word, and a compare that puts every capital before every lower-case letter. - [Zero or one: where BIG-IP starts counting](https://ronutz.com/en/learn/bigip-zero-or-one.md): Tcl counts from 0, several commands F5 adds count from 1, counters return 1 for the first item, many zeros in the configuration are values rather than positions, and the same path segment is element 1, field 2 or index 1 depending on who is asking. Here is where each one comes from, in F5's own words, with the traps and the places where F5's pages disagree with themselves.