この関数は、現在のバッファにおいて位置 pos
に文字を含むすべてのオーバーレイのリストを返します。sorted が nil でない場合、返されるリストは優先度の降順となり、そうでない場合は特に順序はありません。オーバーレイが
pos 以降に始まり、かつ pos
より後に終わる場合、そのオーバーレイは pos の文字を含みます。
使い方の例として、ポイントにある文字のプロパティ prop を指定するオーバーレイのリストを返す Lisp 関数を以下に示します。
(defun find-overlays-specifying (prop)
(let ((overlays (overlays-at (point)))
found)
(while overlays
(let ((overlay (car overlays)))
(if (overlay-get overlay prop)
(setq found (cons overlay found))))
(setq overlays (cdr overlays)))
found))
空のオーバーレイ（空のオーバーレイを参照）には文字が含まれていないため、この関数はそれらを返しません。空のオーバーレイが必要な場合は、代わりに後述する
overlays-in を使用してください。
なお、pos がナローイングの範囲外にある場合、この関数は現在のバッファのナローイング範囲外のオーバーレイを返すことがあります（Narrowing を参照）。
この関数は、領域 beg から end までと重なるオーバーレイの一覧を返します。オーバーレイが領域と重なるとは、そのオーバーレイに beg から end までの文字が1つ以上含まれている場合を指し、end の位置にある（すなわちそれ以降の）文字は除外されます。
空のオーバーレイには文字が含まれないため、それらを含めるためのルールが異なります。具体的には、begにある場合、endを除いたbegとendの厳密な間にある場合、あるいはendがバッファ末尾の位置を示す場合にendにある場合に、オーバーラップしているとみなされます。（バッファ末尾における空のオーバーレイを特別に扱うのは、そのようなオーバーレイを検出して処理できるようにするためです。endにそれ以外の値が設定されている場合は、代わりにendの位置をインクリメントできます。）なお、begとendが同じ位置である場合、begにある空のオーバーレイはendにも位置することになるため、このケースはバッファ末尾にある空のオーバーレイとある程度似ています。
返されるリストにおけるオーバーレイの表示順は不定です。
なお、beg および/または end がバッファの現在の狭域範囲外にある場合、この関数は現在の狭域範囲外のオーバーレイを返す可能性があることに注意してください。
この関数は、pos
の次にあるオーバーレイの開始位置または終了位置のバッファ位置を返します。該当するものがない場合は、(point-max) を返します。
この関数は、pos
より前のオーバーレイの直前の開始位置または終了位置のバッファ位置を返します。該当する位置がない場合は、(point-min) を返します。
例として、プリミティブ関数 next-single-char-property-change
の簡略版（かつ非効率な実装）を以下に示します（テキストプロパティ検索関数を参照）。この関数は、位置 pos から前方を検索し、オーバーレイまたはテキストプロパティのいずれかから取得した特定のプロパティ prop の値が変更される次の位置を探します。
(defun next-single-char-property-change (position prop)
(save-excursion
(goto-char position)
(let ((propval (get-char-property (point) prop)))
(while (and (not (eobp))
(eq (get-char-property (point) prop) propval))
(goto-char (min (next-overlay-change (point))
(next-single-property-change (point) prop)))))
(point)))