coccinelle: O_NDELAY → O_NONBLOCK

Apparently O_NONBLOCK is the modern name used in most documentation and
for most cases in our sources. Let's hence replace the old alias
O_NDELAY and stick to O_NONBLOCK everywhere.

tmpfiles: make "f" lines behaviour match what the documentation says

CHANGE OF BEHAVIOUR — with this commit "f" line's behaviour is altered
to match what the documentation says: if an "argument" string is
specified it is written to the file only when the file didn't exist
before. Previously, it would be appended to the file each time
systemd-tmpfiles was invoked — which is not a particularly useful
behaviour as the tool is not idempotent then and the indicated files
grow without bounds each time the tool is invoked.

I did some spelunking whether this change in behaviour would break
things, but afaics nothing relies on the previous O_APPEND behaviour of
this line type, hence I think it's relatively safe to make "f" lines
work the way the docs say, rather than adding a new modifier for it or
so.

Triggered by:

https://lists.freedesktop.org/archives/systemd-devel/2018-January/040171.html

update TODO

core: propagate TasksMax= on the root slice to sysctls

The cgroup "pids" controller is not supported on the root cgroup.
However we expose TasksMax= on it, but currently don't actually apply it
to anything. Let's correct this: if set, let's propagate things to the
right sysctls.

This way we can expose TasksMax= on all units in a somewhat sensible
way.

cgroup: when querying the number of tasks in the root slice use the pid_max sysctl

The root cgroup doesn't expose and properties in the "pids" cgroup
controller, hence we need to get the data from somewhere else.

cgroup: add proper API to determine whether our unit manags to root cgroup

util: rework system_tasks_max() to make use of procfs_tasks_max()

Let's use our new code.

util-lib: add new procfs-util.[ch] API for dealing with tasks limits

As it turns out the limit on concurrent tasks on Linux nasty to
determine, hence let's appropriate helpers for this.

cgroup: use CGROUP_LIMIT_MAX where appropriate

util: introduce more accurate definitions of TASKS_MAX

The maximum number of processes a tasks on the system is usually lower
than what pid_t would allow, and is compiled into the kernel (and
documented in proc(5)). Let's add proper defines for that, so that
we can adjust the pid_max sysctl without fearing invalid accesses.

log: remove LOG_TARGET_SAFE pseudo log target

This removes LOG_TARGET_SAFE. It's made redundant by the new
"prohibit-ipc" logging flag, as it used to have a similar effect: avoid
logging to the journal/syslog, i.e. any local services in order to avoid
deadlocks when we lock from PID 1 or its utility processes (such as
generators).

All previous users of LOG_TARGET_SAFE are switched over to the new
setting. This makes things a bit safer for all, as not even the
SYSTEMD_LOG_TARGET env var can be used to accidentally log to the
journal anymore in these programs.

log: add brief comment for log_set_open_when_needed() and log_set_always_reopen_console()

These two deserve some explanation...

log: add new "prohibit_ipc" flag to logging system

If set, we'll avoid logging to any IPC log targets, i.e. syslog or the
journal, but allow stderr, kmsg, console logging.

This is useful as PID 1 wants to turn this off explicitly as long as the
journal is not up.

Previously we'd open/close the log stream to these services whenever
needed but this is incompatible with the "open_when_needed" logic
introduced in #6915, which might open the log streams whenever it likes,
including possibly inside of the child process we fork off that'll
become journald later on. Hence, let's make this all explicit, and
instead of managing when we open/close log streams add a boolean that
clearly prohibits the IPC targets when needed, so that opening can be
done at any time, but will honour this.

See: #7985

log: make log_set_upgrade_syslog_to_journal() take effect immediately

This doesn't matter much, and we don't rely on it, but I think it's much
nicer if we log_set_target() and log_set_upgrade_syslog_to_journal() can
be called in either order and have the same effect.

Add fd close support to sd_event_source

It is often the case that a file descriptor and its corresponding IO
sd_event_source share a life span. When this is the case, developers will
have to unref the event source and close the file descriptor. Instead, we
can just have the event source take ownership of the file descriptor and
close it when the event source is freed. This is especially useful when
combined with cleanup attributes and sd_event_source_unrefp().

This patch adds two new public functions:

    sd_event_source_get_io_fd_own()
    sd_event_source_set_io_fd_own()

