-/*
- This is free and unencumbered software released into the public domain.
-
- Anyone is free to copy, modify, publish, use, compile, sell, or
- distribute this software, either in source code form or as a compiled
- binary, for any purpose, commercial or non-commercial, and by any
- means.
-
- In jurisdictions that recognize copyright laws, the author or authors
- of this software dedicate any and all copyright interest in the
- software to the public domain. We make this dedication for the benefit
- of the public at large and to the detriment of our heirs and
- successors. We intend this dedication to be an overt act of
- relinquishment in perpetuity of all present and future rights to this
- software under copyright law.
-
- Unless you really want to, do not even mention that the copied content
- originates from this skeleton library. Its sole purpose is to be copied
- into other projects.
-
- The above statements apply to all content in this skeleton library, even
- when the COPYING files, or the headers in the files state otherwise,
- they are just common examples.
-*/
-
-Questions, feedback, patches please email:
- linux-hotplug@vger.kernel.org
-or:
- Kay Sievers <kay.sievers@vrfy.org>
- Lennart Poettering <lennart@poettering.net>
-
-Why bother?
- - To make things easy for library users, distribution packagers and
- developers of library bindings for other programming languages. If
- you want your stuff to be used and commonly available, try to play
- nice, and give them what they are used to. It makes their life a
- lot easier.
-
-use autotools
- - Every custom config/makefile/build system is worse for everybody
- than autotools is.
- - We are all used to autotools, it works, nobody cares.
- - It's only two simple files to edit and include in git, which are
- well understood by many many people, not just you.
- - Ignore all crap autotools create in the source tree. never check
- the created files into git.
- - Never, ever, install config.h. That's internal to your sources
- and is nothing to install.
- - And really, anything but autotools is realy an option. Just get
- over it. Everything else is an experiment, and it will come back
- to you sooner or later. Why? think cross compilation, installation/
- uninstallation, build root integration, separate object trees,
- standard adherence, tarball handling, make distcheck, testing,
- portability between distros, ...
-
-If you use the GPL, always use the GPL's "(or later)" clause
- - Developers are not lawyers, libraries should be able to be linked
- to any version of the GPL. Remember that GPL2-only is incompatible
- with LGPL3!
-
-Use LGPL (for the shared libraries) if you don't care about politics
- - It protects the code, but does not restrict its use. Low-level
- library interfaces are mostly used like kernel syscall or proc/sysfs
- interfaces, which are usually without any restrictions.
-
-Zero global state -- Make your library threads-aware, but *not* thread-safe!
- - An app can use liba and libb. libb internally can also use liba --
- without you knowing. Both you and libb can run liba code at the
- very same time in different threads and operate at the same global
- variables, without telling you about that. Loadable modules make
- this problem even more prominent, since the libraries they pull in
- are generally completely unknown by the main application. And
- *every* program has loadable modules, think NSS!
- - Avoid locking and mutexes, they are very unlikely to work correctly,
- and incredibly hard to get right.
- - Always use a library context object. every thread should then
- operate on its own context. Do not imply context objects via TLS. It
- won't work. TLS inheritance to new threads will get in your way. TLS
- is a problem in itself, not a solution.
- - Do not use gcc constructors, or destructors, you can only loose if
- you do. Do not use _fini() or _ini(), don't even use your own
- explicit library initializer/destructor functions. It just won't
- work if your library is pulled in indirectly from another library
- or even a shared module (i.e. dlopen())
- - Always use O_CLOEXEC, SOCK_CLOEXEC and friends. It's not an
- option, it's a must.
- - Don't use global variables (it includes static variables defined
- inside functions). Ever. And under no circumstances export global
- variables. It's madness.
-
-Use a common prefix for _all_ exported symbols
- - Avoids namespace clashes
- - Also, hacking is not a contest of finding the shortest possible
- function name. And nobody cares about your 80ch line limit!
- - If you use a drop-in library in your own library make sure to hide its
- symbols with symbol versioning. Don't forget to hide *all* symbols, and
- don't install the header file of the used drop-in library.
-
-Do not expose any complex structures in your API
- - Use get() and set() instead.
- - All objects should be opaque.
- - Exporting structs in headers is OK in very few cases only: usually
- those where you define standard binary formats (think: file
- formats, datagram headers, ...) or where you define well-known
- primitive types (think struct timeval, struct iovec, uuid
- type).
- - Why bother? Because struct stat, struct dirent and friends are
- disasters. Particularly horrible are structs with fixed-size
- strings.
-
-Use the de-facto standardized function names
- - It's abc_new(), abc_free(), abc_ref(), abc_unref(). Don't invent
- your own names, and don't use the confusing kernel-style ref
- counting. Function names: _get() is for accessing properties of
- objects, not for refcounting.
-
-Stick to kernel coding style
- - Just because you are otherwise not bound by the kernel guidelines
- when your write userspace libraries doesn't mean you have to give
- up the good things it defines.
-
-Avoid callbacks in your API
- - Language bindings want iterators.
- - Programmers want iterators too.
-
-Never call exit(), abort(), be very careful with assert()
- - Always return error codes.
- - Libraries need to be safe for usage in critical processes that
- need to recover from errors instead of getting killed (think PID 1!).
-
-Avoid thinking about main loops/event dispatchers.
- - Get your stuff right in the kernel: fds are awesome, expose them
- in userspace and in the library, because people can easily integrate
- them with their own poll() loops of whatever kind they have.
- - Don't hide file descriptors away in your headers.
- - Never add blocking kernel syscalls, and never add blocking library
- calls either (with very few exceptions). Userspace code is primarily
- asynchronous around event loops, and blocking calls are generally
- incompatible with that.
- - Corollary of that: always O_NONBLOCK!
-
-Functions should return int and negative errors instead of NULL
- - Return NULL in malloc() is fine, return NULL in fopen() is not!
- - Pass allocated objects as parameter (yes, ctx_t** is OK!)
- - Returning kernel style negative <errno.h> error codes is cool in
- userspace too. Do it!
-
-Provide pkgconfig files
- - Apps want to add a single line to their configure file,
- they do not want to fiddle with the parameters, dependencies
- to setup and link your library.
- - It's just how we do these things today on Linux, and everything
- else is just horribly messy.
-
-Avoid *hidden* fork()/exec() in libraries
- - Apps generally do not expect signals and react allergic to them.
- - Mutexes, locks, threads of the app might get confused. Mixing
- mutexes and fork() equals failure. It just can't work, and
- pthread_atfork() is not a solution for that, because it's broken
- (even POSIX acknowledges that, just read the POSIX man
- pages!). fork() safety for mutex-ridden code is not an
- afterthought, it's a broken right from the beginning.
-
-Make your code safe for unexpected termination and any point:
- - Do not leave files dirty or temporary files around.
- - This is a tricky, since you need to design your stuff like this
- from the beginning, it's not an afterthought, since you generally
- do not have a place to clean up your stuff on exit. gcc
- destructors are NOT the answer.
-
-Use symbol versioning
- - Only with that, RPM can handle dependencies for added symbols
- - Hide all internal symbols! *This is important!*
-
-Always provide logging/debugging, but do not clutter stderr
- - Allow the app to hook the libs logging into its logging facility.
- - Use conditional logging, do not filter too late.
- - Do not burn cycles with printf() to /dev/null.
- - By default: do not generate any output on stdout/stderr.
-
-Always use 'make distcheck' to create tarballs
- - Never release anything that does not pass distcheck. It will
- likely be broken for others too
-
-Use ./autogen.sh to bootstrap the git repo
- - Always test bootstrapping with 'git clean -x -f -d' before
- release (careful, it force-deletes all uncommitted files).
-
-Avoid any spec files or debian/ subdirs in git trees
- - Distribution specific things do not belong in upstream trees,
- but into distro packages
-
-Update NEWS to let developers know what has changed
- - It's the history of the project, stuff that packagers need to know
- when putting a new version in the distro. The interesting changes
- or added/removed functionality from version to version. This is
- not a commit changelog.
- - If you want to provide ChangeLog, use the one generated
- by git, do not maintain your own.
-
-use standard types
- - The kernel's u8, u16, ... correspond to uint8_t, uint16_t in
- userspace from <inttypes.h>. Don't define your own typedefs
- for that, don't include the kernel types in common headers.
- - Use enums, not #define for constants, wherever possible. In
- userspace you have debuggers, and they are much nicer to use if
- you have proper enum identifiers instead of macro definitions,
- because the debugger can translate binary values back to enum
- identifiers, but not macros. However, be careful with enums in
- function prototypes: they might change the int type they are
- resolved to as you add new enum values.
-
-Always guard for multiple inclusions of headers
- - You must place '#ifndef libabc, #define libabc, #endif' in your
- header files. There is no way around that.
-
-Be careful with variadic functions
- - It's great if you provide them, but you must accompany them with
- "v" variants (i.e. functions taking a va_arg object), and provide
- non-variadic variants as well. This is important to get language
- wrappers right.
-
-Don't put "extern" in front of your function prototypes in headers
- - It has no effect, no effect at all.
-
-Never use sysv IPC, always use POSIX IPC
- - Shmops and semops are horrors. Don't use them, ever. POSIX IPC is
- much much much nicer.
-
-Avoid multiplexed functions ala ioctl()/prctl() style variadic functions
- - Type-safety is awesome!
-
-Executing out-of-process tools and parsing their output is usually
-not acceptable in libraries
- - Tools should be built on top of their own lib.
- - Always separate 'mechanism' from 'policy'. Make access to functionality
- simple, but do not try to hide things that need to be decided by the
- caller. Keep automagic at its minimum. Don't do hidden fork() do not
- implicitly maintain cache files, ...
-
-Function calls with 15 arguments are a bad idea. If you have tons of
-booleans in a function call, then replace them by a flag argument!
- - Think about the invocation! foo(0, 1, 0, 1, 0, 0, 0, 1) is unreadable!
- foo(FOO_QUUX|FOO_BAR|FOO_WALDO) much nicer.
-
-Don't be afraid of C99. Use it.
- - It's 12 years old. And it's nice.
-
-Never expose fixed size strings in your API
- - Pass malloc()ed strings out, or ask the caller to provide you with
- a buffer, and return ENOSPC if too short.
-
-Glibc has byteswapping calls, don't invent your own:
- - le32toh(), htole32() and friends
- - bswap32() and friends()
-
-Don't typedef pointers to structs!
-
-Don't write your own LISP interpreter and do not include it in your
-library. :)
+kmod - Linux kernel module handling
+
+Information
+===========
+
+Mailing list:
+ linux-modules@vger.kernel.org (no subscription needed)
+ https://lore.kernel.org/linux-modules/
+
+Signed packages:
+ http://www.kernel.org/pub/linux/utils/kernel/kmod/
+
+Git:
+ git://git.kernel.org/pub/scm/utils/kernel/kmod/kmod.git
+ http://git.kernel.org/pub/scm/utils/kernel/kmod/kmod.git
+ https://git.kernel.org/pub/scm/utils/kernel/kmod/kmod.git
+
+Gitweb:
+ http://git.kernel.org/?p=utils/kernel/kmod/kmod.git
+ https://github.com/kmod-project/kmod
+
+Irc:
+ #kmod on irc.freenode.org
+
+License:
+ LGPLv2.1+ for libkmod, testsuite and helper libraries
+ GPLv2+ for tools/*
+
+
+OVERVIEW
+========
+
+kmod is a set of tools to handle common tasks with Linux kernel modules like
+insert, remove, list, check properties, resolve dependencies and aliases.
+
+These tools are designed on top of libkmod, a library that is shipped with
+kmod. See libkmod/README for more details on this library and how to use it.
+The aim is to be compatible with tools, configurations and indexes from
+module-init-tools project.
+
+Compilation and installation
+============================
+
+In order to compiler the source code you need following software packages:
+ - GCC compiler
+ - GNU C library
+
+Optional dependencies:
+ - ZLIB library
+ - LZMA library
+
+Typical configuration:
+ ./configure CFLAGS="-g -O2" --prefix=/usr \
+ --sysconfdir=/etc --libdir=/usr/lib
+
+Configure automatically searches for all required components and packages.
+
+To compile and install run:
+ make && make install
+
+Hacking
+=======
+
+Run 'autogen.sh' script before configure. If you want to accept the recommended
+flags, you just need to run 'autogen.sh c'. Note that the recommended
+flags require cython be installed to compile successfully.
+
+Make sure to read the CODING-STYLE file and the other READMEs: libkmod/README
+and testsuite/README.
+
+Compatibility with module-init-tools
+====================================
+
+kmod replaces module-init-tools, which is end-of-life. Most of its tools are
+rewritten on top of libkmod so it can be used as a drop in replacements.
+Somethings however were changed. Reasons vary from "the feature was already
+long deprecated on module-init-tools" to "it would be too much trouble to
+support it".
+
+There are several features that are being added in kmod, but we don't
+keep track of them here.
+
+modprobe
+--------
+
+* 'modprobe -l' was marked as deprecated and does not exist anymore
+
+* 'modprobe -t' is gone, together with 'modprobe -l'
+
+* modprobe doesn't parse configuration files with names not ending in
+ '.alias' or '.conf'. modprobe used to warn about these files.
+
+* modprobe doesn't parse 'config' and 'include' commands in configuration
+ files.
+
+* modprobe from m-i-t does not honour softdeps for install commands. E.g.:
+ config:
+
+ install bli "echo bli"
+ install bla "echo bla"
+ softdep bla pre: bli
+
+ With m-i-t, the output of 'modprobe --show-depends bla' will be:
+ install "echo bla"
+
+ While with kmod:
+ install "echo bli"
+ install "echo bla"
+
+* kmod doesn't dump the configuration as is in the config files. Instead it
+ dumps the configuration as it was parsed. Therefore, comments and file names
+ are not dumped, but on the good side we know what the exact configuration
+ kmod is using. We did this because if we only want to know the entire content
+ of configuration files, it's enough to use find(1) in modprobe.d directories
+
+depmod
+------
+
+* there's no 'depmod -m' option: legacy modules.*map files are gone
+
+lsmod
+-----
+
+* module-init-tools used /proc/modules to parse module info. kmod uses
+ /sys/module/*, but there's a fallback to /proc/modules if the latter isn't
+ available
projects / thirdparty / kmod.git / blobdiff