'\" te
.\" Copyright (c) 2008, Sun Microsystems, Inc., All Rights Removed
.TH mod_install 9F "8 Jul 2008" "SunOS 5.11" "Kernel Functions for Drivers"
.SH NAME
mod_install, mod_remove, mod_info, mod_modname \- add, remove or query a loadable module
.SH SYNOPSIS
.LP
.nf
#include <sys/modctl.h>

\fBint\fR \fBmod_install\fR(\fBstruct modlinkage *\fR\fImodlinkage\fR);
.fi

.LP
.nf
\fBint\fR \fBmod_remove\fR(\fBstruct modlinkage *\fR\fImodlinkage\fR);
.fi

.LP
.nf
\fBint\fR \fBmod_info\fR(\fBstruct modlinkage *\fR\fImodlinkage\fR, 
     \fBstruct modinfo *\fR\fImodinfo\fR);
.fi

.LP
.nf
\fBconst\fR \fBchar *\fR\fImod_modname\fR(\fBstruct modlinkage *\fR\fImodlinkage\fR);
.fi

.SH INTERFACE LEVEL
.sp
.LP
Solaris DDI specific (Solaris DDI).
.SH PARAMETERS
.sp
.ne 2
.mk
.na
\fB\fImodlinkage\fR\fR
.ad
.RS 14n
.rt  
Pointer to the loadable module's \fBmodlinkage\fR structure which describes what type(s) of module elements are included in this loadable module.
.RE

.sp
.ne 2
.mk
.na
\fB\fImodinfo\fR\fR
.ad
.RS 14n
.rt  
Pointer to the \fBmodinfo\fR structure passed to \fB_info\fR(9E). 
.RE

.SH DESCRIPTION
.sp
.LP
\fBmod_install()\fR must be called from a module's \fB_init\fR(9E) routine.
.sp
.LP
\fBmod_remove()\fR must be called from a module's \fB_fini\fR(9E) routine.
.sp
.LP
\fBmod_info()\fR must be called from a module's \fB_info\fR(9E) routine.
.sp
.LP
\fBmod_modname()\fR can be called from any module routine.
.sp
.LP
When \fB_init\fR(9E) is executing, its call to \fBmod_install()\fR enables other threads to call \fBattach\fR(9E) even prior to \fBmod_install()\fR returning and \fB_init\fR(9E) completion. From a programming standpoint this means that all \fB_init\fR(9E) initialization must occur prior to \fB_init\fR(9E) calling \fBmod_install()\fR. If \fBmod_install()\fR fails (non-zero return value), any initialization must be undone. 
.sp
.LP
When \fB_fini\fR(9E) is executing, another thread may call \fBattach\fR(9E) prior to \fB_fini\fR(9E) calling \fBmod_remove()\fR. If this occurs, the \fBmod_remove()\fR fails (non-zero return). From a programming standpoint, this means that \fB_init\fR(9E) initilizations should only be undone after a successful return from \fBmod_remove()\fR.
.sp
.LP
To query the name of a module, use \fBmod_modname()\fR. If the module is a driver, the module name is the same as the driver name. This function can be used to avoid compiled-in knowledge of the module name, and is of particular use when \fB_init\fR(9E) needs to call a function like \fBkstat_create\fR(9F).
.SH RETURN VALUES
.sp
.LP
\fBmod_install()\fR and \fBmod_remove()\fR return \fB0\fR upon success and non-zero on failure. 
.sp
.LP
\fBmod_info()\fR returns a non-zero value on success and  \fB0\fR upon failure.
.sp
.LP
\fBmod_modname()\fR returns the name of the module. The returned name remains valid as long as the module remains loaded.
.SH EXAMPLES
.sp
.LP
See \fB_init\fR(9E) for an example that uses these functions.
.SH SEE ALSO
.sp
.LP
\fB_fini\fR(9E), \fB_info\fR(9E), \fB_init\fR(9E), \fBkstat_create\fR(9F), \fBmodldrv\fR(9S), \fBmodlinkage\fR(9S), \fBmodlstrmod\fR(9S) 
.sp
.LP
\fIWriting Device Drivers for Oracle Solaris 11.2\fR