Include time.h in sd-event.h

The time-related functions in sd-event.h take as inputs constants (CLOCK_*)
defined in time.h. By including time.h in sd-event.h, we free the developer
from having to do this manually.

update TODO

core: rework how we track which PIDs to watch for a unit

Previously, we'd maintain two hashmaps keyed by PIDs, pointing to Unit
interested in SIGCHLD events for them. This scheme allowed a specific
PID to be watched by exactly 0, 1 or 2 units.

With this rework this is replaced by a single hashmap which is primarily
keyed by the PID and points to a Unit interested in it. However, it
optionally also keyed by the negated PID, in which case it points to a
NULL terminated array of additional Unit objects also interested. This
scheme means arbitrary numbers of Units may now watch the same PID.

Runtime and memory behaviour should not be impact by this change, as for
the common case (i.e. each PID only watched by a single unit) behaviour
stays the same, but for the uncommon case (a PID watched by more than
one unit) we only pay with a single additional memory allocation for the
array.

Why this all? Primarily, because allowing exactly two units to watch a
specific PID is not sufficient for some niche cases, as processes can
belong to more than one unit these days:

1. sd_notify() with MAINPID= can be used to attach a process from a
   different cgroup to multiple units.

2. Similar, the PIDFile= setting in unit files can be used for similar
   setups,

3. By creating a scope unit a main process of a service may join a
   different unit, too.

4. On cgroupsv1 we frequently end up watching all processes remaining in
   a scope, and if a process opens lots of scopes one after the other it
   might thus end up being watch by many of them.

This patch hence removes the 2-unit-per-PID limit. It also makes a
couple of other changes, some of them quite relevant:

- manager_get_unit_by_pid() (and the bus call wrapping it) when there's
  ambiguity will prefer returning the Unit the process belongs to based on
  cgroup membership, and only check the watch-pids hashmap if that
  fails. This change in logic is probably more in line with what people
  expect and makes things more stable as each process can belong to
  exactly one cgroup only.

- Every SIGCHLD event is now dispatched to all units interested in its
  PID. Previously, there was some magic conditionalization: the SIGCHLD
  would only be dispatched to the unit if it was only interested in a
  single PID only, or the PID belonged to the control or main PID or we
  didn't dispatch a signle SIGCHLD to the unit in the current event loop
  iteration yet. These rules were quite arbitrary and also redundant as
  the the per-unit handlers would filter the PIDs anyway a second time.
  With this change we'll hence relax the rules: all we do now is
  dispatch every SIGCHLD event exactly once to each unit interested in
  it, and it's up to the unit to then use or ignore this. We use a
  generation counter in the unit to ensure that we only invoke the unit
  handler once for each event, protecting us from confusion if a unit is
  both associated with a specific PID through cgroup membership and
  through the "watch_pids" logic. It also protects us from being
  confused if the "watch_pids" hashmap is altered while we are
  dispatching to it (which is a very likely case).

- sd_notify() message dispatching has been reworked to be very similar
  to SIGCHLD handling now. A generation counter is used for dispatching
  as well.

This also adds a new test that validates that "watch_pid" registration
and unregstration works correctly.

core: unify call we use to synthesize cgroup empty events when we stopped watching any unit PIDs

This code is very similar in scope and service units, let's unify it in
one function. This changes little for service units, but for scope units
makes sure we go through the cgroup queue, which is something we should
do anyway.

core: fix manager_get_unit_by_pid() special casing of manager PID

Previously, we'd hard map PID 1 to the manager scope unit. That's wrong
however when we are run in --user mode, as the PID 1 is outside of the
subtree we manage and the manager PID might be very differently. Correct
that by checking for getpid() rather than hardcoding 1.

test: test-process-util additions

Add some extra paranoia tests that PTR_TO_PID() and PID_TO_PTR() deals
correctly with negative PID.

process-util: replace PTR_TO_PID() and PID_TO_PTR macro by inline functions

This way we gain some typesafety at no cost.

Add support for SD_BUS_DEFAULT*

Currently, sd-bus supports the ability to have thread-local default busses.
However, this is less useful than it can be since all functions which
require an sd_bus* as input require the caller to pass it. This patch adds
a new macro which allows the developer to pass a constant SD_BUS_DEFAULT,
SD_BUS_DEFAULT_USER or SD_BUS_DEFAULT_SYSTEM instead. This reduces work for
the caller.

