man2/query_module.2

   1 .\" Copyright (C) 1996 Free Software Foundation, Inc.
   2 .\"
   3 .\" SPDX-License-Identifier: GPL-1.0-or-later
   4 .\"
   5 .\" 2006-02-09, some reformatting by Luc Van Oostenryck; some
   6 .\" reformatting and rewordings by mtk
   7 .\"
   8 .TH QUERY_MODULE 2 2022-09-09 "Linux man-pages (unreleased)"
   9 .SH NAME
  10 query_module \- query the kernel for various bits pertaining to modules
  11 .SH SYNOPSIS
  12 .nf
  13 .B #include <linux/module.h>
  14 .PP
  15 .BI "[[deprecated]] int query_module(const char *" name ", int " which \
  16 ", void *" buf ,
  17 .BI "                                size_t " bufsize ", size_t *" ret );
  18 .fi
  19 .SH DESCRIPTION
  20 .IR Note :
  21 This system call is present only in kernels before Linux 2.6.
  22 .PP
  23 .BR query_module ()
  24 requests information from the kernel about loadable modules.
  25 The returned information is placed in the buffer pointed to by
  26 .IR buf .
  27 The caller must specify the size of
  28 .I buf
  29 in
  30 .IR bufsize .
  31 The precise nature and format of the returned information
  32 depend on the operation specified by
  33 .IR which .
  34 Some operations require
  35 .I name
  36 to identify a currently loaded module, some allow
  37 .I name
  38 to be NULL, indicating the kernel proper.
  39 .PP
  40 The following values can be specified for
  41 .IR which :
  42 .TP
  43 .B 0
  44 Returns success, if the kernel supports
  45 .BR query_module ().
  46 Used to probe for availability of the system call.
  47 .TP
  48 .B QM_MODULES
  49 Returns the names of all loaded modules.
  50 The returned buffer consists of a sequence of null-terminated strings;
  51 .I ret
  52 is set to the number of
  53 modules.
  54 .\" ret is set on ENOSPC
  55 .TP
  56 .B QM_DEPS
  57 Returns the names of all modules used by the indicated module.
  58 The returned buffer consists of a sequence of null-terminated strings;
  59 .I ret
  60 is set to the number of modules.
  61 .\" ret is set on ENOSPC
  62 .TP
  63 .B QM_REFS
  64 Returns the names of all modules using the indicated module.
  65 This is the inverse of
  66 .BR QM_DEPS .
  67 The returned buffer consists of a sequence of null-terminated strings;
  68 .I ret
  69 is set to the number of modules.
  70 .\" ret is set on ENOSPC
  71 .TP
  72 .B QM_SYMBOLS
  73 Returns the symbols and values exported by the kernel or the indicated
  74 module.
  75 The returned buffer is an array of structures of the following form
  76 .\" ret is set on ENOSPC
  77 .IP
  78 .in +4n
  79 .EX
  80 struct module_symbol {
  81     unsigned long value;
  82     unsigned long name;
  83 };
  84 .EE
  85 .in
  86 .IP
  87 followed by null-terminated strings.
  88 The value of
  89 .I name
  90 is the character offset of the string relative to the start of
  91 .IR buf ;
  92 .I ret
  93 is set to the number of symbols.
  94 .TP
  95 .B QM_INFO
  96 Returns miscellaneous information about the indicated module.
  97 The output buffer format is:
  98 .IP
  99 .in +4n
 100 .EX
 101 struct module_info {
 102     unsigned long address;
 103     unsigned long size;
 104     unsigned long flags;
 105 };
 106 .EE
 107 .in
 108 .IP
 109 where
 110 .I address
 111 is the kernel address at which the module resides,
 112 .I size
 113 is the size of the module in bytes, and
 114 .I flags
 115 is a mask of
 116 .BR MOD_RUNNING ,
 117 .BR MOD_AUTOCLEAN ,
 118 and so on, that indicates the current status of the module
 119 (see the Linux kernel source file
 120 .IR include/linux/module.h ).
 121 .I ret
 122 is set to the size of the
 123 .I module_info
 124 structure.
 125 .SH RETURN VALUE
 126 On success, zero is returned.
 127 On error, \-1 is returned and
 128 .I errno
 129 is set to indicate the error.
 130 .SH ERRORS
 131 .TP
 132 .B EFAULT
 133 At least one of
 134 .IR name ,
 135 .IR buf ,
 136 or
 137 .I ret
 138 was outside the program's accessible address space.
 139 .TP
 140 .B EINVAL
 141 Invalid
 142 .IR which ;
 143 or
 144 .I name
 145 is NULL (indicating "the kernel"),
 146 but this is not permitted with the specified value of
 147 .IR which .
 148 .\" Not permitted with QM_DEPS, QM_REFS, or QM_INFO.
 149 .TP
 150 .B ENOENT
 151 No module by that
 152 .I name
 153 exists.
 154 .TP
 155 .B ENOSPC
 156 The buffer size provided was too small.
 157 .I ret
 158 is set to the minimum size needed.
 159 .TP
 160 .B ENOSYS
 161 .BR query_module ()
 162 is not supported in this version of the kernel
 163 (e.g., the kernel is version 2.6 or later).
 164 .SH VERSIONS
 165 This system call is present on Linux only up until kernel 2.4;
 166 it was removed in Linux 2.6.
 167 .\" Removed in Linux 2.5.48
 168 .SH STANDARDS
 169 .BR query_module ()
 170 is Linux-specific.
 171 .SH NOTES
 172 Some of the information that was formerly available via
 173 .BR query_module ()
 174 can be obtained from
 175 .IR /proc/modules ,
 176 .IR /proc/kallsyms ,
 177 and the files under the directory
 178 .IR /sys/module .
 179 .PP
 180 The
 181 .BR query_module ()
 182 system call is not supported by glibc.
 183 No declaration is provided in glibc headers, but,
 184 through a quirk of history, glibc does export an ABI for this system call.
 185 Therefore, in order to employ this system call,
 186 it is sufficient to manually declare the interface in your code;
 187 alternatively, you can invoke the system call using
 188 .BR syscall (2).
 189 .SH SEE ALSO
 190 .BR create_module (2),
 191 .BR delete_module (2),
 192 .BR get_kernel_syms (2),
 193 .BR init_module (2),
 194 .BR lsmod (8),
 195 .BR modinfo (8)