These functions allow users to set actions to be taken before packages are attached/detached and namespaces are (un)loaded.
getHook(hookName) setHook(hookName, value, action = c("append", "prepend", "replace"))
packageEvent(pkgname, event = c("onLoad", "attach", "detach", "onUnload"))
character string: the hook name
character string: the package/namespace name
character string: an event for the package. Can be abbreviated.
A function or a list of functions, or for
action = "replace",
The action to be taken. Can be abbreviated.
getHook function, a list of functions (possibly empty).
setHook function, no return value.
packageEvent, the derived hook name (a character string).
setHook provides a general mechanism for users to register
hooks, a list of functions to be called from system (or user)
functions. The initial set of hooks was associated with events on
packages/namespaces: these hooks are named via calls to
To remove a hook completely, call
setHook(hookName, NULL, "replace").
When an R package is attached by
library or loaded by
other means, it can call initialization code. See
.onLoad for a description of the package hook functions
called during initialization. Users can add their own initialization
code via the hooks provided by
setHook(), functions which will
be called as
funname(pkgname, pkgpath) inside a
The sequence of events depends on which hooks are defined, and whether a package is attached or just loaded. In the case where all hooks are defined and a package is attached, the order of initialization events is as follows:
The package namespace is loaded.
.onLoad function is run.
If S4 methods dispatch is on, any actions set by
setLoadAction are run.
The namespace is sealed.
"onLoad" hook is run.
The package is added to the search path.
.onAttach function is run.
The package environment is sealed.
"attach" hook is run.
A similar sequence (but in reverse) is run when a package is detached and its namespace unloaded:
"detach" hook is run.
.Last.lib function is run.
The package is removed from the search path.
"onUnload" hook is run.
.onUnload function is run.
The package namespace is unloaded.
Note that when an R session is finished, packages are not detached and namespaces are not unloaded, so the corresponding hooks will not be run.
Also note that some of the user hooks are run without the package being on the search path, so in those hooks objects in the package need to be referred to using the double (or triple) colon operator, as in the example.
If multiple hooks are added, they are normally run in the order shown
getHook, but the
are run in reverse order so the default for package events is to add
hooks ‘inside’ existing ones.
The hooks are stored in the environment
.userHooksEnv in the
base package, with ‘mangled’ names.
for a discussion of the double and triple colon operators.