For example:

    r = sd_bus_default(&bus);
    r = sd_bus_call_method(bus, ...);
    sd_bus_unref(bus);

Becomes:

    r = sd_bus_call_method(SD_BUS_DEFAULT, ...);

If the specified thread-local default bus does not exist, the function
calls will return -ENOPKG. No bus will ever be implicitly created.

Add support for SD_EVENT_DEFAULT

Currently, sd-event supports the ability to have a thread-local default
event loop. However, this is less useful than it can be since all functions
which require an sd_event* as input require the caller to pass it. This
patch adds a new macro which allows the developer to pass a constant
SD_EVENT_DEFAULT instead. This reduces work for the caller.

For example:

    r = sd_event_default(&e);
    r = sd_event_add_io(e, ...);
    sd_event_unref(e);

Becomes:

    r = sd_event_add_io(SD_EVENT_DEFAULT, ...);

If no thread-local default event loop exists, the function calls will
return -ENOPKG. No event loop will ever be implicitly created.

pid1: add option to disable service watchdogs

Add a "systemd.service_watchdogs=" option to the command line which
disables all service runtime watchdogs and emergency actions.

bus-util: add bool property setter

hwdb: map zoomin/out keys to up/down

Some keyboards come with a zoom see-saw or rocker which until now got
mapped to the Linux "zoomin/out" keys in hwdb. However, these keycodes
are not recognized by any major desktop. They now produce Up/Down key
events so that they can be used for scrolling.

The internet is full of instructions how to "unbreak" these keys, e. g.

  https://askubuntu.com/questions/471802/make-the-zoom-slider-of-microsoft-natural-ergonomic-keyboard-4000-and-7000-scrol
  https://unix.stackexchange.com/questions/322075/how-to-get-ms-natural-ergonomic-4000-slider-work-on-linux-mint

So let's make it official. But keep their physical meaning in comments
in case desktops start to do something useful with them at some point.

Thanks to Finn Christiansen for the original patch!

Replaces #6953

update TODO

remove canonicalize_file_name() mention from TODO

canonicalize_file_name() invocations were replaced by chase_symlinks() in
Decemeber 2016 with PR #4694, so we don't need this mention in the TODO anymore

fs-util: chase_symlinks(): prevent double free

Fixes CID #1385316.

fs-util: use _cleanup_close_ attribute

The commit f14f1806e329fe92d01f15c22a384702f0cb4ae0 introduced CHASE_SAFE
flag. When the flag is set, then `fd_parent` may not be properly closed.
This sets `_cleanup_close_` attribute to `fd_parent`.
Thus, now `fd_parent` is always closed properly.

NEWS: fix typo

unaligned: let gcc generate optimal code

on some architectures such as MIPS there are special unaligned load/store
sequences, instead of having to do bitwise accesses

https://www.linux-mips.org/wiki/Alignment

fs-util: chase_symlinks(): support empty root

The commit b1bfb848046e457f3cd623286b8cc1a5e5440023 makes chase_symlinks()
recognize empty string for root as an invalid parameter. However,
empty root is often used e.g. systemd-nspawn.
This makes chase_symlinks() support empty string safely.

Fixes #7927.

bus-message: avoid -Wnull-pointer-arithmetic warning on new clang

We just need some pointer, so use alignment directly converted
to the right type.

core: un-break PrivateDevices= by allowing it to mknod /dev/ptmx

#7886 caused PrivateDevices= to silently fail-open.
https://github.com/systemd/systemd/pull/7886#issuecomment-358542849

Allow PrivateDevices= to succeed, in creating /dev/ptmx, even though
DeviceControl=closed applies.

No specific justification was given for blocking mknod of /dev/ptmx.  Only
that we didn't seem to need it, because we weren't creating it correctly as
a device node.

fuzz: allow building fuzzers outside of oss-fuzz

Add a new -Dllvm-fuzz=true option that can be used to build against
libFuzzer and update the oss-fuzz script to work outside of the
oss-fuzz build environment.

fuzz: disable all deps when building with oss-fuzz

The fuzz targets are intended to be fast and only target systemd
code, so they don't need to call out to any dependencies. They also
shouldn't depend on shared libraries outside of libc, so we disable
every dependency when compiling against oss-fuzz. This also
simplifies the upstream build environment significantly.

