QNX Technical Articles

Date of this edition: October 21, 2021

QNX SDP is a cross-compiling and debugging environment, including an IDE and command-line tools, for building binary images and programs for ARM v7 and v8, and x86_64 targets running the QNX Neutrino RTOS 7.1. You can install QNX SDP on the following development hosts:

• Microsoft Windows 10 Pro 64-bit, or Windows 8.1 Pro 64-bit
• macOS version 10.14 or 10.15
• Linux Red Hat Enterprise Linux 7 64-bit, or Ubuntu Desktop 18.04 LTS 64-bit, on x86_64 processors (QNX SDP isn't supported on Linux on ARM processors)

Contents

• What's in this update?
• Updates and fixed issues
• Known issues
• Getting started with the documentation
• Technical support

Throughout this document, you may see reference numbers associated with particular issues, changes, etc. When corresponding with our Technical Support staff about a given issue, please quote the relevant reference number. You might also find the reference numbers useful for tracking issues as they become fixed.

What's in this update?

This update includes the following packages, which you'll find under Updates -> QNX Software Development Platform -> Documentation in the QNX Software Center:

To see a list of the contents of a package, right-click it in the QNX Software Center, choose Properties, and then click Package Contents in the Properties window.

Updates and fixed issues

This update includes enhancements, fixed issues, and clarifications, to the following QNX SDP documents:

• General updates
• IDE User's Guide
• OS Core Components:
  • Building Embedded Systems
  • Customizing a BSP
  • High Availability Framework Developer's Guide
  • Instant Device Activation
  • QDB Developer's Guide
  • QNX Helper Developer's Guide
  • System Analysis Toolkit User's Guide
  • System Architecture
  • User's Guide
• Audio & Graphics:
  • Audio Developer's Guide
• Programming:
  • Getting Started with QNX Neutrino
  • QNX Neutrino Programmer's Guide
  • Writing a Resource Manager
• System Security Guide
• Utilities & Libraries:
  • C Library Reference
  • Utilities Reference

General updates

• We've fixed the provider name in all doc plugins to be "BlackBerry Limited". This name can be seen if you examine the plugin details in the IDE, by accessing Help > About Momentics IDE > Installation Details > Plug-ins. (You can type part of the directory name of a doc plugin, such as neutrino.lib_ref, to filter the display.)
• We've fixed the copyright dates and the license agreement text in the Momentics IDE Feature software component. The correct information can be seen if you access Help > About Momentics IDE > Installation Details > Installed Software, expand Momentics and click Momentics IDE Feature.

IDE User's Guide

• In "Kernel event trace log configuration", we've stated that a custom pidin command is better to ensure binary names are not truncated.

OS Core Components

Building Embedded Systems

• We've removed any references to the Systems Builder Perspective since it no longer exists in the IDE.
• We've updated the description for default uid and gid.
• We've updated descriptions for the TIMER_ON_CPU0, CHECK_STABLE, TICKLESS, and GLOBAL_CLOCKCYCLES flags.

Customizing a BSP

• Under I2C > Hardware interface > Function table, we've added the bus_reset function.
• In "Startup", we've noted that different revisions of SoC can have different features, and added a revised explanation on memory mapping.
• In the "The development process" section of "Drivers", we've said how modifications to the device driver command or syspage are necessary to run a reference BSP driver on the target board.

High Availability Framework Developer's Guide

• We've updated the description of the hpdl parameter.

Instant Device Activation

• We've revised the explanation of how the minidriver must work (i.e., the startup code must register it by adding an entry to the SYSPAGE's minidriver section).

QDB Developer's Guide

• In "Starting the QDB server", we've removed an improper recommendation that QDB databases be run in RAM.

QNX Helper Developer's Guide

• We've revised the introduction to "Setting up QNX helpers logging" and made this topic easier to find.

System Analysis Toolkit User's Guide

• We've updated the required abilities needed (i.e., PROCMGR_AID_INTERRUPT instead of PROCMGR_AID_IO).

System Architecture

• We've added several crypto-related functions to the interface usage table in "Encryption".
• We've clarified that it's the association between virtual and physical memory pages that gets locked, and fixed the sample ThreadCtl() call.

User's Guide

• We've updated the maximum user name length to 255 characters.
• We've updated the reported limits for file size and directory size, filesystem size, and disk size.

Audio & Graphics

Audio Developer's Guide

snd_pcm_channel_info(), snd_pcm_plugin_info(), snd_pcm_channel_info_t

We've mentioned that when certain snd_pcm_channel_info_t fields contain zeroed data, playback or capture is not possible at this time.

