tripathysagar/man_text huggingface dataset:
# network_namespaces

## NAME



           network_namespaces - overview of Linux network namespaces
    


## DESCRIPTION



           Network namespaces provide isolation of the system resources
           associated with networking: network devices, IPv4 and IPv6
           protocol stacks, IP routing tables, firewall rules, the _/proc/net_
           directory (which is a symbolic link to _/proc/_ pid _/net_), the
           _/sys/class/net_ directory, various files under _/proc/sys/net_ , port
           numbers (sockets), and so on.  In addition, network namespaces
           isolate the UNIX domain abstract socket namespace (see unix(7)).
    
           A physical network device can live in exactly one network
           namespace.  When a network namespace is freed (i.e., when the last
           process in the namespace terminates), its physical network devices
           are moved back to the initial network namespace (not to the
           namespace of the parent of the process).
    
           A virtual network (veth(4)) device pair provides a pipe-like
           abstraction that can be used to create tunnels between network
           namespaces, and can be used to create a bridge to a physical
           network device in another namespace.  When a namespace is freed,
           the veth(4) devices that it contains are destroyed.
    
           Use of network namespaces requires a kernel that is configured
           with the **CONFIG_NET_NS** option.
    


* * *
# intro

## NAME



           intro - introduction to overview and miscellany section
    


## DESCRIPTION



           Section 7 of the manual provides overviews on various topics, and
           describes conventions and protocols, character set standards, the
           standard filesystem layout, and miscellaneous other things.
    


## NOTES



       **Authors and copyright conditions**
           Look at the header of the manual page source for the author(s) and
           copyright conditions.  Note that these can be different from page
           to page!
    


* * *
# mlx5dv

## NAME



           mlx5dv - Direct verbs for mlx5 devices
           This is low level access to mlx5 devices to perform data path
           operations, without general branching performed by
           ibv_post_send(3).
    


## DESCRIPTION



           The libibverbs API is an abstract one. It is agnostic to any
           underlying provider specific implementation. While this
           abstraction has the advantage of user applications portability it
           has a performance penalty. For some applications optimizing
           performance is more important than portability.
    
           The mlx5 direct verbs API is intended for such applications.  It
           exposes mlx5 specific low level data path
           (send/receive/completion) operations, allowing the application to
           bypass the libibverbs data path API.
    
           This interface consists from one hardware specific header file
           with relevant inline functions and conversion logic from ibverbs
           structures to mlx5 specific structures.
    
           The direct include of mlx5dv.h together with linkage to mlx5
           library will allow usage of this new interface.
    
           Once an application uses the direct flow the locking scheme is
           fully managed by itself. There is an expectation that no mixed
           flows in the data path for both direct/non-direct access will be
           by same application.
    


## NOTES



           All Mellanox NIC devices starting from Connect-IB (Connect-IB,
           ConnectX-4, ConnectX-4Lx, ConnectX-5, ...) implement the mlx5 API,
           thus using the mlx5 direct verbs does not limit the applications
           to a single NIC HW device thus keeping some level of portability.
    


* * *
# systemd.image-filter

## NAME



           systemd.image-filter - Disk Image Dissection Filter
    


## DESCRIPTION



           In systemd, whenever a disk image (DDI) implementing the
           **Discoverable Partitions Specification******[1] is activated, a filter
           may be specified controlling which partitions to consider for
           mounting. Such a disk image dissection filter is a string that
           contains per-partition-type patterns, separated by colons (":").
           The individual rules consist of a partition identifier, an equal
           sign ("="), and a shell globbing pattern applied to the GPT label
           string of the partition. Seeglob(7) for details on shell
           globbing.
    
           The partition identifiers currently defined are: **root** , **usr** , **home** ,
           **srv** , **esp** , **xbootldr** , **swap** , **root-verity** , **root-verity-sig** ,
           **usr-verity** , **usr-verity-sig** , **tmp** , **var**. These identifiers match the
           relevant partition types in the Discoverable Partitions
           Specification, but are agnostic to CPU architectures.
    


## USE



           Various systemd components that support operating with disk images
           support a **--image-filter=** command line option to specify the image
           filter to use. If no filter is specified all partitions in
           partition table are considered and no per-label filtering is
           applied (except that partitions with the "_empty" label are always
           ignored).
    
           For the host root file system image itself
           systemd-gpt-auto-generator(8) is responsible for processing the
           GPT partition table and making use of the included discoverable
           partitions. It accepts an image filter via the kernel command line
           option **systemd.image_filter=**.
    


