This will make it easier to link as a library.
Submitted by: Sebastian Huber <sebastian.huber@embedded-brains.de> (older version)
Discussed on: -hackers
This will make it easier to link as a library.
Submitted by: Sebastian Huber <sebastian.huber@embedded-brains.de> (older version)
Discussed on: -hackers
This will make it easier to link as a library.
Submitted by: Sebastian Huber <sebastian.huber@embedded-brains.de> (older version)
Discussed on: -hackers
giving access to functionality that is not available in capability mode
sandbox. The functionality can be precisely restricted.
Start with the following services:
- system.dns - provides API compatible to:
- gethostbyname(3),
- gethostbyname2(3),
- gethostbyaddr(3),
- getaddrinfo(3),
- getnameinfo(3),
- system.grp - provides getgrent(3)-compatible API,
- system.pwd - provides getpwent(3)-compatible API,
- system.random - allows to obtain entropy from /dev/random,
- system.sysctl - provides sysctlbyname(3-compatible API.
Sponsored by: The FreeBSD Foundation
only being able to create 1TB partitions:
o) Use an unsigned 32-bit quantity to store the number of disk sectors.
o) Detect overflow of said 32-bit quantity and clamp to 2^32.
o) Rather than returning the disk sector count from get_params, return 0 on
success, since its return value is only ever compared to -1 to detect
failure. This would cause returning 2^32 sectors to be interpreted as an
error.
Reviewed by: bde ("good for a quick fix")
Print warning for IPv4 address strings which are valid in
inet_aton() but not valid in inet_pton(). (1)
Found by: Özkan KIRIK <ozkan.kirik@gmail.com>
Submitted by: Ian Smith <smithi@nimnet.asn.au> (1)
MFC after: 2 weeks
Sponsored by: Yandex LLC
Now it is easy to expand the size of the mirror when all its components
are replaced. Also add g_resize method to geom_mirror class. It will write
updated metadata to new last sector, when parent provider is resized.
Silence from: geom@
MFC after: 1 month
signifying that a reboot is required to complete activation
of the requested firmware image.
Reported by: Joe Golio <joseph.golio@emc.com>
Sponsored by: Intel
MFC after: 3 days
manual page:
There is no need to call arc4random_stir() before using
arc4random() functions family, since they automatically
initialize themselves.
No objection: des
MFC after: 2 weeks
Original log:
pfctl -ss printed state levels for ICMPv6. Disable this the same
way it has already been done for ICMPv4.
Difference with OpenBSD:
- WITHOUT_INET6 safe
Obtained from: OpenBSD
when -u is specified it is not...
update the docs to say that you can use full device names w/ -u, and
update the examples...
Submitted by: #vbsdcon
MFC after: 3 days
This is believed to fix hastd crashes, which might occur during
synchronization, triggered by the failed assertion:
Assertion failed: (amp->am_memtab[ext] > 0),
function activemap_write_complete, file activemap.c, line 351.
MFC after: 1 week
1. "-u N" specified, no -f, and mdN found,
2. no -u, "-f /pathname" specified, and mdN associated with /pathname found,
3. "-u N" specified, "-f /pathname" specified, and both of them found,
4. "-l" specified and no -f,
5. "-l" specified, "-f /pathname" specified, and /pathname found.
otherwise return -1.
Spotted by: Julian H. Stacey
di_extsize is the EA size and as such it should be unsigned.
Adjust related types for consistency.
Reviewed by: mckusick (previous version)
MFC after: 3 weeks
Always validate the return of find_geomcfg(). It could be NULL, for
example when the geom is withering.
Approved by: ken (mentor)
Sponsored by: Spectra Logic Corporation
MFC after: 3 weeks
with CARP.
Currently, we've got a problem that interface isn't IFF_UP at the time
we assign it a redundant address, and the latter gets stuck in INIT state.
Additional SIOCSIFFLAGS from ifconfig(8) kicks it to a working state.
A proper fix is kernel side and appeared to be non-trivial, not to be
checked in before 10.0-RELEASE.
Submitted by: Ole Myhre <ole.myhre dataoppdrag.no>
already belongs or removing it from a group to which it does not
belong. This makes it possible to include group memberships in
ifconfig_foo0 in rc.conf without fear of breaking "service netif
restart foo0".
MFC after: 3 days
that it's being used by both initiators, and change the title to make
it more easily searchable.
Approved by: re (glebius)
Sponsored by: FreeBSD Foundation
when calculating stats in nvmecontrol perftest.
Sponsored by: Intel
Reported by: Joe Golio <joseph.golio@emc.com>
Reviewed by: carl
Approved by: re (hrs)
MFC after: 1 week
kept dirty to reduce the number of on-disk metadata updates. The
sequence of operations is:
1) acquire the activemap lock;
2) update in-memory map;
3) if the list of keepdirty extents is changed, update on-disk metadata;
4) release the lock.
On-disk updates are not frequent in comparison with in-memory updates,
while require much more time. So situations are possible when one
thread is updating on-disk metadata and another one is waiting for the
activemap lock just to update the in-memory map.
Improve this by introducing additional, on-disk map lock: when
in-memory map is updated and it is detected that the on-disk map needs
update too, the on-disk map lock is acquired and the on-memory lock is
released before flushing the map.
Reported by: Yamagi Burmeister yamagi.org
Tested by: Yamagi Burmeister yamagi.org
Reviewed by: pjd
Approved by: re (marius)
MFC after: 2 weeks
waiting on an empty queue as the queue may have several consumers.
Before the fix the following scenario was possible: 2 threads are
waiting on empty queue, 2 threads are inserting simultaneously. The
first inserting thread detects that the queue is empty and is going to
send the signal, but before it sends the second thread inserts
too. When the first sends the signal only one of the waiting threads
receive it while the other one may wait forever.
The scenario above is is believed to be the cause of the observed
cases, when ggate_recv_thread() was getting stuck on taking free
request, while the free queue was not empty.
Reviewed by: pjd
Tested by: Yamagi Burmeister yamagi.org
Approved by: re (marius)
MFC after: 2 weeks
The fields from deMTime and deMDate in the DOS directory entry
are actually the last-modified time/date.
According to some online documentation these are the only
timestamps available in FAT12/FAT16.
MFC after: 3 days
in the future in a backward compatible (API and ABI) way.
The cap_rights_t represents capability rights. We used to use one bit to
represent one right, but we are running out of spare bits. Currently the new
structure provides place for 114 rights (so 50 more than the previous
cap_rights_t), but it is possible to grow the structure to hold at least 285
rights, although we can make it even larger if 285 rights won't be enough.
The structure definition looks like this:
struct cap_rights {
uint64_t cr_rights[CAP_RIGHTS_VERSION + 2];
};
The initial CAP_RIGHTS_VERSION is 0.
The top two bits in the first element of the cr_rights[] array contain total
number of elements in the array - 2. This means if those two bits are equal to
0, we have 2 array elements.
The top two bits in all remaining array elements should be 0.
The next five bits in all array elements contain array index. Only one bit is
used and bit position in this five-bits range defines array index. This means
there can be at most five array elements in the future.
To define new right the CAPRIGHT() macro must be used. The macro takes two
arguments - an array index and a bit to set, eg.
#define CAP_PDKILL CAPRIGHT(1, 0x0000000000000800ULL)
We still support aliases that combine few rights, but the rights have to belong
to the same array element, eg:
#define CAP_LOOKUP CAPRIGHT(0, 0x0000000000000400ULL)
#define CAP_FCHMOD CAPRIGHT(0, 0x0000000000002000ULL)
#define CAP_FCHMODAT (CAP_FCHMOD | CAP_LOOKUP)
There is new API to manage the new cap_rights_t structure:
cap_rights_t *cap_rights_init(cap_rights_t *rights, ...);
void cap_rights_set(cap_rights_t *rights, ...);
void cap_rights_clear(cap_rights_t *rights, ...);
bool cap_rights_is_set(const cap_rights_t *rights, ...);
bool cap_rights_is_valid(const cap_rights_t *rights);
void cap_rights_merge(cap_rights_t *dst, const cap_rights_t *src);
void cap_rights_remove(cap_rights_t *dst, const cap_rights_t *src);
bool cap_rights_contains(const cap_rights_t *big, const cap_rights_t *little);
Capability rights to the cap_rights_init(), cap_rights_set(),
cap_rights_clear() and cap_rights_is_set() functions are provided by
separating them with commas, eg:
cap_rights_t rights;
cap_rights_init(&rights, CAP_READ, CAP_WRITE, CAP_FSTAT);
There is no need to terminate the list of rights, as those functions are
actually macros that take care of the termination, eg:
#define cap_rights_set(rights, ...) \
__cap_rights_set((rights), __VA_ARGS__, 0ULL)
void __cap_rights_set(cap_rights_t *rights, ...);
Thanks to using one bit as an array index we can assert in those functions that
there are no two rights belonging to different array elements provided
together. For example this is illegal and will be detected, because CAP_LOOKUP
belongs to element 0 and CAP_PDKILL to element 1:
cap_rights_init(&rights, CAP_LOOKUP | CAP_PDKILL);
Providing several rights that belongs to the same array's element this way is
correct, but is not advised. It should only be used for aliases definition.
This commit also breaks compatibility with some existing Capsicum system calls,
but I see no other way to do that. This should be fine as Capsicum is still
experimental and this change is not going to 9.x.
Sponsored by: The FreeBSD Foundation
(sys/dev/iscsi_initiator/ instead of sys/dev/iscsi/initiator/), to make
room for the new one. This is also more logical location (kernel module
being named iscsi_initiator.ko, for example). There is no ongoing work
on this I know of, so it shouldn't make life harder for anyone.
There are no functional changes, apart from "svn mv" and adjusting paths.
being defined in <sys/diskmbr.h>. Instead give the symbols here a
"PC98_" prefix. This way, both <sys/diskmbr.h> and <sys/diskpc98.h>
can be included in the same C source file.
The renaming is trivial. The only gotcha is that DOSBBSECTOR is
also redefined from 0 to 1. This because DOSBBSECTOR was always
used in conjunction with an addition of 1. The PC98_BBSECTOR symbol
is defined as 1 and the expression is simplified.
Note: it is not believed that ports are seriously impacted; or at
all for that matter.
Approved by: nyan@
This fix the case when etherswitch is printing the information of port 0
vlan group (in port based vlan mode) with no member ports.
Add the ETHERSWITCH_VID_VALID support to ip17x driver.
Add the ETHERSWITCH_VID_VALID support to rt8366 driver.
arswitch doesn't need to be updated as it doesn't support vlans management
yet.
Approved by: adrian (mentor)
- Display a AF_LINK address in #linkN when sdl_{nlen,alen,slen) == 0 and
sdl_index != 0.
- Reduce unnecessary loop in pmsg_addrs().
- Remove iso_ntoa(). This is not used.
As part of this commit, add an nvme_strvis() function which borrows
heavily from cam_strvis(). This will allow stripping of
leading/trailing whitespace and also handle unprintable characters
in model/serial numbers. This function goes into a new nvme_util.c
file which is used by both the driver and nvmecontrol.
Sponsored by: Intel
Reviewed by: carl
MFC after: 3 days
Recent testing with QEMU that has variable sector size support for
NVMe uncovered some of these issues. Chatham prototype boards supported
only 512 byte sectors.
Sponsored by: Intel
Reviewed by: carl
MFC after: 3 days
Also remove stat() call and just rely on errno from open() call to discern
whether dev node exists or not.
Sponsored by: Intel
Reviewed by: kib, carl
MFC after: 3 days
and firmware revision in the controller's identify structure.
Also modify consumers of these fields to ensure they only use the
specified number of bytes for their respective fields.
Sponsored by: Intel
Reviewed by: carl
MFC after: 3 days
the root file system on bootup:
|------------------------------------------------------------------------
|r214006 | marcel | 2010-10-17 22:01:53 -0700 (Sun, 17 Oct 2010) | 20 lines
|
| Re-implement the root mount logic using a recursive approach, whereby each
|root file system (starting with devfs and a synthesized configuration) can
|contain directives for mounting another file system as root.
|------------------------------------------------------------------------
This commit adds a mount.conf(8) man page which documents
the root mount logic. mount.conf(8) also provides some examples
for the /.mount.conf file, which can be used to change the root mount behavior.
Reviewed by: marcel bjk
- Fix a bug in sodump() which prevented struct sockaddr_in6 from displaying.
- Fix a bug in in fiboptlist_csv() which could cause free() of uninitialized
pointer.
- Style cleanups:
. Add missing "static" keywords.
. Use an array of struct sockaddr_storage instead of sockunion for rtmsg.
. Use err() and errx() instead of pair of fprintf(stderr, "...") + exit(1).
. Use nitems() macro.
. Various style(9) fixes.
an empty firmware slot, as long as the user has specified a firmware
image to download into the empty firmware slot.
Sponsored by: Intel
Reported by: Joe Golio <joseph.golio@emc.com>
MFC after: 3 days
are processed as admin commands, not I/O commands.
As part of this change, pull out the code for parsing a namespace node
string into a separate function, since it is used for both identify and
logpage commands.
Sponsored by: Intel
MFC after: 3 days
firmware download. This correctly prints an error and exits for
an incorrect firmware image name before prompting the user to
confirm the download.
Sponsored by: Intel
MFC after: 3 days
* Use 0/1 instead of sysexits. Man pages are confusing on this topic,
but 0/1 is sufficient for nvmecontrol.
* Use err function family where possible instead of fprintf/exit.
* Fix some typing errors.
* Clean up some error message inconsistencies.
Sponsored by: Intel
Submitted by: bde (parts of firmware.c changes)
MFC after: 3 days
that looks for interface skips interfaces that are not UP. We need to call
dhclient-script PREINIT before we call discover_interfaces(), so the script has
a chance to bring the interface UP.
Reported by: alfred
Revoke all capability rights from STDIN and allow only for write to STDOUT and
STDERR. All those descriptors are redirected to /dev/null.
Reviewed by: brooks
Sponsored by: The FreeBSD Foundation
Once PID is written to the pidfile, revoke all capability rights.
We just want to keep the pidfile open.
Reviewed by: brooks
Sponsored by: The FreeBSD Foundation
Limit routing socket so only poll(2) and read(2) are allowed (CAP_POLL_EVENT
and CAP_READ). This prevents unprivileged process from adding, removing or
modifying system routes.
Reviewed by: brooks
Sponsored by: The FreeBSD Foundation
- Limit bpf descriptor in unprivileged process to CAP_POLL_EVENT, CAP_READ and
allow for SIOCGIFFLAGS, SIOCGIFMEDIA ioctls.
- While here limit bpf descriptor in privileged process to only CAP_WRITE.
Reviewed by: brooks
Sponsored by: The FreeBSD Foundation
Currently it was allowed to send any UDP packets from unprivileged process and
possibly any packets because /dev/bpf was open for writing.
Move sending packets to privileged process. Unprivileged process has no longer
access to not connected UDP socket and has only access to /dev/bpf in read-only
mode.
Reviewed by: brooks
Sponsored by: The FreeBSD Foundation
- Add new request (IMSG_SEND_PACKET) that will be handled by privileged process.
- Add $FreeBSD$.
Reviewed by: brooks
Sponsored by: The FreeBSD Foundation
The gethostname(3) function won't work in capability mode, because reading
kern.hostname sysctl is not permitted there. Cache hostname early and use
cached value later.
Reviewed by: brooks
Sponsored by: The FreeBSD Foundation
Make use of two fields: rfdesc and wfdesc to keep bpf descriptor open for
reading only in rfdesc and bpf descriptor open for writing only in wfdesc.
In the end they will be used by two different processes.
Reviewed by: brooks
Sponsored by: The FreeBSD Foundation
contained in the DHCP offer, and write it out to the lease file
as an unquoted value of the "next-server" keyword. The value is ignored
when the lease is read back by dhclient, however other applications
are free to parse it.
The intent behind this change is to allow easier interoperability
with automated installation systems e.g. Cobbler, Foreman, Razor;
FreeBSD installation kernels can automatically probe the network
to discover deployment servers. There are no plans to MFC this
change unless a backport is specifically requested.
The syntax of the "next-server <ip>" lease keyword is intended to be
identical to that used by the ISC DHCPD server in its configuration files.
The required defines are already present in dhclient but were unused before
this change. (Note: This is NOT the same as Option 66, tftp-server-name).
It has been exercised in a university protocol testbed environment, with
Cobbler and an mfsBSD image containing pc-sysinstall (driven by Cobbler
Cheetah templates). The SYSLINUX memdisk driver is used to boot mfsBSD.
Currently this approach requires that a dedicated system profile has
been created for the node where FreeBSD is to be deployed. If this
is not present, the pc-sysinstall wrapper will be unable to obtain
a node configuration. There is code in progress to allow mfsBSD images
to obtain the required hints from the memdisk environment by parsing
the MBFT ACPI chunk. This is non-standard as it is not linked into
the platform's ACPI RSDT.
Reviewed by: des
in gpart(8) and boot(8), adding references to gptboot(8) in both.
Reviewed by: jhb, ae, pjd, Paul Schenkeveld <bsdcan@psconsult.nl>, david_a_bright@dell.com (portions), gjb
MFC after: 1 week
sbin/devd/devd.cc
All output will now go to syslog(3) if devd is daemonized, or stderr
if it's running in the foreground.
sbin/devd/devd.8
Remove the "-D" flag. Filtering messages by priority now
happens in the usual syslog way. For performance reasons, a few
extra-verbose debugging statements are now conditional on the "-d" (do
not daemonize) flag.
etc/syslog.conf
etc/newsyslog.conf
Direct messages from devd(8) to /var/log/devd.log, but leave it
disabled by default
Reviewed by: eadler
Approved by: gibbs (co-mentor)
MFC after: never (removed a command-line option from devd)
which is presently: AES-XTS, no authentication. Create provider
with pagesize as sectorsize by default.
- Rewrite parsing code for geli(8)-backed swap options, now options
are required to be exact match, and unrecognized options will trigger
a warning.
- Don't initialize GELI device if it's already initialized. This
restores previous behavior.
- Don't duplicate file descriptor when working with geli(8) and
gbde(8) as there is no need to communicate with the utility other
than exit status.
- When calling swap_on_off_* routines, which_prog can only be SWAP_ON
or SWAP_OFF. Eliminate unneeded case branches by replacing switch
with if's.
- Plug a few memory leaks.
Reviewed by: hrs (but bugs are mine)
MFC after: 1 week
X-MFC-with: r252310, r252332, r252345
- Reconnect with some minor modifications, in particular now selsocket()
internals are adapted to use sbintime units after recent'ish calloutng
switch.
device names "md" or "md[0-9]*" and a "file" option are specified in
/etc/fstab like this:
md none swap sw,file=/swap.bin 0 0
- Add GBDE/GELI encrypted swap space specification support, which
rc.d/encswap supported. The /etc/fstab lines are like the following:
/dev/ada1p1.bde none swap sw 0 0
/dev/ada1p2.eli none swap sw 0 0
.eli devices accepts aalgo, ealgo, keylen, and sectorsize as options.
swapctl(8) can understand an encrypted device in the command line
like this:
# swapctl -a /dev/ada2p1.bde
- "-L" flag is added to support "late" option to defer swapon until
rc.d/mountlate runs.
- rc.d script change:
rc.d/encswap -> removed
rc.d/addswap -> just display a warning message if $swapfile is defined
rc.d/swap1 -> renamed to rc.d/swap
rc.d/swaplate -> newly added to support "late" option
These changes alleviate a race condition between device creation/removal
and swapon/swapoff.
MFC after: 1 week
Reviewed by: wblock (manual page)
a new firmware command.
NVMe controllers may support up to 7 firmware slots for storing of
different firmware revisions. This new firmware command supports
firmware replacement (i.e. firmware download) with or without immediate
activation, or activation of a previously stored firmware image. It
also supports selection of the firmware slot during replacement
operations, using IDENTIFY information from the controller to
check that the specified slot is valid.
Newly activated firmware does not take effect until the new controller
reset, either via a reboot or separate 'nvmecontrol reset' command to the
same controller.
Submitted by: Joe Golio <joseph.golio@emc.com>
Obtained from: EMC / Isilon Storage Division
MFC after: 3 days
This includes pretty printers for all of the standard NVMe log pages
(Error, SMART/Health, Firmware), as well as hex output for non-standard
or vendor-specific log pages.
Submitted by: Joe Golio <joseph.golio@emc.com>
Obtained from: EMC / Isilon Storage Division
MFC after: 3 days
commands.
Also improve the checking of device node names, so that better error
messages are displayed when incorrect names are specified.
Sponsored by: Intel
MFC after: 3 days
usage message for each nvmecontrol command. This helps reduce some code
clutter both now and for future commits which will add logpage and
firmware support to nvmecontrol(8).
Also move helper function prototypes to the end of the header file, after
the per-command functions.
Sponsored by: Intel
MFC after: 3 days
specified, only md(4) devices which have the specified file as backing
store are displayed.
- Use MD_NAME instead of "md".
- Use _PATH_DEV instead of "/dev/".
MFC after: 1 week
C11 atomics now work on all the architectures. Have at least a single
piece of software in our base system that uses C11 atomics. This
somewhat makes it less likely that we break it because of LLVM imports,
etc.
- When operating on a core file (-M) and -c is specified we don't clear
the message buffer of the running system.
- If we don't have permission to clear the buffer print the error message
only. That's what Linux does in this case, where this feature was ported
from, and it ensures that the error message doesn't get lost in the noise.
Discussed with: antoine, cognet
Approved by: cognet
This allows setting attributes on tables. One simply does not provide
an index in that case. Otherwise the entry corresponding the index has
the attribute set or unset.
Use this change to fix a relatively longstanding bug in our GPT scheme
that's the result of rev 198097 (relatively harmless) followed by rev
237057 (damaging). The damaging part being that our GPT scheme always
has the active flag set on the PMBR slice. This is in violation with
EFI. Existing EFI implementions for both x86 and ia64 reject the GPT.
As such, GPT disks created by us aren't usable under EFI because of
that.
After this change, GPT disks never have the active flag set on the PMBR
slice. In order to make the GPT disk bootable under some x86 BIOSes,
the reason of rev 198097, one must now set the active attribute on the
gpt table. The kernel will apply this to the PMBR slice For (S)ATA:
gpart set -a active ada0
To fix an existing GPT disk that has the active flag set in the PMBR,
and that does not need the flag, use (again for (S)ATA):
gpart unset -a active ada0
The EBR, MBR & PC98 schemes, which also impement at least 1 attribute,
now check to make sure the entry passed is valid. They do not have
attributes that apply to the table.
The "failok" option doesn't have any effect at all unless specified in
fstab(5) and combined with the -a flag. The "failok" option is already
documented in fstab(5).
PR: 177630
No objection: eadler
MFC after: 1 week
recreating the filesystem, check for and output the -i, -k, and -l
options if appropriate.
Note the remaining deficiencies of the -m option in the dumpfs(8)
manual page. Specifically that newfs(8) options -E, -R, -S, and -T
options are not handled and that -p is not useful so is omitted.
Also document that newfs(8) options -n and -r are neither checked
for nor output but should be. The -r flag is needed if the filesystem
uses gjournal(8).
PR: bin/163992
Reported by: Dieter <freebsd@sopwith.solgatos.com>
Submitted by: Andy Kosela <akosela@andykosela.com>
MFC after: 1 week
If an expander returns 0x00 (no device attached) in the ATTACHED DEVICE
field of the SMP DISCOVER response, ignore the value of ATTACHED SAS
ADDRESS, because it is invalid. Some expanders zero out the address
when the attached device is removed, but others do not. Section
9.4.3.10 of the SAS Protocol Layer 2 revision 04b does not require them
to do so.
Approved by: ken (mentor)
MFC after: 3 weeks
been printed. This provides compatibility with other *nix systems
(including Linux).
While here use stdbool booleans for 'all'.
PR: bin/178295
Submitted by: Levent Serinol <lserinol@gmail.com>
Reviewed by: will
This adds the support to the config keyword (vlan operation mode), ports
flags, prints the vlan mode and vlan capabilities. It also adds some basic
information to usage() and support the keyword 'help' as a shortcut to
usage(). The manual page is also updated with the new options.
Submitted by: Luiz Otavio O Souza <loos.br@gmail.com>
Reviewed by: ray
Address. Although KAME implementation used FF02:0:0:0:0:2::/96 based on
older versions of draft-ietf-ipngwg-icmp-name-lookup, it has been changed
in RFC 4620.
The kernel always joins the /104-prefixed address, and additionally does
/96-prefixed one only when net.inet6.icmp6.nodeinfo_oldmcprefix=1.
The default value of the sysctl is 1.
ping6(8) -N flag now uses /104-prefixed one. When this flag is specified
twice, it uses /96-prefixed one instead.
Reviewed by: ume
Based on work by: Thomas Scheffler
PR: conf/174957
MFC after: 2 weeks
names within the std namespace (and possibly within the global
namespace).
The main advantage is that the C++ versions can provide optimized
versions or simplified interfaces.
