search-buffer(2)

NAME

search-buffer - Search the current buffer for a string

SYNOPSIS

n search-buffer "flags" "string"

DESCRIPTION

search-buffer searches for a string from the current cursor position, in a forwards or backwards direction, to the end or start of the buffer, respectively. The search direction and mode is specified by the by flags argument.

The search-buffer command is designed to be used from the macro language rather than the command line as the search may be defined independently of the buffer setting of magic(2m) mode, which allows regular expression pattern matching, or exact(2m) mode, which makes the search case sensitive. The flags argument is used to explicitly set the magic(2m) and exact(2m) search modes.

The flags argument is defined as a character string which defines the search behavior:

b - backward search


Specifies the direction of the search as backwards, when omitted then a forward search is performed.

e - enable exact search


A exact(2m) mode search is performed, the characters are matched case sensitively.

E - disable exact search


A exact(2m) mode search is not performed, the characters are matched case insensitively.

m - enable magic


A magic(2m) mode search is performed, the search string is interpreted as a regular expression.

M - disable magic


A magic(2m) mode search is not performed, the search string is searched for literally.

When the flags are not specified then the default behavior is to search in a forwards direction inheriting the exact(2m) and magic(2m) modes of the buffer. Within macros it is suggested that the search modes are explicitly specified unless the buffer modes are to be inherited.

The numeric argument n is interpreted in the same way as a search-forward(2) command, except when 0 is given:

n > 0


The nth occurrence of the string is located.

n = 0


All occurrences of the string, from the current location, are counted and returned in $result(5). The cursor is left at the location of the last occurrence.

n < 0


The first occurrence of the string is located in the next n lines.

DIAGNOSTICS

The command returns a status of FALSE if the string could not be located (or nth string where n occurrences are requested). If the string is found within the given search criteria the return status is TRUE.

EXAMPLE

The following examples show the use of the search-buffer command. The search-buffer is usually used with the !force(4) directive which traps any FALSE return status and may be subsequently tested using the !if(4) directive on the status $status(5) variable. If the !force directive is omitted then the macro will abort with a failure status if the search fails (sometimes this behavior may be required).

Case sensitive search forward for the word "foo", this is not a magic regular expression.

!force search-buffer "eM" "foo" 
!if $status 
    ; found string 
!else 
    ; not found 
!endif 

Case sensitive search bacward for the word "foo", this is not a magic regular expression.

search-buffer "beM" "foo" 

Regular expression search forward for `<' or `>'.

search-buffer "m" "[<>]" 

Regular expression search catching the regular expression. A[a-z]*. The macro variable @s1 returns the regular expression string that has been found.

!force search-buffer "em" "\\(A[a-z]*\\)" 
!if $status 
    ; found string 
    1000 ml-write &spr "Found string '%s'" @s1 
!else 
    ; not found 
!endif 

NOTES

Search-buffer was added in November 2004 to simplify macro writing and to speed up macro execution. It replaces the macro commands regex-forward(3) and regex-backward(3). The command simplifies macro development by allowing the exact(2m) and magic(2m) modes to be specified on the command line, this ensures that the buffer mode does not need to be saved, set and then restored in order to modify the behaviour of a search operation.

SEE ALSO

buffer-mode(2), exact(2m), hunt-backward(2), hunt-forward(2), isearch-forward(2), narrow-search-forward(3), magic(2m), replace-string(2), search-backward(2), search-forward(2), $result(5).
Regular Expressions

Ref: search-buffer(2) File: m2cmd019.2 Date: 2026/01/26

(c) Copyright JASSPA 2026