man(1)

📦 version 1.6.1, in opensuse-leap 16.0

🌈 man(1) — the flom man page 🌈

Okay bestie, welcome to the flom page in the man(1) manual — it's literally all about making commands wait their turn so everything stays iconic. 🎀

✨ NAME ✨

flom — serialize command execution

🦋 SYNOPSIS 🦋

flom [OPTION] [-- [COMMAND [ARG]...]]

💅 DESCRIPTION 💅

Run COMMAND serializing it with other commands executed under the supervision of flom or explicitly synchronizing using the FLoM API (libflom). No chaos, just orderly command energy. ✨

🔥 OPTIONS 🔥

  • -h, --help — Show help options. 🫶
  • -v, --version — Print flom version and exit. 👑
  • -x, --quiesce-exit — Stop the running daemon after current activity completion. ✨
  • -X, --immediate-exit — Stop the running daemon immediately without any quiesce time. 💀
  • -V, --verbose — Verbose mode execution. 👀
  • -c, --config-file=FILENAME — User configuration file name. Flom tries to read the system default configuration file @sysconfdir@/@_SYSTEM_CONFIG_FILENAME@, the user default configuration file ~/@_USER_CONFIG_FILENAME@, and finally this file if specified. The definitive configuration is obtained by overloading hard wired build time defaults, system defaults, user defaults, user custom, and command line options. 🧚
  • -r, --resource-name=RESOURCE — Name of the resource used for enqueuing (locking). 🌸
    • Simple resource names can be composed of alpha and digit characters, but the first character must be of type alpha (example: RA123 is OK, 123RA is not OK). Accepted resource names are described in function global_res_name_preg_init: inspect source code for more details.
    • Numeric resource names are composed by simple resource names followed by an integer value enclosed in square brackets ([ ]); examples: foo[12], bar[3], RA123[23]. Numbers must be expressed using decimal base.
    • Resource set names are obtained by concatenating simple resource names with character @_RESOURCE_SET_SEPARATOR@ (example: RED@_RESOURCE_SET_SEPARATOR@BLUE@_RESOURCE_SET_SEPARATOR@GREEN).
    • Hierarchical resource names are like absolute path filenames using @_DIR_FILE_SEPARATOR@ as the level delimiter (but a trailing delimiter is not allowed); examples: @_DIR_FILE_SEPARATOR@apple and @_DIR_FILE_SEPARATOR@apple@_DIR_FILE_SEPARATOR@pear are valid names, while @_DIR_FILE_SEPARATOR@apple@_DIR_FILE_SEPARATOR@ and @_DIR_FILE_SEPARATOR@apple@_DIR_FILE_SEPARATOR@pear@_DIR_FILE_SEPARATOR@ are not valid names.
    • Sequence resource names are composed by _s_ (non transactional) or _S_ (transactional) prefix and a simple resource name followed by an integer value enclosed in square brackets ([ ]); examples: _s_foo[12], _S_bar[3], _s_RA123[23]. Numbers must be expressed using decimal base.
    • Timestamp resource names are composed by the _t_ prefix followed by a timestamp format and by an integer value enclosed in square brackets ([ ]); examples: _t_foo.%D.%T[4], _t_bar:%S#fff[1]. Numbers must be expressed using decimal base.
    • Additional information can be retrieved from official wiki documentation: http://sourceforge.net/p/flom/wiki/Home/
  • -o, --resource-timeout=milliseconds — Default (-1): maximum enqueue time if the resource is already locked by someone else; if the resource doesn't become free before milliseconds, the command will return. A negative value means "infinite timeout" and the command will wait until the resource will become free. If the value equals zero, in case of locked resource, the command will not wait. ⏳
  • -q, --resource-quantity=number — Number of numeric resources to lock; it's meaningless if the locked resource is not of type "numeric". number must be an integer positive number. Note: only positive values are accepted, periodt. 💅
  • -e, --resource-create=yes|no — Default (yes): the command will create the resource if it was not already created by another command, otherwise (no) it will wait for resource creation or will end immediately (see -o, --resource-timeout option). Note: if used with a hierarchical resource, the behavior applies to the root level of the resource, not to the single leaf. 🦋
  • -i, --resource-idle-lifespan=milliseconds — How long a resource will be kept after last usage, default value is 0 milliseconds; this option can be used to avoid a following job that specifies -e n, --resource-create=no will wait indefinitely just because the previous task terminated too early. Warning: too many long lasting resources can waste memory and threads inside flom daemon. Note: if used with a hierarchical resource, the behavior applies to the root level of the resource, not to the single leaf. 🫶
  • -l, --lock-mode=MODE — Lock mode as defined by VMS DLM (Distributed Lock Manager). MODE can be: NullLock, ConcurrentRead, ConcurrentWrite, ProtectedRead, ProtectedWrite, Exclusive (equivalent short forms are: NL, CR, CW, PR, PW, EX). More information are available here http://en.wikipedia.org/wiki/Distributed_lock_manager#Lock_modes. 🔐
  • -s, --socket-name=FILENAME — Absolute FILENAME that must be used to create the UNIX socket used for local communication between flom command line and flom daemon; typical values are something like /tmp/something. This option is useful to share locks between different users (the default socket is per user and every user creates a different one). 🌟
  • -a, --unicast-address=IPaddress — TCP/IP address that must be used to reach a running daemon; if the daemon must be started locally, IPaddress must be a valid IP address for this host. Both IPv4 and IPv6 addresses can be used. 🌈
  • -p, --unicast-port=IPport — TCP/IP port that must be used to reach a running daemon; if the daemon must be started locally, IPport must be a port not used by another process on this host. If IPaddress (see -a, --unicast-address) is specified and IPport is not specified, the default value is @_DEFAULT_DAEMON_PORT@. 🎀
  • -A, --multicast-address=IPaddress — UDP/IP multicast address that must be used to discover the location of a running daemon; if the daemon must be started locally, IPaddress must be a valid multicast IP address for this host. Multicast IPv4 address ranges are: 224.0.0.1 - 224.0.0.255 (link-local), 239.255.0.0 - 239.255.255.255 (site-local), 239.192.0.0 - 239.195.255.255 (organization-local) and 224.0.1.0 - 238.255.255.255 (global). Multicast IPv6 addresses are documented at this URL: http://www.iana.org/assignments/ipv6-multicast-addresses/. A typical choice is an address in link-local or in site-local range. 📡
  • -P, --multicast-port=IPport — UDP/IP multicast port that must be used to discover the location of a running daemon; if the daemon must be started locally, IPport must be a port not used by another process on this host. If IPaddress (see -A, --multicast-address) is specified and IPport is not specified, the default value is @_DEFAULT_DAEMON_PORT@. 🛰️
  • --ignore-signal=SIGNAL — Ignore SIGNAL while waiting for the termination of the monitored program. SIGNAL can be a string like for example "SIGTERM" or "SIGQUIT" or a number like for example "15" or "3". The option can be specified more than once to ignore two or more signals. Some signals can not be ignored: as explained in SIGNAL(7) man page, the signals SIGKILL and SIGSTOP cannot be caught, blocked, or ignored. 🙈
  • --signal-list — Print the list of signals that can be used with --ignore-signal and exit. 📋
  • -n, --network-interface=interface — Network interface that must be used to reach IPv6 link-local addresses. It's the equivalent of the % notation that can be used for network addresses but can not be used for network aliases. Typical values are eth0, eth1 and so on. If this option is specified, only IPv6 network addresses will be used. 🧚
  • -d, --daemon-lifespan=milliseconds — Lifespan of flom daemon if activated, expressed using milliseconds. The value of milliseconds can be an integer greater than 0, equal to 0 or less than 0: values greater than 0 are interpreted as minimum daemon lifetime (in milliseconds), the value 0 is interpreted as "don't start a daemon process" and values less than 0 are interpreted as "run forever" (or until a kill message is sent to flom daemon). If not specified, the default value is @_DEFAULT_DAEMON_LIFESPAN@ milliseconds. ⏱️
  • -D, --discovery-attempts=attempts — Number of attempts (UDP/IP multicast sent datagrams) performed to locate flom daemon; if the answer to UDP/IP multicast does not arrive, auto-discovery will fail. If not specified, the default value is @_DEFAULT_DISCOVERY_ATTEMPTS@. 🔎
  • -I, --discovery-timeout=milliseconds — Timeout related to UDP/IP multicast auto-discovery feature: if the answer to UDP/IP multicast query does not arrive before this timeout, another datagram is sent (until attempts limit is reached). If not specified, the default value is @_DEFAULT_DISCOVERY_TIMEOUT@ milliseconds. ⏲️
  • --discovery-ttl=TTL — IP hop limit for outgoing UDP/IP multicast datagrams (this option may be useful if your datagrams have to traverse some router). If not specified, the default value is @_DEFAULT_DISCOVERY_TTL@. 🚦
  • --tcp-keepalive-time=seconds — FLoM daemon sets SO_KEEPALIVE attribute to every TCP/IP socket connected with a flom command; this parameter allows you to change after how many connection inactivity seconds the kernel will start to probe the TCP/IP connection. A good explanation of tcp_keepalive_time kernel parameter can be found at this URL: http://tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO. If not specified, the default value set by flom daemon is @_DEFAULT_TCP_KEEPALIVE_TIME@ seconds. 🫀
  • --tcp-keepalive-intvl=seconds — FLoM daemon sets SO_KEEPALIVE attribute to every TCP/IP socket connected with a flom command; this parameter allows you to change how many seconds the kernel will wait before a new probe of the TCP/IP connection (the connection inactivity condition already triggered before successive probes are issued). A good explanation of tcp_keepalive_intvl kernel parameter can be found at this URL: http://tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO. If not specified, the default value set by flom daemon is @_DEFAULT_TCP_KEEPALIVE_INTVL@ seconds. 💓
  • --tcp-keepalive-probes=probes — ok so the FLoM daemon sets the SO_KEEPALIVE attribute on every TCP/IP socket connected with a flom command, and this parameter lets you change how many probes for a suspicious connection the kernel will try before it terminates the connection. A good explanation of the tcp_keepalive_probes kernel parameter is at this URL: http://tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO. If you don’t specify it, the default value set by the flom daemon is @_DEFAULT_TCP_KEEPALIVE_PROBES@ probes. 💅
  • --tls-certificate=FILENAME — PEM file containing the X.509 certificate of the peer. 🎀
  • --tls-private-key=FILENAME — PEM file containing the private key of the peer. 🔐
  • --tls-ca-certificate=FILENAME — PEM file containing the X.509 certificate of the certification authority used to sign the peers’ certificates. 🧚
  • --tls-check-peer-id=yes|no — perform peer authentication by comparing the unique ID sent by the peer (see the --unique-id option) with the content of the CN field inside the certificate presented by the peer. bestie, this is the vibe check for TLS peers. ✅
  • -T, --command-trace-file=FILENAME — file destination of the trace messages produced by the command (foreground) process; FILENAME must be an absolute path. The FLOM_TRACE_MASK environment variable must be set with an active bit for every desired module. ✨
  • -t, --daemon-trace-file=FILENAME — file destination of the trace messages produced by the daemon (background) process; FILENAME must be an absolute path. The FLOM_TRACE_MASK environment variable must be set with an active bit for every desired module. 🌸
  • --append-trace-file=yes|no — default (no): the command truncates the trace file(s); otherwise (yes) it appends to the trace file(s). The number and the name of the trace files depend on the -T, --command-trace-file and -t, --daemon-trace-file options. no cap, this is the trace-file mood switch. 🫶
  • --unique-id — print the flom unique ID and exit. iconic little info dump. 👑
  • --debug-feature=ipv6.multicast.server — activate an IPv6 multicast server (requester) for debugging purposes. 🔥
  • --debug-feature=ipv6.multicast.client — activate an IPv6 multicast client (replier) for debugging purposes. 🌈
  • --debug-feature=tls.server — activate a TLS server for debugging purposes. ⭐
  • --debug-feature=tls.client — activate a TLS client for debugging purposes. 🦋