snd_pcm_plugin_read(), snd_pcm_plugin_write(), snd_pcm_write()

We've clarified that EWOULDBLOCK and EAGAIN are equivalent.

Programming

Getting Started with QNX Neutrino

• We've documented F_GROWSP.
• We've fixed the explanation of checking the message length for combine messages.

QNX Neutrino Programmer's Guide

• In the ACL example code, we've added the correct #includes and fixed the acl_calc_mask() call so the program compiles and runs properly.
• We've added a new subsection, "CPU time billing for threads", that illustrates and explains how QNX Neutrino bills CPU time for a thread during pre-emption or interrupt handling.
• We've described the QCONF_OVERRIDE, INSTALL_ROOT_$(OS), and USE_INSTALL_ROOT variables for setting up separate directories for built content and an SDP installation. We've also explained the CPUDIR and CPUVARDIR variables.
• We've updated the descriptions for 32-bit and 64-bit QNX time values, and the processor-specific details.
• We've fixed the explanation of CLOCK_MONOTONIC in the first sentence.

Writing a Resource Manager

• We've added a new field (requested_len) in the io_mmap_t structure.
• We've added a note for using close() if we send a custom _IO_CONNECT_COMBINE message.
• We've mentioned that you can initialize a resource manager using a channel with a pulse pool, and given an example of doing so.
• We've pointed out that dirent structures must be properly aligned in the reply, clarified the meaning of the d_reclen and d_namelen fields, and revised the example of building a directory entry.

System Security Guide

• We've added a topic for application groups, which are used to group processes together so they can be controlled as a group.
• We've revised the "Required compiler options", "Enabling the use of fortified system functions for an entire project", and "Enabling the use of fortified system functions via the command line" sections.
• We've corrected instances of "receive buffer" to "reply buffer" when referring to clients.
• We've corrected instances of /user to /usr.
• We've explained why it's better to not use inetd to launch sshd.
• We've updated the flowchart and the description of when the setuid or setgid bits are ignored.
• We've adpated most of the examples to use the standard make infrastructure, and explicitly mentioned any places where we still use the QNX recursive make intrastructure. We've also explained the differences in specifying compiler optimization levels for these two infrastructures.
• We've corrected the second sample startup script, and revised the text below it to describe the sample script properly.

Utilities & Libraries

C Library Reference

Changes include the following:

*at() functions

We've corrected the description for several *at() functions regarding path operation.

acl_create_entry(), acl_get_entry()

We've indicated that the ACL entry's pointer returned by acl_create_entry() becomes invalid after calling certain acl*() functions.

acl_set_qualifier()

We've removed ENOMEM as a possible error.

atof()

We've corrected atof() to indicate that it's signal safe and interrupt safe.

ChannelCreate()

We've updated the description for _NTO_CHF_COID_DISCONNECT and _NTO_CHF_DISCONNECT, and we've added diagrams to clarify the explanation.

dirent

We've updated the d_name and d_namelen fields in the dirent and dirent64 structures.

dispatch_handler()

We've clarified the possible error scenarios indicated by a return of -1. Also, the code sample has been fixed.

dlopen(), spawn(), posix_spawn(), fork()

We've mentioned that PROCMGR_AID_PROT_EXEC and PROCMGR_AID_MAP_FIXED abilities are needed to link libraries at load time or run time, or for any child process to use dlopen().

drand48(), erand48(), lrand48(), nrand48()

We've corrected the range for serveral *rand() functions to be [0.0, 1.0).

getspnam()

We've corrected the returns section.

inotify_add_watch()

We've noted that by default, inotify events are non-recursive, so you have to create a specific watch for each file or directory of interest. Also, the cancellation point status has been changed to yes.

InterruptAttach*(), InterruptAttachArray*()

In InterruptAttach*() and InterruptAttachArray*(), we've removed any mention of synthetic interrupts and added links to init_intrinfo().

io_connect(), open()

We've updated the O_DSYNC flag description to use proper memory terminology and explain its QNX-specific behavior.

iofunc_link()

We've fixed the function's description and the dattr argument's description, and we've updated the errors list.

iofunc_mmap_ext(), iofunc_mmap()

We've added a new field (requested_len) in the io_mmap_t structure.

iofunc_notify_trigger*()

We've improved the description for the __cnt argument.

iofunc_open()

The attr and dattr argument descriptions have been revised to explain the meaning of NULL values and how the meaning of attr depends on whether dattr is NULL.

iofunc_read_default(), iofunc_read_verify(), iofunc_space_verify(), iofunc_write_default(), iofunc_write_verify()