fuzz: add initial fuzzing infrastructure

The fuzzers will be used by oss-fuzz to automatically and
continuously fuzz systemd.

This commit includes the build tooling necessary to build fuzz
targets, and a fuzzer for the DNS packet parser.

path-util: don't insert duplicate "/" in path_make_absolute_cwd()

When the working directory is "/" it's prettier not to insert a second
"/" in the path, even though it is technically correct.

tree-wide: port all code to use safe_getcwd()

path-util: introduce new safe_getcwd() wrapper

It's like get_current_dir_name() but protects us from
CVE-2018-1000001-style exploits:

https://www.halfdog.net/Security/2017/LibcRealpathBufferUnderflow/

path-util: don't add extra "/" when prefix already is suffixed by slash

No need to insert duplicate "/" if we can avoid it. This is particularly
relevant if the prefix passed in is the root directory.

path-util: do something useful if the prefix is "" in path_make_absolute()

Do not insert a "/" if the prefix we shall use is empty. It's a corner
case we should probably take care of.

fs-util: refuse taking a relative path to chase if "root" is specified and CHASE_PREFIX_ROOT is set

If we take a relative path we first make it absolute, based on the
current working directory. But if CHASE_PREFIX_ROOT is passe we are
supposed to make the path absolute taking the specified root path into
account, but that makes no sense if we talk about the current working
directory as that is relative to the host's root in any case. Hence,
let's refuse this politely.

fs-util: extra chase_symlink() safety check on "path" parameter

It's not clear what an empty "path" is even supposed to mean, hence
refuse.

fs-util: extra safety checks on chase_symlinks() root parameter

Let's handle root="" and root="/" safely.

parse-util: detect overflows in parse_percent_unbounded()

We shouldn't accept percentages beyon INT32_MAX and consider them
valid.

parse-util: coding style fix

Let's not rely on C's downgrade-to-bool feature to check for NUL bytes

locale-util: add freelocale() cleanup helper

virt: add comment that we need to use sscanf()

Follow-up for 13e0f9fe8334859ee86f4ff725374d1d83f5baf7.
See PR #7890 and comment in PR #7581.

