Hooks - GNU Emacs Lisp Reference Manual

A hook is a variable where you can store a function or functions to be called on a particular occasion by an existing program. Emacs provides hooks for the sake of customization. Most often, hooks are set up in the init file (see Init File), but Lisp programs can set them also. See Standard Hooks, for a list of standard hook variables.

Most of the hooks in Emacs are normal hooks. These variables contain lists of functions to be called with no arguments. By convention, whenever the hook name ends in “-hook”, that tells you it is normal. We try to make all hooks normal, as much as possible, so that you can use them in a uniform way.

Every major mode function is supposed to run a normal hook called the mode hook as the one of the last steps of initialization. This makes it easy for a user to customize the behavior of the mode, by overriding the buffer-local variable assignments already made by the mode. Most minor mode functions also run a mode hook at the end. But hooks are used in other contexts too. For example, the hook suspend-hook runs just before Emacs suspends itself (see Suspending Emacs).

The recommended way to add a hook function to a normal hook is by calling add-hook (see below). The hook functions may be any of the valid kinds of functions that funcall accepts (see What Is a Function). Most normal hook variables are initially void; add-hook knows how to deal with this. You can add hooks either globally or buffer-locally with add-hook.

If the hook variable's name does not end with “-hook”, that indicates it is probably an abnormal hook. That means the hook functions are called with arguments, or their return values are used in some way. The hook's documentation says how the functions are called. You can use add-hook to add a function to an abnormal hook, but you must write the function to follow the hook's calling convention.

By convention, abnormal hook names end in “-functions” or “-hooks”. If the variable's name ends in “-function”, then its value is just a single function, not a list of functions.

Here's an example that uses a mode hook to turn on Auto Fill mode when in Lisp Interaction mode:

At the appropriate time, Emacs uses the run-hooks function to run particular hooks.

— Function: run-hooks &rest hookvars

This function takes one or more normal hook variable names as arguments, and runs each hook in turn. Each argument should be a symbol that is a normal hook variable. These arguments are processed in the order specified.
If a hook variable has a non-nil value, that value should be a list of functions. run-hooks calls all the functions, one by one, with no arguments.
The hook variable's value can also be a single function—either a lambda expression or a symbol with a function definition—which run-hooks calls. But this usage is obsolete.

— Function: run-hook-with-args hook &rest args

This function is the way to run an abnormal hook and always call all of the hook functions. It calls each of the hook functions one by one, passing each of them the arguments args.

— Function: run-hook-with-args-until-failure hook &rest args

This function is the way to run an abnormal hook until one of the hook functions fails. It calls each of the hook functions, passing each of them the arguments args, until some hook function returns nil. It then stops and returns nil. If none of the hook functions return nil, it returns a non-nil value.

— Function: run-hook-with-args-until-success hook &rest args

This function is the way to run an abnormal hook until a hook function succeeds. It calls each of the hook functions, passing each of them the arguments args, until some hook function returns non-nil. Then it stops, and returns whatever was returned by the last hook function that was called. If all hook functions return nil, it returns nil as well.

— Function: add-hook hook function &optional append local

This function is the handy way to add function function to hook variable hook. You can use it for abnormal hooks as well as for normal hooks. function can be any Lisp function that can accept the proper number of arguments for hook. For example,
          (add-hook 'text-mode-hook 'my-text-hook-function)
     
adds my-text-hook-function to the hook called text-mode-hook.
If function is already present in hook (comparing using equal), then add-hook does not add it a second time.
It is best to design your hook functions so that the order in which they are executed does not matter. Any dependence on the order is “asking for trouble.” However, the order is predictable: normally, function goes at the front of the hook list, so it will be executed first (barring another add-hook call). If the optional argument append is non-nil, the new hook function goes at the end of the hook list and will be executed last.
add-hook can handle the cases where hook is void or its value is a single function; it sets or changes the value to a list of functions.
If local is non-nil, that says to add function to the buffer-local hook list instead of to the global hook list. If needed, this makes the hook buffer-local and adds t to the buffer-local value. The latter acts as a flag to run the hook functions in the default value as well as in the local value.

— Function: remove-hook hook function &optional local

This function removes function from the hook variable hook. It compares function with elements of hook using equal, so it works for both symbols and lambda expressions.
If local is non-nil, that says to remove function from the buffer-local hook list instead of from the global hook list.

23.1 Hooks