## EXAMPLES



           The following image filter string dictates that for the root file
           system partition only partitions shall be considered whose label
           begins with "ParticleOS-". For the /usr/ partition the precise
           label "ParticleOS_47110815" is required.
    
               root=ParticleOS-*:usr=ParticleOS_47110815
    


## NOTES



            1. Discoverable Partitions Specification
               https://uapi-group.org/specifications/specs/discoverable_partitions_specification
    


* * *
# error::fault

## NAME



           error::fault - memory access faults
    


## DESCRIPTION



           Read or write faults can occur during the operation of a systemtap
           script, if the script causes dereferencing of a pointer that turns
           out to be invalid.  This can be caused by using context variables
           that do not happen to have valid values, or perhaps references to
           memory that is unavailable at that moment due to paging.
    
           These fault conditions are benign because they are caught by the
           systemtap runtime, which cleanly terminates the script.  If quick
           termination is not desired, consider using the _--skip-badvars_ or
           _--suppress-handler-errors_ or _-DMAXERRORS=NN_ stap options, or
           wrapping relevant parts of the probe handlers in a _try_ /_catch_
           block.
    
           It may be possible to adjust the target program, to make it more
           likely that needed context variables are paged in when systemtap
           looks for them.  Consider adding some lightweight processing on
           the key variables, like a _strlen(foo)_ for a string, or iterating
           across elements of an array or linked list, or touching a few
           bytes of a heap-allocated block.  The idea is to trigger any page
           faults in the target program, before systemtap would need to (but
           can't).
    


* * *
# user-keyring

## NAME



           user-keyring - per-user keyring
    


## DESCRIPTION



           The user keyring is a keyring used to anchor keys on behalf of a
           user.  Each UID the kernel deals with has its own user keyring
           that is shared by all processes with that UID.  The user keyring
           has a name (description) of the form __uid. <UID>_ where _< UID>_ is the
           user ID of the corresponding user.
    
           The user keyring is associated with the record that the kernel
           maintains for the UID.  It comes into existence upon the first
           attempt to access either the user keyring, the
           user-session-keyring(7), or the session-keyring(7).  The keyring
           remains pinned in existence so long as there are processes running
           with that real UID or files opened by those processes remain open.
           (The keyring can also be pinned indefinitely by linking it into
           another keyring.)
    
           Typically, the user keyring is created by pam_keyinit(8) when a
           user logs in.
    
           The user keyring is not searched by default by request_key(2).
           When pam_keyinit(8) creates a session keyring, it adds to it a
           link to the user keyring so that the user keyring will be searched
           when the session keyring is.
    
           A special serial number value, **KEY_SPEC_USER_KEYRING** , is defined
           that can be used in lieu of the actual serial number of the
           calling process's user keyring.
    
           From the keyctl(1) utility, '**@u** ' can be used instead of a numeric
           key ID in much the same way.
    
           User keyrings are independent of clone(2), fork(2), vfork(2),
           execve(2), and _exit(2) excepting that the keyring is destroyed
           when the UID record is destroyed when the last process pinning it
           exits.
    
           If it is necessary for a key associated with a user to exist
           beyond the UID record being garbage collected—for example, for use
           by a cron(8) script—then the persistent-keyring(7) should be used
           instead.
    
           If a user keyring does not exist when it is accessed, it will be
           created.
    


* * *
# ipc_namespaces

## NAME



           ipc_namespaces - overview of Linux IPC namespaces
    


## DESCRIPTION



           IPC namespaces isolate certain IPC resources, namely, System V IPC
           objects (see sysvipc(7)) and (since Linux 2.6.30) POSIX message
           queues (see mq_overview(7)).  The common characteristic of these
           IPC mechanisms is that IPC objects are identified by mechanisms
           other than filesystem pathnames.
    
           Each IPC namespace has its own set of System V IPC identifiers and
           its own POSIX message queue filesystem.  Objects created in an IPC
           namespace are visible to all other processes that are members of
           that namespace, but are not visible to processes in other IPC
           namespaces.
    
           The following _/proc_ interfaces are distinct in each IPC namespace:
    
           •  The POSIX message queue interfaces in _/proc/sys/fs/mqueue_.
    
           •  The System V IPC interfaces in _/proc/sys/kernel_ , namely:
              _msgmax_ , _msgmnb_ , _msgmni_ , _sem_ , _shmall_ , _shmmax_ , _shmmni_ , and
              _shm_rmid_forced_.
    
           •  The System V IPC interfaces in _/proc/sysvipc_.
    
           When an IPC namespace is destroyed (i.e., when the last process
           that is a member of the namespace terminates), all IPC objects in
           the namespace are automatically destroyed.
    
           Use of IPC namespaces requires a kernel that is configured with
           the **CONFIG_IPC_NS** option.
    


* * *
# libdrop_ambient

## NAME



           libdrop_ambient - force application started with ambient
           capabilities to drop them
    


## DESCRIPTION



           This library can be used via LD_PRELOAD to force an application
           started with ambient capabilities to drop them. It leaves other
           capabilities intact. This can also be linked against and
           automatically does the right thing. You do not need to make any
           calls into the library because all the work is done in the
           constructor which runs before main() is called.
    


* * *
# error::inode-uprobes

## NAME



           error::inode-uprobes - limitations of inode-uprobes
    


## DESCRIPTION



           The uprobes kernel facility introduced in Linux 3.5 aims to
           supplant the earlier out-of-tree utrace patch to enable user-space
           probing.  There have been some functional limitations in inode-
           uprobes that preclude some systemtap constructs.  Over time, we
           hope these regressions will be corrected.
    
           function.return probes
                  _process.function().return_ probes require "return-probes" or
                  "uretprobes" functionality, which was not implemented in
                  the builtin inode-uprobes until kernel 3.10.  If you cannot
                  upgrade your kernel, consider using _process.statement()_
                  probes placed on source line numbers at the function's
                  return statements.
    
           function.statement.absolute probes
                  In utrace-equipped kernels, systemtap made it possible to
                  address probes by literal addresses in the process virtual
                  memory address space.  The new inode-uprobes does not have
                  this capability.
    


* * *
# pathname

## NAME



           pathname, filename - how pathnames are encoded and interpreted
    


## DESCRIPTION



           Some system calls allow you to pass a pathname as a parameter.
           When writing code that deals with pathnames, there are kernel-
           space requirements that you must comply with, and user-space
           requirements that you should comply with.
    
           The kernel stores pathnames as C strings, that is, sequences of
           non-null bytes terminated by a null byte.  There are a few general
           rules that apply to all pathnames:
    
           •  The last byte in the sequence needs to be a null byte.
    
           •  Any other bytes in the sequence need to be non-null bytes.
    
           •  A 0x2F byte (_'/'_) is always interpreted as a directory
              separator, and cannot be part of a filename.
    
           •  A pathname can be at most **PATH_MAX** bytes long (see
              limits.h(0p)).  A pathname that's longer than **PATH_MAX** bytes
              can be split into multiple smaller pathnames and opened
              piecewise using openat(2).
    
           •  A filename can be at most a certain number of bytes long.  The
              number is filesystem-specific (see **_PC_NAME_MAX** in
              fpathconf(3)).  For maximum portability, programs should be
              able to handle filenames that are as long as the relevant
              filesystems will allow.  For maximum portability, programs and
              users should limit the length of their own pathnames to
              **NAME_MAX** bytes (see limits.h(0p)).
    
           Some filesystems or APIs may apply further restrictions, such as
           requiring shorter filenames, or restricting the allowed bytes in a
           filename.
    
           For maximum interoperability, programs and users should also limit
           the characters that they use for their own pathnames to characters
           in the POSIX Portable Filename Character Set 
           ⟨https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/V1_chap03.html#tag_03_265⟩.
    


* * *
# error::reporting

## NAME



           error::reporting - systemtap error reporting
    


## COMMERCIAL SUPPORT



           If you have a commercial support agreement with your OS
           distributor that covers this software, we recommend getting your
           money's worth by using their problem reporting systems first.
    


## COMMUNITY SUPPORT



           Systemtap community & volunteer developers are eager to hear
           problem reports, so they can improve the software.  Various ways
           to contact them include:
    
           public mailing list
                  systemtap@sourceware.org
    
           public IRC
                  #systemtap on irc.oftc.net, use fpaste.org for snippets of
                  text
    
           public bugzilla
                  http://sourceware.org/bugzilla/
    


## INFORMATION TO COLLECT



           In general, please include information about your platform,
           systemtap version, your scripts & custom tapsets, systemtap
           invocation, actual behavior / errors seen, and expected behavior.
           The _stap-report_ script collects useful system/kernel information
           that helps describe the OS environment; please include its output.
    


* * *
# sysvipc

## NAME



           sysvipc - System V interprocess communication mechanisms
    


## DESCRIPTION



           System V IPC is the name given to three interprocess communication
           mechanisms that are widely available on UNIX systems: message
           queues, semaphore, and shared memory.
    
       **Message queues**
           System V message queues allow data to be exchanged in units called
           messages.  Each message can have an associated priority.  POSIX
           message queues provide an alternative API for achieving the same
           result; see mq_overview(7).
    
           The System V message queue API consists of the following system
           calls:
    
           msgget(2)
                  Create a new message queue or obtain the ID of an existing
                  message queue.  This call returns an identifier that is
                  used in the remaining APIs.
    
           msgsnd(2)
                  Add a message to a queue.
    
           msgrcv(2)
                  Remove a message from a queue.
    
           msgctl(2)
                  Perform various control operations on a queue, including
                  deletion.
    
       **Semaphore sets**
           System V semaphores allow processes to synchronize their actions.
           System V semaphores are allocated in groups called sets; each
           semaphore in a set is a counting semaphore.  POSIX semaphores
           provide an alternative API for achieving the same result; see
           sem_overview(7).
    
           The System V semaphore API consists of the following system calls:
    
           semget(2)
                  Create a new set or obtain the ID of an existing set.  This
                  call returns an identifier that is used in the remaining
                  APIs.
    
           semop(2)
                  Perform operations on the semaphores in a set.
    
           semctl(2)
                  Perform various control operations on a set, including
                  deletion.
    
       **Shared memory segments**
           System V shared memory allows processes to share a region a memory
           (a "segment").  POSIX shared memory is an alternative API for
           achieving the same result; see shm_overview(7).
    
           The System V shared memory API consists of the following system
           calls:
    
           shmget(2)
                  Create a new segment or obtain the ID of an existing
                  segment.  This call returns an identifier that is used in
                  the remaining APIs.
    
           shmat(2)
                  Attach an existing shared memory object into the calling
                  process's address space.
    
           shmdt(2)
                  Detach a segment from the calling process's address space.
    
           shmctl(2)
                  Perform various control operations on a segment, including
                  deletion.
    
       **IPC namespaces**
           For a discussion of the interaction of System V IPC objects and
           IPC namespaces, see ipc_namespaces(7).
    


* * *
# babeltrace2-plugin-utils

## NAME



           babeltrace2-plugin-utils - Babeltrace 2: Common graph utilities
           plugin
    


## DESCRIPTION



           The Babeltrace 2 **utils** plugin contains common, generic utility
           component classes which you can use in any processing graph.
    
           See babeltrace2-intro(7) to learn more about the Babeltrace 2
           project and its core concepts.
    


## COMPONENT CLASSES



           **filter.utils.muxer**
               Muxes messages by time.
    
               See babeltrace2-filter.utils.muxer(7).
    
           **filter.utils.trimmer**
               Discards all the consumed messages with a time outside a given
               time range, effectively “cutting” trace streams.
    
               See babeltrace2-filter.utils.trimmer(7).
    
           **sink.utils.counter**
               Prints the number of consumed messages, either once at the end
               or periodically.
    
               See babeltrace2-sink.utils.counter(7).
    
           **sink.utils.dummy**
               Consumes messages and discards them (does nothing with them).
    
               This is useful for testing and benchmarking a trace processing
               graph application, for example.
    
               See babeltrace2-sink.utils.dummy(7).
    


## BUGS



           If you encounter any issue or usability problem, please report it
           on the Babeltrace bug tracker (see
           <https://bugs.lttng.org/projects/babeltrace>).
    


## RESOURCES



           The Babeltrace project shares some communication channels with the
           LTTng project (see <https://lttng.org/>).
    
           •   Babeltrace website (see <https://babeltrace.org/>)
    
           •   Mailing list (see <https://lists.lttng.org>) for support and
               development: **lttng-dev@lists.lttng.org**
    
           •   IRC channel (see <irc://irc.oftc.net/lttng>): **#lttng** on
               **irc.oftc.net**
    
           •   Bug tracker (see <https://bugs.lttng.org/projects/babeltrace>)
    
           •   Git repository (see
               <https://git.efficios.com/?p=babeltrace.git>)
    
           •   GitHub project (see <https://github.com/efficios/babeltrace>)
    
           •   Continuous integration (see
               <https://ci.lttng.org/view/Babeltrace/>)
    
           •   Code review (see
               <https://review.lttng.org/q/project:babeltrace>)
    


* * *
# uts_namespaces

## NAME



           uts_namespaces - overview of Linux UTS namespaces
    


## DESCRIPTION



           UTS namespaces provide isolation of two system identifiers: the
           hostname and the NIS domain name.  These identifiers are set using
           sethostname(2) and setdomainname(2), and can be retrieved using
           uname(2), gethostname(2), and getdomainname(2).  Changes made to
           these identifiers are visible to all other processes in the same
           UTS namespace, but are not visible to processes in other UTS
           namespaces.
    
           When a process creates a new UTS namespace using clone(2) or
           unshare(2) with the **CLONE_NEWUTS** flag, the hostname and domain
           name of the new UTS namespace are copied from the corresponding
           values in the caller's UTS namespace.
    
           Use of UTS namespaces requires a kernel that is configured with
           the **CONFIG_UTS_NS** option.
    


* * *
# notifier

## NAME



           notifier - cups notification interface
    


## SYNOPSIS



           **notifier** _recipient_ [ _user-data_ ]
    


## DESCRIPTION



           The CUPS notifier interface provides a standard method for adding
           support for new event notification methods to CUPS.  Each notifier
           delivers one or more IPP events from the standard input to the
           specified recipient.
    
           Notifiers **MUST** read IPP messages from the standard input using the
           **ippNew**() and **ippReadFile**() functions and exit on error.  Notifiers
           are encouraged to exit after a suitable period of inactivity,
           however they may exit after reading the first message or stay
           running until an error is seen.  Notifiers inherit the environment
           and can use the logging mechanism documented in filter(7).
    


* * *
# termio

## NAME



           termio - System V terminal driver interface
    


## DESCRIPTION



           **termio** is the name of the old System V terminal driver interface.
           This interface defined a _termio_ structure used to store terminal
           settings, and a range of ioctl(2) operations to get and set
           terminal attributes.
    
           The **termio** interface is now obsolete: POSIX.1-1990 standardized a
           modified version of this interface, under the name **termios**.  The
           POSIX.1 data structure differs slightly from the System V version,
           and POSIX.1 defined a suite of functions to replace the various
           ioctl(2) operations that existed in System V.  (This was done
           because ioctl(2) was unstandardized, and its variadic third
           argument does not allow argument type checking.)
    
           If you're looking for a page called "termio", then you can
           probably find most of the information that you seek in either
           termios(3) or ioctl_tty(2).
    


* * *
# error::process-tracking

## NAME



           warning::process-tracking - process-tracking facilities are not
           available
    


## DESCRIPTION



           These errors and warnings occur when the kernel systemtap is
           running on lacks support for user-space process tracking
           facilities.
    
       **COMPILE-TIME ERROR**
           The error
    
                  ERROR: user-space process-tracking facilities not available
    
           occurs when the script contains a uprobes probe point that the
           current kernel does not support.
    
       **RUNTIME WARNINGS**
           The warning,
    
                  WARNING: process-tracking facilities are not available in this kernel
    
           and the related message,
    
                  WARNING: cannot track target in process '...'
    
           both occur at runtime when running on a kernel (generally an older
           version) that has neither utrace functionality nor an acceptable
           substitute.
    
           The script should still load and run. However, probes that rely on
           availability of process-tracking facilities will silently fail to
           trigger.
    


## RESOLVING THE ISSUE



           If process-tracking functionality is absolutely necessary, either
           a kernel version newer than 3.5 is needed, or an older version
           must be compiled with appropriate utrace patches.
    


* * *
# hnsdv

## NAME



           hnsdv - Direct verbs for hns devices
    
           This provides low level access to hns devices to perform direct
           operations, without general branching performed by libibverbs.
    


## DESCRIPTION



           The libibverbs API is an abstract one.  It is agnostic to any
           underlying provider specific implementation.  While this
           abstraction has the advantage of user applications portability it
           has a performance penalty.  Besides, some provider specific
           features that are directly facing users are not available through
           libibverbs.  For some applications these demands are more
           important than portability.
    
           The hns direct verbs API is intended for such applications.  It
           exposes hns specific low level operations, allowing the
           application to bypass the libibverbs API and enable some hns
           specific features.
    
           The direct include of hnsdv.h together with linkage to hns library
           will allow usage of this new interface.
    


* * *
# ditroff

## Name



           ditroff - device-independent typesetter roff
    


## Description



           The name _ditroff_ refers to a historical development stage of the
           _roff_(7) text processing system.  In _roff_ systems extant today, the
           name _troff_ is a synonym for _ditroff_.
    
           Early versions of _roff_ by Joe Ossanna generated two programs from
           the same sources, using conditional compilation to distinguish
           them.  _nroff_ produced text-oriented TTY output, while _troff_
           generated graphical output for exactly one output device, the Wang
           Graphic Systems CAT phototypesetter.
    
           In 1979, Brian Kernighan rewrote _troff_ to support more devices by
           creating an intermediate output format for _troff_ that could be fed
           into postprocessor programs which actually do the printout on the
           device.  Kernighan's version marks what is known as “classical
           troff” today.  In order to distinguish it from Ossanna's original
           version, it was called _ditroff_ (_d_ evice _i_ ndependent _t_ roff) on some
           systems, though this naming isn't mentioned in the classical
           documentation.
    
           Today, all existing _roff_ systems are based on Kernighan's multi-
           device _troff_.  The distinction between _troff_ and _ditroff_ is no
           longer necessary; each modern _troff_ provides the complete
           functionality of _ditroff_.
    
           The easiest way to use _ditroff_ is via the GNU _roff_ system, _groff_.
           The _groff_(1) program is a wrapper around _(di)troff_ that
           automatically handles device postprocessing.
    


## Authors



           This document was written by Bernd Warken ⟨groff-bernd.warken-72@
           web.de⟩.
    


## See also



           CSTR #54
                  refers to the 1992 revision of the _Nroff/Troff User's_
                  _Manual_ by J. F. Ossanna and Brian Kernighan.
    
           CSTR #97
                  refers to _A Typesetter-independent TROFF_ , by Brian
                  Kernighan and is the original documentation of the first
                  multi-device _troff_ (_ditroff_).
    
           _roff_(7)
                  provides a history and conceptual overview of _roff_ systems.
    
           _troff_(1)
                  describes the GNU implementation of _(di)troff_.
    
           _groff_(1)
                  documents the GNU _roff_ program and includes pointers to
                  further documentation about _groff_.
    
           _groff_out_(5)
                  describes the _groff_ version of the intermediate output
                  language, the basis for multi-device output.
    


* * *
# efadv

## NAME



           efadv - Direct verbs for efa devices
    
           This provides low level access to efa devices to perform direct
           operations, without general branching performed by libibverbs.
    


## DESCRIPTION



           The libibverbs API is an abstract one.  It is agnostic to any
           underlying provider specific implementation.  While this
           abstraction has the advantage of user applications portability, it
           has a performance penalty.  For some applications optimizing
           performance is more important than portability.
    
           The efa direct verbs API is intended for such applications.  It
           exposes efa specific low level operations, allowing the
           application to bypass the libibverbs API.
    
           The direct include of efadv.h together with linkage to efa library
           will allow usage of this new interface.
    


* * *
# error::pass1

## NAME



           error::pass1 - systemtap pass-1 errors
    


## DESCRIPTION



           Errors that occur during pass 1 (parsing) usually mean a basic
           syntax error of some sort occurred in the systemtap script.  There
           are several classes of problems possible:
    
           plain syntax error
                  The systemtap script parser detects a large variety of
                  errors, such as missing operands, bad punctuation.  It
                  tries to list what kinds of tokens it was expecting to see,
                  and will show the region of the source code with the
                  problem.  Please review the stap(1) man page and/or the
                  tutorial, to correct the script's syntax.
    
           grammar ambiguities
                  There is at least one known ambiguity in the systemtap
                  grammar.  It relates to the optionality of _;_ (semicolon)
                  separators between statements, and the _++_ and _--_
                  increment/decrement operators.  If the parser indicates an
                  error, consider adding some explicit _;_ separators between
                  nearby statements and try again.
    
           missing command line arguments
                  A systemtap script that uses the _$N_ and _@N_ constructs for
                  substituting in command-line options may fail if not enough
                  options were given on the stap command line.
    
           compatibility changes
                  Some versions of systemtap have changed the language
                  incompatibly, for example by adding the try/catch keywords
                  for exception handling.  In such cases, rerun systemtap
                  with the _--compatibility=VERSION_ option, substituting the
                  last systemtap version where your script was known to work.
                  You may also check the release-history NEWS file for
                  compatibility changes.
    


## GATHERING MORE INFORMATION



           Increasing the verbosity of pass-1 with an option such as _--vp 1_
           can help pinpoint the problem.
    


* * *
# shm_overview

## NAME



           shm_overview - overview of POSIX shared memory
    


## DESCRIPTION



           The POSIX shared memory API allows processes to communicate
           information by sharing a region of memory.
    
           The interfaces employed in the API are:
    
           shm_open(3)
                  Create and open a new object, or open an existing object.
                  This is analogous to open(2).  The call returns a file
                  descriptor for use by the other interfaces listed below.
    
           ftruncate(2)
                  Set the size of the shared memory object.  (A newly created
                  shared memory object has a length of zero.)
    
           mmap(2)
                  Map the shared memory object into the virtual address space
                  of the calling process.
    
           munmap(2)
                  Unmap the shared memory object from the virtual address
                  space of the calling process.
    
           shm_unlink(3)
                  Remove a shared memory object name.
    
           close(2)
                  Close the file descriptor allocated by shm_open(3) when it
                  is no longer needed.
    
           fstat(2)
                  Obtain a _stat_ structure that describes the shared memory
                  object.  Among the information returned by this call are
                  the object's size (_st_size_), permissions (_st_mode_), owner
                  (_st_uid_), and group (_st_gid_).
    
           fchown(2)
                  To change the ownership of a shared memory object.
    
           fchmod(2)
                  To change the permissions of a shared memory object.
    
       **Versions**
           POSIX shared memory is supported since Linux 2.4 and glibc 2.2.
    
       **Persistence**
           POSIX shared memory objects have kernel persistence: a shared
           memory object will exist until the system is shut down, or until
           all processes have unmapped the object and it has been deleted
           with shm_unlink(3)
    
       **Linking**
           Programs using the POSIX shared memory API must be compiled with
           _cc -lrt_ to link against the real-time library, _librt_.
    
       **Accessing shared memory objects via the filesystem**
           On Linux, shared memory objects are created in a (tmpfs(5))
           virtual filesystem, normally mounted under _/dev/shm_.  Since Linux
           2.6.19, Linux supports the use of access control lists (ACLs) to
           control the permissions of objects in the virtual filesystem.
    


## NOTES



           Typically, processes must synchronize their access to a shared
           memory object, using, for example, POSIX semaphores.
    
           System V shared memory (shmget(2), shmop(2), etc.) is an older
           shared memory API.  POSIX shared memory provides a simpler, and
           better designed interface; on the other hand POSIX shared memory
           is somewhat less widely available (especially on older systems)
           than System V shared memory.
    


* * *
# operator

## NAME



           operator - C operator precedence and order of evaluation
    


## DESCRIPTION



           This manual page lists C operators and their precedence in
           evaluation.
    
           **Operator                            Associativity   Notes**
           [] () . -> ++ --                    left to right   [1]
           ++ -- & * + - ~ ! sizeof            right to left   [2]
           (type)                              right to left
           * / %                               left to right
           + -                                 left to right
           << >>                               left to right
           < > <= >=                           left to right
           == !=                               left to right
           &                                   left to right
           ^                                   left to right
           |                                   left to right
           &&                                  left to right
           ||                                  left to right
           ?:                                  right to left
           = *= /= %= += -= <<= >>= &= ^= |=   right to left
           ,                                   left to right
    
           The following notes provide further information to the above
           table:
    
           [1]  The ++ and -- operators at this precedence level are the
                postfix flavors of the operators.
           [2]  The ++ and -- operators at this precedence level are the
                prefix flavors of the operators.
    


* * *
# manadv

## NAME



           manadv - Direct verbs for mana devices
    
           This provides low level access to mana devices to perform direct
           operations, without general branching performed by libibverbs.
    


## DESCRIPTION



           The libibverbs API is an abstract one.  It is agnostic to any
           underlying provider specific implementation.  While this
           abstraction has the advantage of user applications portability, it
           has a performance penalty.  For some applications optimizing
           performance is more important than portability.
    
           The mana direct verbs API is intended for such applications.  It
           exposes mana specific low level operations, allowing the
           application to bypass the libibverbs API.
    
           This version of the driver supports one QP type:
           IBV_QPT_RAW_PACKET.  To use this QP type, the application is
           required to use manadv_set_context_attr() to set external buffer
           allocators for allocating queues, and use manadv_init_obj() to
           obtain all the queue information.  The application implements its
           own queue operations, bypassing libibverbs API for
           sending/receiving traffic over the queues.  At hardware layer,
           IBV_QPT_RAW_PACKET QP shares the same hardware resource as the
           Ethernet port used in the kernel.  The software checks for
           exclusive use of the hardware Ethernet port, and will fail the QP
           creation if the port is already in use.  To create a
           IBV_QPT_RAW_PACKET on a specified port, the user needs to
           configure the system in such a way that this port is not used by
           any other software (including the Kernel).  If the port is used,
           ibv_create_qp() will fail with errno set to EBUSY.
    
           The direct include of manadv.h together with linkage to mana
           library will allow usage of this new interface.
    


* * *
# warning::buildid

## NAME



           warning::buildid - build-id verification failures
    


## DESCRIPTION



           Because systemtap's script translation / execution stages may be
           executed at different times and places, it is sometimes necessary
           to verify certain invariants.  One such invariant is that if a
           script was informed by translate-time analysis of executables,
           then those same executables need to be used at run time.  This
           checking is done based upon the build-id, a binary hash that
           modern (post-2007) compilers/toolchains add as an _NT_GNU_BUILD_ID_
           ELF note to object files and executables.  Use the _readelf -n_
           command to examine the build-ids of binaries, if you are
           interested.
    
           Only scripts are sensitive to executables' build-ids: generally
           those that perform deep analysis of the binaries or their
           debuginfo.  For example, scripts that place _.function_ or
           _.statement_ probes, or use stack backtrace-related tapset functions
           may be sensitive.  Other scripts that rely only on _process.mark_ or
           _kernel.trace_ probes do not require debuginfo.  See the DWARF
           DEBUGINFO section in the stapprobes(3stap) man page.
    
           During translation, systemtap saves a copy of the relevant files'
           build-ids within the compiled modules.  At run-time, the modules
           compare the saved ones to the actual run-time build-ids in memory.
           The warning message indicates that they did not match, so the
           module will decline placing a probe that was computed based upon
           obsolete data.  This is important for safety, as placing them at
           an inappropriate address could crash the programs.  However, this
           is not necessarily a fatal error, since probes unrelated to the
           mismatching binaries may operate.
    
           A build-id mismatch could be caused by a few different situations.
           The main one is where the executable versions or architecture were
           different between the systemtap translation and execution
           times/places.  For example, one may run a stap-server on a
           slightly different version of the OS distribution.  Someone may
           have rebuilt a new kernel image, but preserved the previous
           version numbers.  The kernel running on the workstation may be
           slightly different from the version being targeted - perhaps due
           to a pending kernel upgrade leaving different files on disk versus
           running in memory.  If your OS distribution uses separate
           debuginfo packages, the split _.debug_ files may not exactly match
           the main binaries.
    
           To disable build-id verification warnings, if one is confident
           that they are an artefact of build accidents rather than a real
           mismatch, one might try the _-DSTP_NO_BUILDID_CHECK_ option.
    


* * *
# babeltrace2-plugin-text

## NAME



           babeltrace2-plugin-text - Babeltrace 2: Plain text plugin
    


## DESCRIPTION



           The Babeltrace 2 **text** plugin contains component classes which read
           or write plain text data.
    
           See babeltrace2-intro(7) to learn more about the Babeltrace 2
           project and its core concepts.
    


## COMPONENT CLASSES



           **source.text.dmesg**
               Reads the lines of a Linux kernel ring buffer, that is, the
               output of the dmesg(1) tool, and emits each line as an event
               message.
    
               See babeltrace2-source.text.dmesg(7).
    
           **sink.text.details**
               Deterministically prints the messages it consumes with details
               to the standard output.
    
               See babeltrace2-sink.text.details(7).
    
           **sink.text.pretty**
               Pretty-prints the messages it consumes to the standard output
               or to a file.
    
               This is equivalent to the **text** output format of **babeltrace**(1)
               (Babeltrace 1).
    
               See babeltrace2-sink.text.pretty(7).
    


## BUGS



           If you encounter any issue or usability problem, please report it
           on the Babeltrace bug tracker (see
           <https://bugs.lttng.org/projects/babeltrace>).
    


## RESOURCES



           The Babeltrace project shares some communication channels with the
           LTTng project (see <https://lttng.org/>).
    
           •   Babeltrace website (see <https://babeltrace.org/>)
    
           •   Mailing list (see <https://lists.lttng.org>) for support and
               development: **lttng-dev@lists.lttng.org**
    
           •   IRC channel (see <irc://irc.oftc.net/lttng>): **#lttng** on
               **irc.oftc.net**
    
           •   Bug tracker (see <https://bugs.lttng.org/projects/babeltrace>)
    
           •   Git repository (see
               <https://git.efficios.com/?p=babeltrace.git>)
    
           •   GitHub project (see <https://github.com/efficios/babeltrace>)
    
           •   Continuous integration (see
               <https://ci.lttng.org/view/Babeltrace/>)
    
           •   Code review (see
               <https://review.lttng.org/q/project:babeltrace>)
    


* * *
# warning::symbols

## NAME



           warning::symbols - systemtap missing-symbols warnings
    


## DESCRIPTION



           For some probing operations, where DWARF debugging data is not
           available, systemtap needs ELF symbols for the relevant binaries.
           This allows at least probe addresses to be calculated, some
           variables resolved, and with @cast() and headers, maybe even some
           types.
    
           kernel symbol table
                  Systemtap may need a linux-build style **System.map** file to
                  find addresses of kernel functions/data.  It may be
                  possible to create it by hand:
    
                  % su
                  # cp /proc/kallsyms /boot/System.map-`uname -r`
                  or
                  # nm /lib/modules/`uname -r`/build/vmlinux > /boot/System.map-`uname -r`
    
           minisymbols
                  On some systems, binaries may be compiled with a subset of
                  symbols useful for function tracing and backtraces.  This
                  'Minisymbols' is a xz compressed section labeled .gnu_de‐
                  bugdata.  Support for minisymbols relies on elfutils ver‐
                  sion 0.156 or later.
    
           compressed symbols
                  On some systems, symbols may be available, but compressed
                  into _.zdebug_*_ sections.  Support for compressed symbols
                  relies on elfutils version 0.153 or later.
    


* * *