man: fix broken kernel document links (#7892)

Fix parsing of features in detect_vm_xen_dom0 (#7890)

Use sscanf instead of the built-in safe_atolu because the scanned string
lacks the leading "0x", it is generated with snprintf(b, "%08x", val).
As a result strtoull handles it as octal, and parsing fails.

The initial submission already used sscanf, then parsing was replaced by
safe_atolu without retesting the updated PR.

Fixes 575e6588d ("virt: use XENFEAT_dom0 to detect the hardware domain
(#6442, #6662) (#7581)")

add false option for tests (#7778)

Currently there is no way to prevent tests from building using meson.
This introduces two problems:

1) It adds a extra 381 files to compile.
2) One of these tests explicitly requires libgcrypt to be built even if systemd
   is not using it.
3) It adds C++ to the requirements to build systemd.

When cross-compiling, this is uneccessary.

sd-dameon: also sent ucred when our UID differs from EUID

Let's be explicit, and always send the messages from our UID and never
our EUID. Previously this behaviour was conditionalized only on whether
the PID was specified, which made this non-obvious.

fs-util: add new chase_symlinks() flag CHASE_OPEN

The new flag returns the O_PATH fd of the final component, which may be
converted into a proper fd by open()ing it again through the
/proc/self/fd/xyz path.

Together with O_SAFE this provides us with a somewhat safe way to open()
files in directories potentially owned by unprivileged code, where we
want to refuse operation if any symlink tricks are played pointing to
privileged files.

fs-util: add new CHASE_SAFE flag to chase_symlinks()

When the flag is specified we won't transition to a privilege-owned
file or directory from an unprivileged-owned one. This is useful when
privileged code wants to load data from a file unprivileged users have
write access to, and validates the ownership, but want's to make sure
that no symlink games are played to read a root-owned system file
belonging to a different context.

bash-completion: loginctl: add missing options and verbs

update TODO

log: assign the realm to a variable first in log_full_errno_realm()

Let's avoid duplicate evaluation (which might have side-effects) and
assign the realm to an internal variable first, as we need it twice.

log: rework log_syntax_invalid_utf8() a bit

The macro used utf8.h functions without including that. Let's clean this
up, by moving that code inside of log.c.

Let's also make the call return -EINVAL in all cases. This is in line
with log_oom() which also returns a well-defined error code even though
it doesn#t take one.

log: minor modernizations to log_received_signal()

log: minimize includes in log.h

log.h really should only include the bare minimum of other headers, as
it is really pulled into pretty much everything else and already in
itself one of the most basic pieces of code we have.

Let's hence drop inclusion of:

1. sd-id128.h because it's entirely unneeded in current log.h
2. errno.h, dito.
3. sys/signalfd.h which we can replace by a simple struct forward
   declaration
4. process-util.h which was needed for getpid_cached() which we now hide
   in a funciton log_emergency_level() instead, which nicely abstracts
   the details away.
5. sys/socket.h which was needed for struct iovec, but a simple struct
   forward declaration suffices for that too.

Ultimately this actually makes our source tree larger (since users of
the functionality above must now include it themselves, log.h won't do
that for them), but I think it helps to untangle our web of includes a
tiny bit.

(Background: I'd like to isolate the generic bits of src/basic/ enough
so that we can do a git submodule import into casync for it)

sd-bus: drop bloom stuff, it's not needed anymore since kdbus is gone

process-util: make our freeze() routine do something useful

When we crash we freeze() our-self (or possibly we reboot the machine if
that is configured). However, calling pause() is very unhelpful thing to
do. We should at least continue to do what init systems being doing
since 70's and that is reaping zombies. Otherwise zombies start to
accumulate on the system which is a very bad thing. As that can prevent
admin from taking manual steps to reboot the machine in somewhat
graceful manner (e.g. manually stopping services, unmounting data
volumes  and calling reboot -f).

Fixes #7783

Comment the fact that some tools need to termintate their bus connect first

Revert "tree-wide: use _cleanup_(sd_bus_flush_close_unrefp) at various appropriate places"

This reverts commit 0b3c84eb7da3a8c28ac248a68228f6a7edbb2e19.

The removal of _cleanup_() usages was done on purpose, see
cf647b69baee4c478d3909c327e3d917e1563f44.

Fixes: #3543

bus-socket: slight simplification in bus_get_peercred()

util: minor tweaks to disable_core_dumps()

First, let's rename it to disable_coredumps(), as in the rest of our
codebase we spell it "coredump" rather than "core_dump", so let's stick
to that.

However, also log about failures to turn off core dumpling on LOG_DEBUG,
because debug logging is always a good idea.

nss-systemd,user-util: add a way how synthesizing "nobody" can be turned off

This is quite ugly, but provides us with an avenue for moving
distributions to define the "nobody" user properly without breaking legacy
systems that us the name for other stuff.

The idea is basically, that the distribution adopts the new definition
of "nobody" (and thus recompiles systemd with it) and then touches
/etc/systemd/dont-synthesize-nobody on legacy systems to turn off
possibly conflicting synthesizing of the nobody name by systemd.

util-lib: save/restore errno in cleanup calls

We should be careful with errno in cleanup functions, and not alter it
under any circumstances. In the safe_close cleanup handlers we are
already safe in that regard, but let's add similar protections on other
cleanup handlers that invoke system calls.

Why bother? Cleanup handlers insert code at function return in
non-obvious ways. Hence, code that sets errno and returns should not be
confused by us overrding the errno from a cleanup handler.

This is a paranoia fix only, I am not aware where this actually mattered
in real-life situations.

cocci: use strempty() at more places

This shortens the code by a few lines.

missing: add bpf() define for ARM definition

missing: fix bpf() define for Tilera

__NR_bpf syscall uses the default generic value for Tilera, e.g. 280.

tree-wide: introduce disable_core_dumps helper and port existing users

Changes the core_pattern to prevent any core dumps by the kernel. Does
nothing if we're in a container environment as this is system wide
setting.

exec-util: cast to void when return value is ignored

CID 1384262.

process-util: initialize block_signals

CID 1384240.

networkd: add support for wireguard interface type

More information may be found at wireguard.com.

networkd: add support for wireguard interface type

More information may be found at wireguard.com.

sd-netlink: add generic netlink support

This also adds the ability to incorporate arrays into netlink messages
and to determine when a netlink message is too big, used by some generic
netlink protocols.

logind: fix user_object_find()

The logic was completely borked since
e4d2984bf8514ab576a66d5ac1f1cde746bb32a3, correct that.

CID #1384234

update TODO

man: document all the new APIs we added

meson: resurrect API documentation target

We had this functionality back in Automake times, let's resurrect it.

sd-bus: remove 'hint_sync_call' parameter from various function calls

This is unused since kdbus is gone, hence remove this too. This permits
us to get rid of sd_bus_send_internal() and just implement sd_bus_send()
directly.

sd-bus: add API to optionally set a sender field on all outgoing messages

This is useful on direct connections to generate messages with valid
sender fields.

This is particularly useful for services that are accessible both
through direct connections and the broker, as it allows clients to
install matches on the sender service name, and they work the same in
both cases.

verbs: suppress debug log message if SYSTEMD_OFFLINE is not set

If SYSTEMD_OFFLINE is not set getenv_bool() for it will return -ENXIO,
which is nothing we should log about, not even at LOG_DEBUG level.

sd-bus: drop some unused fields from the sd_bus_message structure

tree-wide: make the Subscribe() method calls asynchronous too

sd-bus: accept NULL callbacks in sd_bus_call_async()

This way sd_bus_call_method_async() (which is just a wrapper around
sd_bus_call_async()) can be used to put method calls together that
expect no reply.

sd-bus: log about bus state changes

Let's unify all state changes in a new helper function, from which we
can then debug log all state changes

networkd,resolved: make use of watch_bind feature to connect to the bus

The changes both networkd and resolved to make use of the watch_bind
feature of sd-bus to connect to the system bus. This way, both daemons
can be started during early boot, and automatically and instantly
connect to the system bus as it becomes available.

This replaces prior code that used a time-based retry logic to connect
to the bus.

sd-bus: add new sd_bus_set_connected_signal() API

With this new API sd-bus can synthesize a local "Connected" signal when
the connection is fully established. It mirrors the local "Disconnected"
signal that is already generated when the connection is terminated. This
is useful to be notified when connection setup is done, in order to
start method calls then, in particular when using "slow" connection
methods (for example slow TCP, or most importantly the "watch_bind"
inotify logic).

Note that one could also use hook into the initial NameAcquired signal
received from the bus broker, but that scheme works only if we actually
connect to a bus. The benefit of "Connected" OTOH is that it works with
any kind of connection.

Ideally, we'd just generate this message unconditionally, but in order
not to break clients that do not expect this message it is opt-in.

sd-bus: add new sd_bus_is_ready() API

This new call is much light sd_bus_is_open(), but returns true only if
the connection is fully set up, i.e. after we finished with the
authentication and Hello() phase. This API is useful for clients in
particular when using the "watch_bind" feature, as that way it can be
determined in advance whether it makes sense to sync on some operation.

sd-bus: modernize how we generate the match string in sd-bus-track

strjoina() FTW!

sd-bus: drop references to legacy /var/run D-Bus socket

Let's directly reference /run instead, so that we can work without /var
being around, or with /var/run being incorrectly set up.

Note that we keep the old socket path in place when referencing the
system bus of containers, as they might be foreign operating systems,
that still don't have adopted /run, and where it makes sense to use the
standardized name instead. On local systems, we insist on /run being set
up properly however, hence this limitation does not apply.

Also, get rid of the UNIX_SYSTEM_BUS_ADDRESS and
UNIX_USER_BUS_ADDRESS_FMT defines. They had a purpose when we still did
kdbus, as we then had to support two different backends. But since
that's gone, we don't need this indirection anymore, hence settle on a
one define only.

tree-wide: install matches asynchronously

Let's remove a number of synchronization points from our service
startups: let's drop synchronous match installation, and let's opt for
asynchronous instead.

Also, let's use sd_bus_match_signal() instead of sd_bus_add_match()
where we can.

tree-wide: make name requesting asynchronous in all our services

This optimizes service startup a bit, and makes it less prone to
deadlocks.

sd-bus: when disconnecting a slot, also reset its memory

Yes, we aren#t accessing this anymore after, but it's still nicer if
this is actually guaranteed.

sd-bus: add new API sd_bus_match_signal() + sd_bus_match_signal_asnyc()

These are convenience helpers that hide the match string logic (which we
probably should never have exposed), and instead just takes regular C
arguments.