We've expanded the descriptions of some iofunc_*() functions to specify what checks they make, and updated their error lists so they are complete.

iofunc_space_verify(), fcntl()

We've documented F_GROWSP.

iofunc_unlock_ocb_default(), iofunc_lock_ocb_default()

We've corrected the descriptions for both functions regarding locking and unlocking.

message_attach()

We've noted that you must explicitly reply to unblock a client.

mlock(), mlockall()

We've mentioned that using MAP_LAZY may not have an immediate effect on mappings.

mlock(), munlock(), munlockall()

For mlock(), we've clarified the description of how this function affects memory pages. In munlock() and munlockall(), we've mentioned that any locks established by other processes to pages that are in range for this function call are unaffected by the call.

MsgError()

We've improved the description to say the function usually unblocks the client and sets the client's error, and to explain how different error argument settings affect the reply-blocked client.

name_attach()

We've mentioned that when given a dispatch handle (dpp) of NULL, name_attach() creates a channel with the _NTO_CHF_COID_DISCONNECT, _NTO_CHF_UNBLOCK , and _NTO_CHF_DISCONNECT flags set.

pread()

We've added EINVAL to the list of errors.

procmgr_ability_create()

We've explained the semantics of multiple procmgr_ability_create() calls for the same ability.

procmgr_value_current()

We've corrected the #include file for procmgr_value_current().

pthread_sigmask(), sigprocmask(), SignalProcmask()

We've added a warning that blocking signals such as SIGSEGV doesn't prevent process termination when the signals are delivered by the kernel.

readdir()

We've added a code example.

_readdir_r(), _readdir64_r()

We've updated the explanation of how large the buffer pointed to by entry must be.

readdir_r(), readdir64_r()

We've updated the explanation of how large the buffer pointed to by entry must be.

resmgr_attach()

We've clarified how the pointer-based arguments in resmgr_attach() are used.

We've revised the explanation of supported file types (e.g., by explaining the _FTYPE_ANY and _FTYPE_ALL flags). We've also fixed the information about client request types and their matching pathnames, and the _RESMGR_FLAG_FTYPEONLY description.

rsrcdbmgr_query_name()

We've added -2 as a PID value, and changed the description for -1.

scandir()

The scandir() entry now lists and describes the ENOSYS and EPERM errors.

seed48()

We've corrected the thread safety to no.

select()

We've recommended to use poll() and fixed the description of FD_SETSIZE.

setegid(), setgid(), setgroups(), setregid(), setreuid(), setuid()

We've recommended against using negative IDs.

setvbuf()

We've added a note for _IOBLF mode regarding situations when the buffer is flushed.

shm_create_handle(), shm_open_handle()

We've provided a more generic example of shared memory object handles.

shm_ctl()

We've added a list of three default mappings for "Bits in the special argument for ARM processors" and changed the description for some of the memory attributes.

SignalAction()

We've fixed the summary of the sigstub argument.

socketpair()

We've corrected the fd argument in the function prototype.

spawn()

We've added a note about the O_CLOEXEC flag being ignored by file descriptors in fd_map.

ThreadCtl()

We've corrected a code sample that uses _NTO_TCTL_SHR_MUTEX.

Utilities Reference

The following entries are new:

mkshadow

Create entries for QNX Neutrino shadow files.

qchecksec

Check binaries for security hardening properties.

qlicense

Activate licenses without a myQNX account.

qtdctl

QNX Trusted Disk (QTD) control utility.

Other changes include the following:

auto_ipd

For the -w option, we've explained how it affects ANNOUNCE_INTERVAL and ANNOUNCE WAIT.

BIND utilities

We've made the syntax generic, mentioned how to find the current version, and referred readers to third-party BIND documentation.

devb-*

We've updated the synopsis and options lists to indicate support for filesystem-specific options.

echo

We've rewritten the description to explain the different versions of echo supported on the target and host, and the differences in supported options between these versions.

elfnote

We've revised the -F option to explain the different formats, revised the -m, -L, and -S options, and added the -q option. We've mentioned that you must specify at least one possible action this command performs and we've updated some usage examples.

elfnote

For -t, we've added NT_GNU_BUILD_ID to the defined types and mentioned that for defined types, -n is not required. We've also removed bad examples that would generate errors.

envars

We've added the LIBC_FATAL_STDERR environment variable to "Commonly Used Environment Variables".

fdisk

We've removed the -e option, fixed the description for the -s option of the add command, and fixed the description of the Restore command for interactive mode.

fsevmgr

We've mentioned that the random daemon must be running to launch fsevmgr. For -m, we've added that multiple events per read() are allowed for all inotify-style watches.

