.\" -*- coding: UTF-8 -*-
.\" Copyright (C) 2012 Michael Kerrisk <mtk.manpages@gmail.com>
.\" A few fragments remain from a version
.\" Copyright (C) 1996 Free Software Foundation, Inc.
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
.\"*******************************************************************
.\"
.\" This file was generated with po4a. Translate the source file.
.\"
.\"*******************************************************************
.TH init_module 2 "2 maja 2024 r." "Linux man\-pages 6.9.1" 
.SH NAZWA
init_module, finit_module \- ładuje moduł jądra
.SH BIBLIOTEKA
Standardowa biblioteka C (\fIlibc\fP, \fI\-lc\fP)
.SH SKŁADNIA
.nf
\fB#include <linux/module.h>\fP    /* Definicja stałych \fBMODULE_*\fP */
\fB#include <sys/syscall.h>\fP     /* Definicja stałych \fBSYS_*\fP */
\fB#include <unistd.h>\fP
.P
\fBint syscall(SYS_init_module, void \fP\fImodule_image\fP\fB[.\fP\fIlen\fP\fB], unsigned long \fP\fIlen\fP\fB,\fP
\fB            const char *\fP\fIparam_values\fP\fB);\fP
\fBint syscall(SYS_finit_module, int \fP\fIfd\fP\fB,\fP
\fB            const char *\fP\fIparam_values\fP\fB, int \fP\fIflags\fP\fB);\fP
.fi
.P
\fIUwaga\fP: glibc nie udostępnia opakowania dla tych wywołań systemowych, co
wymusza użycie \fBsyscall\fP(2).
.SH OPIS
\fBinit_module\fP() ładuje obraz ELF do przestrzeni jądra, przeprowadzając
wszelkie niezbędne przesunięcia symboli, inicjuje parametry modułu zgodnie z
wartościami przekazanymi przez wywołującego, a następnie uruchamia funkcję
\fIinit\fP modułu. To wywołanie systemowe wymaga uprzywilejowania.
.P
Argument \fImodule_image\fP wskazuje na bufor zawierający obraz binarny, który
ma być załadowany; \fIlen\fP określa rozmiar tego bufora. Obraz modułu powinien
być prawidłowym obrazem ELF, zbudowanym do aktualnie działającego jądra.
.P
Argument \fIparam_values\fP jest łańcuchem zawierającym wartości parametrów
modułu (zdefiniowanych wewnątrz modułu za pomocą \fBmodule_param\fP() i
\fBmodule_param_array\fP()), rozdzielone spacją. Jądra analizuje ten łańcuch i
inicjuje podane parametry. Określenie każdego z parametrów ma postać:
.P
\fInazwa\fP[ \fB=\fP\fIwartość\fP [\fB,\fP\fIwartość\fP...]]
.P
Parametr \fInazwa\fP jest jednym ze zdefiniowanych wewnątrz modułu za pomocą
\fImodule_param\fP() (zob. plik źródeł jądra Linux
\fIinclude/linux/moduleparam.h\fP). Parametr \fIwartość\fP jest opcjonalny w
przypadku parametrów \fIbool\fP i \fIinvbool\fP. Wartości parametrów tablicy są
podawane w liście rozdzielonej przecinkami.
.SS finit_module()
.\" commit 34e1169d996ab148490c01b65b4ee371cf8ffba2
.\" https://lwn.net/Articles/519010/
Wywołanie systemowe \fBfinit_module\fP() jest podobne do \fBinit_module\fP(), lecz
odczytuje moduł, który ma być załadowany, z deskryptora pliku \fIfd\fP. Ma to
zastosowanie, gdy autentyczność modułu jądra można określić na podstawie
jego położenia w systemie plików; w przypadku gdy jest to możliwe, można w
ten sposób uniknąć narzutu wynikającego z używania modułów podpisanych
kryptograficznie. Argument \fIparam_values\fP jest taki sam jak do
\fBinit_module\fP().
.P
.\" commit 2f3238aebedb243804f58d62d57244edec4149b2
Argument \fIflags\fP modyfikuje działanie \fBfinit_module\fP(). Jest maską bitową
wartości, utworzoną przez zsumowanie (OR) zera lub więcej poniższych
znaczników:
.TP 
\fBMODULE_INIT_IGNORE_MODVERSIONS\fP
Ignoruje skróty wersji symboli.
.TP 
\fBMODULE_INIT_IGNORE_VERMAGIC\fP
Ignoruje magię wersji jądra.
.TP 
\fBMODULE_INIT_COMPRESSED_FILE\fP (od Linuksa 5.17)
.\" commit b1ae6dc41eaaa98bb75671e0f3665bfda248c3e7
Używa modułu dekompresji w jądrze.
.P
.\" http://www.tldp.org/HOWTO/Module-HOWTO/basekerncompat.html
.\" is dated, but informative
W module są wbudowane pewne mechanizmy bezpieczeństwa zapewniające, że
będzie on pasował do jądra, do którego jest załadowywany. Są one zapisywane
przy budowaniu modułu i weryfikowane przy jego ładowaniu. Po pierwsze, moduł
zapisuje łańcuch \[Bq]vermagic\[rq] zawierający łańcuch z numerem wersji
jądra i głównymi cechami (takimi jak typ procesora). Po drugie, jeśli moduł
zbudowano z włączoną opcją konfiguracyjną \fBCONFIG_MODVERSIONS\fP, to
zapisywany jest skrót (hash) wersji każdego symbolu, którego używa
moduł. Skrót ten zależy od typów argumentów i zwracanej przez funkcję,
nazwaną przez symbol, wartości. W niniejszym przypadku, numer wersji jądra w
\[Bq]vermagic\[rq] jest ignorowany przyjmując, że skróty wersji symboli są
wystarczająco wiarygodne.
.P
Użycie znacznika \fBMODULE_INIT_IGNORE_VERMAGIC\fP wskazuje, że łańcuch
\[Bq]vermagic\[rq] ma być zignorowany, natomiast znacznik
\fBMODULE_INIT_IGNORE_MODVERSIONS\fP wskazuje, że skróty wersji symboli mają
być zignorowane. Jeśli jądro zbudowano w sposób umożliwiający wymuszone
ładowanie modułów (tj. skonfigurowano je z opcją
\fBCONFIG_MODULE_FORCE_LOAD\fP), to ładowanie będzie kontynuowane, w przeciwnym
przypadku zawiedzie z błędem \fBENOEXEC\fP, jak jest to spodziewane wobec
nieprawidłowych modułów.
.P
Jeśli jądro zbudowano z opcją \fBCONFIG_MODULE_DECOMPRESS\fP, można skorzystać
z funkcji dekompresji w jądrze. Kod w przestrzeni użytkownika może
sprawdzić, czy jądro obsługuje dekompresję odczytując atrybut
\fI/sys/module/compression\fP. Jeśli jądro obsługuje dekompresję, skompresowany
plik można podać bezpośrednio do \fBfinit_module\fP() za pomocą znacznika
\fBMODULE_INIT_COMPRESSED_FILE\fP. Moduł dekompresji w jądrze obsługuje
następujące algorytmy kompresji:
.P
.RS 4
.PD 0
.IP \[bu] 3
\fIgzip\fP (od Linuksa 5.17)
.IP \[bu]
\fIxz\fP (od Linuksa 5.17)
.IP \[bu]
.\" commit 169a58ad824d896b9e291a27193342616e651b82
\fIzstd\fP (od Linuksa 6.2)
.PD
.RE
.P
Jądro implementuje jedynie pojedynczą metodę dekompresji. Wybiera się ją
przy generowaniu modułu, zgodnie z metodą kompresji użytą w konfiguracji
jądra.
.SH "WARTOŚĆ ZWRACANA"
W przypadku powodzenia, te wywołania zwracają 0. W razie wystąpienia błędu
zwracane jest \-1 i ustawiane \fIerrno\fP wskazując błąd.
.SH BŁĘDY
.TP 
\fBEBADMSG\fP (od Linuksa 3.7)
Podpis modułu jest nieprawidłowo sformatowany.
.TP 
\fBEBUSY\fP
Nastąpiło przeterminowanie, przy próbie rozwiązania referencji symbolu przez
ten moduł.
.TP 
\fBEFAULT\fP
Argument adresu odnosi się do położenia, znajdującego się poza dostępną
przestrzenią adresową procesu.
.TP 
\fBENOKEY\fP (od Linuksa 3.7)
.\" commit 48ba2462ace6072741fd8d0058207d630ce93bf1
.\" commit 1d0059f3a468825b5fc5405c636a2f6e02707ffa
.\" commit 106a4ee258d14818467829bf0e12aeae14c16cd7
Podpis modułu jest nieprawidłowy albo jądro nie ma klucza do tego
modułu. Błąd jest zwracany tylko, jeśli jądro skonfigurowano z opcją
\fBCONFIG_MODULE_SIG_FORCE\fP; w przeciwnym wypadku nieprawidłowy lub
niepodpisany moduł jedynie zatruwa (taint) jądro.
.TP 
\fBENOMEM\fP
Brak pamięci.
.TP 
\fBEPERM\fP
Wywołujący nie był uprzywilejowany (nie posiadał przywileju
(ang. capability) \fBCAP_SYS_MODULE\fP) lub ładowanie modułów jest wyłączone
(zob.  \fI/proc/sys/kernel/modules_disabled\fP w \fBproc\fP(5)).
.P
Mogą wystąpić następujące dodatkowe błędy dla \fBinit_module\fP():
.TP 
\fBEEXIST\fP
Załadowano już moduł o takiej nazwie.
.TP 
\fBEINVAL\fP
.\" .TP
.\" .BR EINVAL " (Linux 2.4 and earlier)"
.\" 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.
\fIparam_values\fP jest nieprawidłowe albo pewne fragmenty obrazu
\fImodule_image\fP są niespójne.
.TP 
\fBENOEXEC\fP
Obraz binarny podany w \fImodule_image\fP nie jest obrazem ELF albo jest
nieprawidłowym lub przeznaczonym do innej architektury obrazem ELF.
.P
Mogą wystąpić następujące dodatkowe błędy dla \fBfinit_module\fP():
.TP 
\fBEBADF\fP
Plik, do którego odnosi się \fIfd\fP , nie jest otwarty do odczytu.
.TP 
\fBEFBIG\fP
Plik, do którego odnosi się \fIfd\fP, jest zbyt duży.
.TP 
\fBEINVAL\fP
Znaczniki \fIflags\fP są nieprawidłowe.
.TP 
\fBEINVAL\fP
Przy ładowaniu spakowanego modułu ze znacznikiem
\fBMODULE_INIT_COMPRESSED_FILE\fP, zawiodło sprawdzanie poprawności
przeprowadzone przez dekompresor.
.TP 
\fBENOEXEC\fP
\fIfd\fP nie odnosi się do otwartego pliku.
.TP 
\fBEOPNOTSUPP\fP (od Linuksa 5.17)
Ustawiono znacznik \fBMODULE_INIT_COMPRESSED_FILE\fP w celu załadowania
spakowanego modułu, lecz jądro zbudowano bez \fBCONFIG_MODULE_DECOMPRESS\fP.
.TP 
\fBETXTBSY\fP (od Linuksa 4.7)
.\" commit 39d637af5aa7577f655c58b9e55587566c63a0af
Plik, do którego odnosi się \fIfd\fP, jest otwarty do odczytu i zapisu.
.P
Oprócz powyższych błędów, jeśli wykonana funkcja \fIinit\fP modułu zwróci błąd,
to \fBinit_module\fP() lub \fBfinit_module\fP() zawiodą, a \fIerrno\fP zostanie
ustawione na wartość zwróconą przez funkcję \fIinit\fP.
.SH STANDARDY
Linux.
.SH HISTORIA
.TP 
\fBfinit_module\fP()
Linux 3.8.
.P
Wywołanie systemowe \fBinit_module\fP() nie jest obsługiwane przez glibc. W
nagłówkach glibc nie ma jego deklaracji, ale z powodów pewnych zaszłości
historycznych wersje glibc przed glibc 2.23 eksportowały ABI dla tego
wywołania systemowego. Z tego powodu, aby go użyć wystarczy (przed glibc
2.23) manualnie zadeklarować interfejs w swoim kodzie; alternatywnie można
wywołać to wywołanie systemowe za pomocą \fBsyscall\fP(2).
.SS "Linux 2.4 i wcześniejsze"
W Linuksie 2.4 i wcześniejszych wywołanie systemowe \fBinit_module\fP() było
wyraźnie odmienne:
.P
\fB#include <linux/module.h>\fP
.P
\fB int init_module(const char *\fP\fIname\fP\fB, struct module *\fP\fIimage\fP\fB);\fP
.P
(Aplikacje w przestrzeni użytkownika mogą wykryć dostępną wersję
\fBinit_module\fP() przez wywołanie \fBquery_module\fP(); to ostatnie wywołanie
zawiedzie z błędem \fBENOSYS\fP w Linuksie 2.6 i późniejszych).
.P
Starsza wersja tego wywołania systemowego ładowała przesunięty obraz jądra,
na który wskazywało \fIimage\fP do przestrzeni jądra i uruchamiało funkcję
\fIinit\fP modułu. To wywołujący był odpowiedzialny za udostępnienie
przesuniętego obrazu (od Linuksa 2.6, to wywołanie systemowe
\fBinit_module\fP() dokonuje przesunięcia).
.P
Obraz modułu rozpoczyna się od struktury modułu, po której następują,
odpowiednio, kod i dane. Od Linuksa 2.2 struktura modułu jest zdefiniowana
następująco:
.P
.in +4n
.EX
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
};
.EE
.in
.P
Wszystkie pola wskazujące, oprócz \fInext\fP i \fIrefs\fP, powinny wskazywać na
adresy w ciele modułu i zostać zainicjalizowane odpowiednio dla przestrzeni
adresowej jądra, tzn. przesunięte wraz z resztą modułu.
.SH UWAGI
Informacje o obecnie załadowanych modułach są dostępne w \fI/proc/modules\fP
oraz w strukturze plików zawartej w podkatalogach, przypisanych
poszczególnym modułom, w katalogu \fI/sys/module\fP.
.P
Więcej przydatnych informacji \[Bq]od kuchni\[rq] znajduje się w pliku
źródeł jądra Linux \fIinclude/linux/module.h\fP.
.SH "ZOBACZ TAKŻE"
\fBcreate_module\fP(2), \fBdelete_module\fP(2), \fBquery_module\fP(2), \fBlsmod\fP(8),
\fBmodprobe\fP(8)
.PP
.SH TŁUMACZENIE
Autorami polskiego tłumaczenia niniejszej strony podręcznika są:
Andrzej Krzysztofowicz <ankry@green.mf.pg.gda.pl>
i
Michał Kułach <michal.kulach@gmail.com>
.
.PP
Niniejsze tłumaczenie jest wolną dokumentacją. Bliższe informacje o warunkach
licencji można uzyskać zapoznając się z
.UR https://www.gnu.org/licenses/gpl-3.0.html
GNU General Public License w wersji 3
.UE
lub nowszej. Nie przyjmuje się ŻADNEJ ODPOWIEDZIALNOŚCI.
.PP
Błędy w tłumaczeniu strony podręcznika prosimy zgłaszać na adres listy
dyskusyjnej
.MT manpages-pl-list@lists.sourceforge.net
.ME .
