From c4d4162c93ec6d0ab8196cf8f6092e9967350747 Mon Sep 17 00:00:00 2001 From: Michael Kerrisk Date: Thu, 9 Feb 2006 19:32:36 +0000 Subject: [PATCH] Modified versions of old GPL pages on kernel modules API. --- man2/create_module.2 | 58 ++++++++++++++ man2/delete_module.2 | 56 ++++++++++++++ man2/get_kernel_syms.2 | 71 ++++++++++++++++++ man2/init_module.2 | 101 +++++++++++++++++++++++++ man2/query_module.2 | 167 +++++++++++++++++++++++++++++++++++++++++ 5 files changed, 453 insertions(+) create mode 100644 man2/create_module.2 create mode 100644 man2/delete_module.2 create mode 100644 man2/get_kernel_syms.2 create mode 100644 man2/init_module.2 create mode 100644 man2/query_module.2 diff --git a/man2/create_module.2 b/man2/create_module.2 new file mode 100644 index 000000000..92dcbddb4 --- /dev/null +++ b/man2/create_module.2 @@ -0,0 +1,58 @@ +.\" 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 CREATE_MODULE 2 "2002" Linux "Linux Module Support" +.SH NAME +create_module \- create a loadable module entry +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "caddr_t create_module(const char *" name ", size_t " size ); +.fi +.SH DESCRIPTION +.BR create_module () +attempts to create a loadable module entry and reserve the kernel memory +that will be needed to hold the module. +This system call requires privilege. +.SH "RETURN VALUE" +On success, returns the kernel address at which the module will reside. +On error \-1 is returned and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EEXIST +A module by that name already exists. +.TP +.B EFAULT +.I name +is outside the program's accessible address space. +.TP +.B EINVAL +The requested size is too small even for the module header information. +.TP +.B ENOMEM +The kernel could not allocate a contiguous block of memory large +enough for the module. +.TP +.B EPERM +The caller was not privileged +(did not have the +.B CAP_SYS_MODULE +capability). +.SH "CONFORMING TO" +.BR create_module () +is Linux specific. +.SH NOTES +This system call is only present on Linux up until kernel 2.4; +it was removed in Linux 2.6. +.\" Removed in Linux-2.5.48 +.SH "SEE ALSO" +.BR init_module (2), +.BR delete_module (2), +.BR query_module (2) diff --git a/man2/delete_module.2 b/man2/delete_module.2 new file mode 100644 index 000000000..eba70f95b --- /dev/null +++ b/man2/delete_module.2 @@ -0,0 +1,56 @@ +.\" 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 DELETE_MODULE 2 "2002" Linux "Linux Module Support" +.SH NAME +delete_module \- delete a loadable module entry +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int delete_module(const char *" name ); +.fi +.SH DESCRIPTION +.BR delete_module () +attempts to remove an unused loadable module entry. +If +.I name +is NULL, +all unused modules marked auto-clean will be removed. +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 is in use. +.TP +.B EFAULT +.I name +is outside the program's accessible address space. +.TP +.B EINVAL +.I name +was an empty string. +.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 delete_module () +is Linux specific. +.SH "SEE ALSO" +.BR create_module (2), +.BR init_module (2), +.BR query_module (2) diff --git a/man2/get_kernel_syms.2 b/man2/get_kernel_syms.2 new file mode 100644 index 000000000..37c1bc1d3 --- /dev/null +++ b/man2/get_kernel_syms.2 @@ -0,0 +1,71 @@ +.\" 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 GET_KERNEL_SYMS 2 "2002" Linux "Linux Module Support" +.SH NAME +get_kernel_syms \- retrieve exported kernel and module symbols +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int get_kernel_syms(struct kernel_sym *" table ); +.fi +.SH DESCRIPTION +If +.I table +is NULL, +.BR get_kernel_syms () +returns the number of symbols available for query. +Otherwise it fills in a table of structures: +.PP +.RS +.nf +struct kernel_sym { + unsigned long value; + char name[60]; +}; +.fi +.RE +.PP +The symbols are interspersed with magic symbols of the form +.BI # module-name +with the kernel having an empty name. +The value associated with a symbol of this form is the address at +which the module is loaded. +.PP +The symbols exported from each module follow their magic module tag +and the modules are returned in the reverse of the +order in which they were loaded. +.SH "RETURN VALUE" +Returns the number of symbols copied to +.IR table . +There is no possible error return. +.SH "CONFORMING TO" +.BR get_kernel_syms () +is Linux specific. +.SH BUGS +There is no way to indicate the size of the buffer allocated for +.IR table . +If symbols have been added to the kernel since the +program queried for the symbol table size, memory will be corrupted. +.PP +The length of exported symbol names is limited to 59 characters. +.PP +Because of these limitations, this system call is deprecated in +favor of +.BR query_module (2) +(which is itself nowadays deprecated +in favor of other interfaces described on its manual page). +.SH NOTES +This system call is only present on Linux up until kernel 2.4; +it was removed in Linux 2.6. +.\" Removed in Linux-2.5.48 +.SH "SEE ALSO" +.BR create_module (2), +.BR delete_module (2), +.BR init_module (2), +.BR query_module (2) diff --git a/man2/init_module.2 b/man2/init_module.2 new file mode 100644 index 000000000..10be572be --- /dev/null +++ b/man2/init_module.2 @@ -0,0 +1,101 @@ +.\" 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 "2002" "Linux" "Linux Module Support" +.SH NAME +init_module \- initialize a loadable module entry +.SH SYNOPSIS +.nf +.B #include +.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 +.RS +.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 +.RE +.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, i.e., 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) diff --git a/man2/query_module.2 b/man2/query_module.2 new file mode 100644 index 000000000..e3fc73f6c --- /dev/null +++ b/man2/query_module.2 @@ -0,0 +1,167 @@ +.\" 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 QUERY_MODULE 2 "2002" "Linux" "Linux Module Support" +.SH NAME +query_module \- query the kernel for various bits pertaining to modules. +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int query_module(const char *" name ", int " which ", +.BI "void *" buf ", size_t " bufsize ", size_t *" ret ); +.fi +.SH DESCRIPTION +.BR query_module () +requests information from the kernel about loadable modules. +The returned information is placed in the buffer pointed to by +.IR buf . +The caller must specify the size of +.I buf +in +.IR bufsize . +The precise nature and format of the returned information +depend on the operation specified by +.IR which . +Some operations require +.I name +to identify a currently loaded module, some allow +.I name +to be NULL, indicating the kernel proper. + +The following values can be specified for +.IR which : +.TP +.B 0 +Always returns success. +Used to probe for availability of the system call. +.TP +.B QM_MODULES +Returns the names of all loaded modules. +The returned buffer consists of a sequence of null-terminated strings; +.I ret +is set to the number of +modules. +.TP +.B QM_DEPS +Returns the names of all modules used by the indicated module. +The returned buffer consists of a sequence of null-terminated strings; +.I ret +is set to the number of modules. +.TP +.B QM_REFS +Returns the names of all modules using the indicated module. This is +the inverse of +.BR QM_DEPS . +The returned buffer consists of a sequence of null-terminated strings; +.I ret +is set to the number of modules. +.TP +.B QM_SYMBOLS +Returns the symbols and values exported by the kernel or the indicated +module. +The returned buffer is an array of structures of the following form +.RS +.PP +.nf +struct module_symbol { + unsigned long value; + unsigned long name; +}; +.fi +.PP +followed by null-terminated strings. +The value of +.I name +is the character offset of the string relative to the start of +.IR buf ; +.I ret +is set to the number of symbols. +.RE +.TP +.B QM_INFO +Returns miscellaneous information about the indicated module. The output +buffer format is: +.RS +.PP +.nf +struct module_info { + unsigned long address; + unsigned long size; + unsigned long flags; +}; +.fi +.PP +where +.I address +is the kernel address at which the module resides, +.I size +is the size of the module in bytes, and +.I flags +is a mask of +.BR MOD_RUNNING , +.BR MOD_AUTOCLEAN , +etc. that indicates the current status of the module +(see the kernel source file +.IR include/linux/module.h ). +.I ret +is set to the size of the +.I module_info +structure. +.RE +.SH "RETURN VALUE" +On success, zero is returned. On error, \-1 is returned and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EFAULT +At least one of +.IR name , +.IR buf , +or +.I ret +was outside the program's accessible address space. +.TP +.B EINVAL +Invalid +.IR which ; +or +.I name +is NULL (indicating "the kernel"), +but this is not permitted with the specified value of +.IR which . +.\" Not permitted with QM_DEPS, QM_REFS, or QM_INFO. +.TP +.B ENOENT +No module by that +.I name +exists. +.TP +.B ENOSPC +The buffer size provided was too small. +.I ret +is set to the minimum size needed. +.SH "CONFORMING TO" +.BR query_module () +is Linux specific. +.SH NOTES +This system call is only present on Linux up until kernel 2.4; +it was removed in Linux 2.6. +.\" Removed in Linux-2.5.48 +Some of the information that was available via +.BR query_module () +can be obtained from +.IR /proc/modules , +.IR /proc/kallsyms , +and +.IR /sys/modules . +.SH "SEE ALSO" +.BR create_module (2), +.BR delete_module (2), +.BR get_kernel_syms (2), +.BR init_module (2)