hogs

We've added the -l ("el") option.

inetd.conf, sshd

We've explained why it's better to not use inetd to launch sshd.

io-audio

We've stated that the configuration file used to start io-audio can't be re-used as a driver-specific configuration file with the mount command.

io-audio

We've updated the descriptions of the fragment size options.

io-usb-otg

We've added the -I option.

iperf2

We've added the following options: -e -H -R -S -X -z

ls

We've added the '=' character type to the -F option.

ls

We've clarified that the -h option is applicable for -g, -o, -l, and -n.

mkefs, mketfs, mkfatfsimg, mkifs, mkqnx6fsimg

We've explained how directory separators in buildfile lines determine whether the included file can be found at an absolute or relative path on the host (see the "Buildfiles" section and include attribute). For the non-mkifs entries, we've stated how the default empty setting for the search attribute means that only the current working directory will be searched for host files.

In the Buildfiles section, we've explained the meaning of backslashes within buildfiles. For path-based attributes, we've mentioned that forward slashes should be used as directory separators, even on Windows.

mkefs, mketfs, mkifs, mkfatfsimg

We've removed the -h option, which doesn't apply to these filesystem image-building tools.

mkefs, mketfs, mkifs, mkqnx6fsimg

We've explained that for the type=link attribute setting, symbolic links in the target filesystem must not be used in the pathnames of other buildfile items.

mkfatfsimg, mkqnx6fsimg

We've updated the dperms attribute description to clarify the default directory permissions, and to replace the vague "inline directories" term with "directories that don't exist on the host".

mkifs

We've mentioned that the -s option and keepsection attribute don't apply to bootstrap binaries and for these files, only the QNX_info section is kept.

mkifs

The note at the end of the Buildfiles section now says that by default, mkifs strips version information and debug symbols.

mkqfs

We've updated the list of signature algorithms for the QTD -S option.

We've added examples of creating ed25519 and ed448 keypairs.

mkqnx6fs

We've added the -I cmdline option.

mkqnx6fsimg

We've documented the max_sectors attribute.

mkqnximage

We've clarified that this utility builds a VM image.

mount_ifs

We've added the -d and -k options and explained how the IFS image can be digitally verified.

passwd

We've removed the QNXCRYPT, INSISTANT, STRICTPASSWORD, and NOPASSWORDOK options, and fixed the default home directory, uid and gid ranges, and default DEFPROFILE.

pidin

We've fixed the description of _NTO_PF_FORKED.

pipe

We've added the -t option.

pr

We've added the -b, -c, and -f options.

qcc

We've added a section on linking against static and dynamic libraries, and explained the various forms of the -l ("el") option.

We've documented the -pg option.

rpcbind, nfsd, rpcinfo

We've clarified that portmap is identical to rpcbind.

slm

We've documented the SLM: groups element.

slm

We've updated the description for SLM: Runmask.

slm

The SLM description now says you must make sure that slogger2 is running when you start SLM.

tar

We've added a link to the BSD tar documentation.

time

We've added the -p option and an examples section.

tracelogger

We've improved the -d1 option to mention including -E and -n, and mentioned that -c is equivalent to -n0.

use

The -s option has been revised to explain its purpose, when it's useful (or not), and how to call it in scripts vs. on the command line.

valgrind

In "Providing debug symbols to Valgrind", we've explained the need to add the SONAME when +raw is specified.

Known issues

None currently known.

See also the QNX SDP 7.1 release notes.

Getting started with the documentation

After you've installed QNX SDP, you'll find an extensive set of HTML documentation in the Integrated Development Environment (IDE) help system. To start the IDE:

• on Windows, choose QNX Software Systems > QNX Momentics IDE from the Start menu, or use the desktop icon
• on Linux, run IDE_base_directory/qde, where IDE_base_directory is where you installed the IDE package
• on macOS, click the icon labelled QNX Momentics IDE from the launchpad

The roadmap page contains links to the various HTML booksets that accompany the OS. For a short tutorial that will help you get started, see the Quickstart Guide, then refer to the other documents (System Architecture, QNX Neutrino Programmer's Guide, C Library Reference, Utilities Reference, and so on).

You can install and work with multiple versions of QNX Neutrino. Whether you're using the command line or the IDE, you can choose which version of the OS to build programs for. For more information, see the IDE User's Guide or the QNX Neutrino Programmer's Guide.

Technical support

To obtain technical support for any QNX product, visit the support area on our website (https://blackberry.qnx.com/en/support/qnx-support-overview). You'll find a wide range of support options, including community forums.