From 2a2e7ad562841be14b2d1f8ad870780f32be2b1f Mon Sep 17 00:00:00 2001 From: PulkoMandy Date: Sat, 17 Feb 2024 16:49:03 +0100 Subject: [PATCH] doc/user: mention libnetwork and a bit of the filesystem hierarchy Based on the feedback from Maya Posch in https://mayaposch.wordpress.com/2024/01/20/porting-nymphcast-to-the-haiku-operating-system/ Thanks for noting that the information was missing! Change-Id: I4a9f709b17cb3a4a771f167b5af0fc83843ec5ad Reviewed-on: https://review.haiku-os.org/c/haiku/+/7406 Reviewed-by: Niels Sascha Reedijk Tested-by: Commit checker robot --- docs/user/posix/_libroot.dox | 10 +++++-- docs/user/storage/storageintro.dox | 44 ++++++++++++++++++++++++++++++ 2 files changed, 52 insertions(+), 2 deletions(-) create mode 100644 docs/user/storage/storageintro.dox diff --git a/docs/user/posix/_libroot.dox b/docs/user/posix/_libroot.dox index e0a15d3202..7a21c1278f 100644 --- a/docs/user/posix/_libroot.dox +++ b/docs/user/posix/_libroot.dox @@ -1,5 +1,5 @@ /* - * Copyright 2019 Haiku, Inc. All rights reserved. + * Copyright 2019-2024 Haiku, Inc. All rights reserved. * Distributed under the terms of the MIT License. * * Authors: @@ -15,7 +15,9 @@ Haiku implements a standard library containing the standard functions from C available in libroot, which is linked in by default. For convenience and POSIX compatibility, empty "m" and "pthread" libraries are -also provided, but the math and thread functions are also defined in libroot. +also provided, but the math and thread functions are also defined in libroot. However, this is +currently not the case for "rt" and "trace" (both also part of the standard libraries required +in POSIX). The C library also contains a number of GNU and BSD extensions to the C and POSIX standards. The BSD extensions are enabled by default unless a specific @@ -30,4 +32,8 @@ _GNU_SOURCE. The GNU and BSD extensions are in a separate library, so the -lbsd linker flag may be needed to use them. +On the other hand, network socket functions (socket, connect, bind, accept, ...) are provided in +a separate library, libnetwork.so. To use these functions you will need to use the -lnetwork +linker command line switch (instead of the POSIX specified -lxnet). + */ diff --git a/docs/user/storage/storageintro.dox b/docs/user/storage/storageintro.dox new file mode 100644 index 0000000000..e02c1acd01 --- /dev/null +++ b/docs/user/storage/storageintro.dox @@ -0,0 +1,44 @@ +/*! + \page storage_intro Introduction to the storage kit + +\section Filesystem hierarchy + +The filesystems are organized in a hierarchy starting at the root directory (which has the path +'/'). Unlike on typical UNIX systems, the root filsystem is not a mass storage filesystem that +the OS was booted from. Instead, it is a virtual filesystem that can only contain directories, +symbolic links, and mountpoints. + +All the other filesystems are mounted as subdirectories of the root filesystem or further down +in the file hierarchy. + +The booted filesystem (what would be the rootfs in a typical UNIX) is mounted in '/boot'. For +convenience, several links are created in the rootfs to well-known directories ('/bin', '/var', +etc). These point into the corresponding directories in /boot/system, which are managed by +packagefs. + +The packagefs is a read-only union filesystem that makes available the content of various software +packages (installed as .hpkg files) to constitute the entire /boot/system directory. The files can +be accessed either as a complete filesystem hierarchy directly in /boot/system, or by referencing +specific packages exposed in /boot/system/package-links (each directory is a view of the packagefs, +containing only the files for a given package and all its dependencies). In theory, this allows +packages to be exposed in the package-links directory even while they are not actually "activated" +in the main system hierarchy. It also allows to access a version of a file provided by a specific +package, in the case that two packages provide identically named files. + +While packagefs is mostly read-only, some directories (called "shine-through") are actually +exposing the content of the underlying filesystem. This includes for example the "config" directory +(for configuration files) and the "non-packaged" directory, where a mirror of the standard +filesystem hierarchy is available for non packaged software. This can be used to install software +locally that is not available yet in HPKG form (for example, as a destination for "make install"). + +For a complete list of directories and how to access them in a way that is safe to future +filesystem reorganizations, see \link find_directory, \link find_path, and \link BPathFinder. + +*/ + +/*! +\addtgroup storage + +See \link storage_intro for general concepts and filesystem hierarchy description. + +*/