[thirdparty/man-pages.git] / man2 / init_module.2

.\" Copyright (C) 1996 Free Software Foundation, Inc.
.\" This file is distributed according to the GNU General Public License.
.\" See the file COPYING in the top level source directory for details.
.\"
.\" 2006-02-09, some reformatting by Luc Van Oostenryck; some
.\" reformatting and rewordings by mtk
.\"
.TH INIT_MODULE 2 2006-02-09 "Linux" "Linux Programmer's Manual"
.SH NAME
init_module \- initialize a loadable module entry
.SH SYNOPSIS
.nf
.B #include <linux/module.h>
.sp
.BI "int init_module(const char *" name ", struct module *" image );
.fi
.SH DESCRIPTION
.BR init_module ()
loads the relocated module image into kernel space and runs the
module's
.I init
function.
.PP
The module image begins with a module structure and is followed by
code and data as appropriate.
The module structure is defined as follows:
.PP
.in +4n
.nf
struct module {
    unsigned long         size_of_struct;
    struct module        *next;
    const char           *name;
    unsigned long         size;
    long                  usecount;
    unsigned long         flags;
    unsigned int          nsyms;
    unsigned int          ndeps;
    struct module_symbol *syms;
    struct module_ref    *deps;
    struct module_ref    *refs;
    int                 (*init)(void);
    void                (*cleanup)(void);
    const struct exception_table_entry *ex_table_start;
    const struct exception_table_entry *ex_table_end;
#ifdef __alpha__
    unsigned long gp;
#endif
};
.fi
.in
.PP
All of the pointer fields, with the exception of
.I next
and
.IR refs ,
are expected to point within the module body and be
initialized as appropriate for kernel space, that is, relocated with
the rest of the module.
.PP
This system call requires privilege.
.SH "RETURN VALUE"
On success, zero is returned.
On error, \-1 is returned and
.I errno
is set appropriately.
.SH ERRORS
.TP
.B EBUSY
The module's initialization routine failed.
.TP
.B EFAULT
.I name
or
.I image
is outside the program's accessible address space.
.TP
.B EINVAL
Some
.I image
slot is filled in incorrectly,
.I image\->name
does not correspond to the original module name, some
.I image\->deps
entry does not correspond to a loaded module,
or some other similar inconsistency.
.TP
.B ENOENT
No module by that name exists.
.TP
.B EPERM
The caller was not privileged
(did not have the
.B CAP_SYS_MODULE
capability).
.SH "CONFORMING TO"
.BR init_module ()
is Linux-specific.
.SH "SEE ALSO"
.BR create_module (2),
.BR delete_module (2),
.BR query_module (2)
Commit	Line	Data
c4d4162c MK	1	.\" Copyright (C) 1996 Free Software Foundation, Inc.
	2	.\" This file is distributed according to the GNU General Public License.
	3	.\" See the file COPYING in the top level source directory for details.
	4	.\"
c13182ef	5	.\" 2006-02-09, some reformatting by Luc Van Oostenryck; some
c4d4162c MK	6	.\" reformatting and rewordings by mtk
c4d4162c MK	7	.\"
e127c16a	8	.TH INIT_MODULE 2 2006-02-09 "Linux" "Linux Programmer's Manual"
c4d4162c MK	9	.SH NAME
	10	init_module \- initialize a loadable module entry
	11	.SH SYNOPSIS
	12	.nf
	13	.B #include <linux/module.h>
	14	.sp
	15	.BI "int init_module(const char " name ", struct module " image );
	16	.fi
	17	.SH DESCRIPTION
	18	.BR init_module ()
	19	loads the relocated module image into kernel space and runs the
	20	module's
	21	.I init
	22	function.
	23	.PP
	24	The module image begins with a module structure and is followed by
	25	code and data as appropriate.
	26	The module structure is defined as follows:
	27	.PP
a6e2f128	28	.in +4n
c4d4162c MK	29	.nf
	30	struct module {
	31	unsigned long size_of_struct;
	32	struct module *next;
	33	const char *name;
	34	unsigned long size;
	35	long usecount;
	36	unsigned long flags;
	37	unsigned int nsyms;
	38	unsigned int ndeps;
	39	struct module_symbol *syms;
	40	struct module_ref *deps;
	41	struct module_ref *refs;
	42	int (*init)(void);
	43	void (*cleanup)(void);
	44	const struct exception_table_entry *ex_table_start;
	45	const struct exception_table_entry *ex_table_end;
	46	#ifdef __alpha__
	47	unsigned long gp;
	48	#endif
	49	};
	50	.fi
a6e2f128	51	.in
c4d4162c MK	52	.PP
	53	All of the pointer fields, with the exception of
	54	.I next
	55	and
	56	.IR refs ,
	57	are expected to point within the module body and be
75b94dc3	58	initialized as appropriate for kernel space, that is, relocated with
c4d4162c MK	59	the rest of the module.
	60	.PP
	61	This system call requires privilege.
	62	.SH "RETURN VALUE"
c13182ef MK	63	On success, zero is returned.
c13182ef MK	64	On error, \-1 is returned and
c4d4162c MK	65	.I errno
	66	is set appropriately.
	67	.SH ERRORS
	68	.TP
	69	.B EBUSY
	70	The module's initialization routine failed.
	71	.TP
	72	.B EFAULT
	73	.I name
	74	or
	75	.I image
	76	is outside the program's accessible address space.
	77	.TP
	78	.B EINVAL
	79	Some
	80	.I image
	81	slot is filled in incorrectly,
94e9d9fe	82	.I image\->name
c4d4162c	83	does not correspond to the original module name, some
94e9d9fe	84	.I image\->deps
c13182ef	85	entry does not correspond to a loaded module,
c4d4162c MK	86	or some other similar inconsistency.
	87	.TP
	88	.B ENOENT
	89	No module by that name exists.
	90	.TP
	91	.B EPERM
	92	The caller was not privileged
	93	(did not have the
	94	.B CAP_SYS_MODULE
	95	capability).
	96	.SH "CONFORMING TO"
	97	.BR init_module ()
8382f16d	98	is Linux-specific.
c4d4162c MK	99	.SH "SEE ALSO"
	100	.BR create_module (2),
	101	.BR delete_module (2),
	102	.BR query_module (2)