💥 EXIT STATUS 💥

If everything runs as expected, the flom exit status is the same as the controlled (serialized) command. Sometimes an error happens and flom reports it using dedicated exit statuses — you can check them with the $? environment variable:

  • @_ES_UNABLE_TO_EXECUTE_COMMAND@: flom caught an error trying to exec (see execvp man page) COMMAND.
  • @_ES_RESOURCE_BUSY@: the resource can not be locked because it’s already locked by someone else — have you used --resource-timeout=0 option?! 😭
  • @_ES_GENERIC_ERROR@: flom caught some type of error and did not execute COMMAND.

🌿 ENVIRONMENT 🌿

Environment variable FLOM_TRACE_MASK can be used to activate internal detailed trace. The available flags are explained in file flom_trace.h; you can activate more than one module trace using OR operation between values. fr fr, trace-maxxing is a whole thing. 🍓

✨ EXAMPLES ✨

A list of example use cases is available at this web page: http://www.tiian.org/flom/FLoM_by_examples/FLoM_by_examples.html. go off, examples. 💖

⚠️ CAVEATS ⚠️

flom -- flom -- [COMMAND [ARG]...]

Hangs due to a deadlock: the inner flom instance waits for the lock obtained by the first flom instance. this is not the cute kind of suspense, bestie. 💀

🧚 AUTHOR 🧚

Christian Ferrari (tiian@users.sourceforge.net). 💜

🐛 REPORTING BUGS 🐛

Bugs should be reported using https://github.com/tiian/flom/issues.

Suggestions, hints and helps should be asked using http://sourceforge.net/p/flom/discussion/. 🫶

Copyright (C) 2013-2023, Christian Ferrari. License GPL version 2 http://www.gnu.org/licenses/. This is free software: you are free to change and redistribute it. There is NO WARRANTY , to the extent permitted by law. legal text ate, no notes. 💅

👀 SEE ALSO 👀

Official documentation is available at http://www.tiian.org/flom/.

A sample configuration file (@_SYSTEM_CONFIG_FILENAME@) is installed in dir @docdir@: you may copy it and customize as explained inside the sample itself.

Take a look to file flom_trace.h for FLOM_TRACE_MASK environment variable setting. 🌟

This gorgeous page is FLoM @PACKAGE_VERSION@, dated @_RELEASE_DATE@, and it’s the man(1) page — bye bestie! 💅✨

📦 where this page comes from