Caution: This version of this document is no longer maintained. For the latest documentation, see http://www.qnx.com/developers/docs.

Working with Files

This chapter includes:


Note: This chapter concentrates on working with files in the QNX 4 filesystem, which is the default under Neutrino and is compatible with the older QNX 4 OS. For more information, see the Working with Filesystems chapter in this guide.

Everything is a file

In a Neutrino system, almost everything is a file; devices, data, and even services are all typically represented as files. This lets you work with local and remote resources easily from the command line, or through any program that works with files.

Types of files

Neutrino supports the following types of files, and ls -l uses the character shown in parentheses to identify the type:

Regular (-)
A file that contains user data, such as C code, HTML, and data. For example, /home/fred/myprog.c.
Directory (d)
Conceptually, a directory is something that contains files and other directories. For example, /home/fred.

A directory is implemented as a disk file that stores a list of the names of files and other directories. Each filename is associated with an inode (information node) that defines the file's existence. For more information, see QNX 4 filesystem in Working with Filesystems.

Symbolic link (l)
An additional name for a file or directory. For example, /usr/bin/more is a symbolic link to /usr/bin/less. For more information, see Symbolic links in Working with Filesystems.
Named special (n)
A shared memory region, such as, /dev/shmem/Pg101e0001.
Character special files (c)
Entries that represent a character device. For example, /dev/ser1 represents a serial port.
FIFO special files (p)
Persistent named pipes through which two programs communicate. For example, PipeA
Block special files (b)
Entries that represent a block device, such as a disk. For example, /dev/hd0 represents the raw block data of your primary disk drive.
Socket files (s)
Entries that represent a communications socket, especially a UNIX-domain socket. For more information, see socket() and the UNIX protocol in the Neutrino Library Reference.

Some files are persistent across system reboots, such as most files in a disk filesystem. Other files may exist only as long as the program responsible for them is running. Examples of these include shared memory objects, objects in the /proc filesystem, and temporary files on disk that are still being accessed even though the links to the files (their filenames) have been removed.

Filenames and pathnames

To access any file or directory, you must specify a pathname, a symbolic name that tells a program where to find a file within the directory hierarchy based at root (/).

A typical Neutrino pathname looks like this:

/home/fred/.profile

In this example, .profile is found in the fred directory, which in turn resides in the home directory, which is found in /, the root directory:

Sample filename

Like Linux and other UNIX-like operating systems, Neutrino pathname components are separated by a forward slash (/). This is unlike Microsoft operating systems, which use a backslash (\).


Note: To explore the files and directories on your system, use the ls utility. This is the equivalent of dir in MS-DOS. For more information, see Basic commands in Using the Command Line, or ls in the Utilities Reference.

Absolute and relative pathnames

There are two types of pathname:

Absolute paths
Pathnames that begin with a slash specify locations that are relative to the root of the pathname space (/). For example, /usr/lib/libmalloc.so.2.
Relative paths
Pathnames that don't begin with / specify locations relative to your current working directory.

For example, if your current directory is /home/fred, a relative path of .ph/helpviewer is the same as an absolute path of /home/fred/.ph/helpviewer.

The pathname, /home/fred/.ph/helpviewer, actually specifies a directory, not a regular file. You can't tell by looking at a pathname whether the path points to a regular file, a directory, a symbolic link, or some other file type. To determine the type of a file, use file or ls -ld.

The one exception to this is a pathname that ends with /, which always indicates a directory. If you use the -F option to ls, the utility displays a slash at the end of a directory name.

Dot and dot-dot directories

Every directory in a QNX 4 filesystem contains these special links:

. (“dot”)
The current directory.
.. (“dot dot”)
The directory that this directory appears in.

So, for example, you could list the contents of the directory above your current working directory by typing:

ls ..

If your current directory is /home/fred/.ph/helpviewer, you could list the contents of the root directory by typing:

ls ../../../..

but the absolute path (/) is much shorter, and you don't have to figure out how many “dot dots” you need.


Note: Flash filesystems don't support . and .. entries, but the shell might resolve them before passing the path to the filesystem. You can also set up hard links with these names on a flash filesystem.

A note about cd

In some traditional UNIX systems, the cd (change directory) command modifies the pathname given to it if that pathname contains symbolic links. As a result, the pathname of the new current working directory — which you can display with pwd — may differ from the one given to cd.

In Neutrino, however, cd doesn't modify the pathname — aside from collapsing .. references. For example:

cd /home/dan/test/../doc

would result in a current working directory of /home/dan/doc, even if some of the elements in the pathname were symbolic links.

No drive letters

Unlike Microsoft Windows, which represents drives as letters that precede pathnames (e.g. C:\), Neutrino represents disk drives as regular directories within the pathname space. Directories that access another filesystem, such as one on a second hard disk partition, are called mountpoints.

Usually the primary disk-based filesystem is mounted at / (the root of the pathname space). A full Neutrino installation (such as a self-hosted development installation) mounts all additional disk filesystems automatically under the /fs directory. For example:

/fs directory

So, while in a DOS-based system a second partition on your hard drive might be accessed as D:\, in a Neutrino system you might access the second QNX 4 filesystem partition on the first hard drive as /fs/hd0-qnx4-2.

For more information on where to find things in a typical Neutrino pathname space, see Where everything is stored,” later in this chapter. To learn more about mounting filesystems, see Working with Filesystems and Controlling How Neutrino Starts.

Pathnames that begin with a dot

When you list the contents of a directory, the ls utility usually hides files and directories whose names begin with a period. Programs precede configuration files and directories with a period to hide them from view. The files (not surprisingly) are called hidden files.

Other than the special treatment by ls and some other programs (such as the Photon file manager, pfm), nothing else is special about hidden files. Use ls -a to list all files, including any hidden ones.

Extensions

Filename extensions (.something at the end of a filename) tell programs and users what type of data a file contains. In the QNX 4 filesystem (the Neutrino native hard disk filesystem), extensions are just an ordinary part of the filename and can be any length, as long as the total filename size stays within the 505 byte filename length limit.

Most of the time, file extensions are simply naming conventions, but some utilities base their behavior on the extension. See Filename extensions later in this chapter for a list of some of the common extensions used in a Neutrino system.

Pathname-space mapping

You may have noticed that we've talked about files and directories “appearing in” their parent directories, rather than just saying that the parent directories contain these files. This is because in Neutrino, the pathname space is virtual, dictated not just by the filesystem that resides on media mounted at root, but rather by the paths and pathname aliases registered by the process manager.

For example, let's take a small portion of the pathname space:

/dev/ser

In a typical disk-based Neutrino system, the directory / maps to the root of a filesystem on a physical hard drive partition. This filesystem on disk doesn't actually contain a /dev directory, which exists virtually, adopted via the process manager. In turn, the filename ser1 doesn't exist on a disk filesystem either; it has been adopted by the serial port driver.

This capability allows virtual directory unions to be created. This happens when multiple resource managers adopt files that lie in a common directory within the pathname space.


Note: In the interests of creating a maintainable system, we suggest that you create directory unions as rarely as possible.

For more information on pathname-space management, see Pathname Management in the Process Manager chapter of the System Architecture guide.

Filename rules

Neutrino supports a variety of filesystems, each of which has different capabilities and rules for valid filenames. For information about filesystem capabilities, see Working with Filesystems; for filesystem limits, see Understanding System Limits.

In the QNX 4 filesystem, filenames can be up to 48 bytes long, but you can extend them to 505 bytes (see Filenames in Working with Filesystems). Individual bytes within the filename may have any value except the following (all values are in hexadecimal):

If you're using UTF-8 representations of Unicode characters to represent international characters, the limit on the filename length will be lower, depending on your use of characters in the extended range. For more information on UTF-8 and Unicode, see the Unicode Multilingual Support appendix in the Photon Programmer's Guide.

In the QNX 4 filesystem, you can use international characters in filenames by using the UTF-8 encoding of Unicode characters. If you're using the Photon microGUI, this is done transparently (you can enter the necessary characters directly from your keyboard, and the display shows them correctly within the Photon file manager). Filenames containing UTF-8 characters are generally illegible when viewed from the command line.

You can also use the ISO-Latin1 supplemental and PC character sets for international characters; however, the appearance of these 8-bit characters depends on the display settings of your terminal, and might not appear as you expect from within Photon or in other operating systems that access the files via a network.

Most other operating systems, including Microsoft Windows, support UTF-8/Unicode characters, and their filenames appear correctly in the Photon microGUI environment. Filenames from older versions of Microsoft Windows may be encoded using 8-bit characters with various language codepage in effect. The DOS filesystem in Neutrino can translate these filenames to UTF-8 representations, but you need to tell the filesystem which codepage to use via a command-line option. For more information see fs-dos.so in the Utilities Reference.


Note: All our disk filesystems except fs-qnx4.so — i.e. fs-cd.so, fs-dos.so, fs-ext2.so, the Power-safe filesystem (fs-qnx6.so), and fs-udf.so — use UTF-8 encoding for presentation of their filenames; attempts to specify a filename not using UTF-8 encoding will fail (with an error of EILSEQ) on these filesystems.

Where everything is stored

The default Neutrino filesystem generally follows the Filesystem Hierarchy Standard, but we don't claim to be compliant or compatible with it. This standard describes where files and directories should or must be placed in UNIX-style operating systems. For more information, see http://www.pathname.com.


Note: The Neutrino pathname space is extremely flexible. Your system may be configured differently.

This section describes the contents of these directories (select a directory from this diagram to go to its description):

/var /usr /tmp /sbin /root /lib /home /fs /etc /dev /boot /bin / /proc

Directories under /

/

The / directory is the root of the pathname space. Usually your primary hard disk or flash filesystem is mounted here. On a QNX 4 filesystem, this directory includes the following files:

/.altboot
Contains an alternate OS image that's loaded if you press ESC during bootup and you're using the QNX 4 filesystem; see Controlling How Neutrino Starts.
/.bitmap
A system file that contains a bitmap representing the disk regions in use by the filesystem. Each block is represented by one bit; if the bit is set, the filesystem is using the block.

You must preserve the integrity of this file to prevent disk corruption. After an unexpected shutdown, run chkfsys to walk through the entire filesystem and validate this file's contents, correcting them if necessary. For more information, see QNX 4 filesystem in Working with Filesystems, and chkfsys in the Utilities Reference.

/.boot
This item depends on the filesystem you're using:

For more information, see Controlling How Neutrino Starts, as well as QNX Neutrino and QNX 4 bootloader partitions in the Neutrino Technical Notes.

/.diskroot
A file that indicates which QNX 4 filesystem to mount as /. For more information, see Controlling How Neutrino Starts.
/.inodes
Contains additional data pointing to extra inode blocks required by files that occupy more than one extent (i.e. more than one contiguous region on the disk device). For more information, see QNX 4 filesystem in Working with Filesystems.

The / directory also contains platform-specific directories (e.g. armle, ppcbe, x86), as well as the directories described in the sections that follow.

/bin

The /bin directory contains binaries of essential utilities, such as chmod, ls, and ksh.

To display basic utility syntax, type use utilityname from the command line. For more information, see use in the Utilities Reference.

/boot

The /boot directory contains files and directories related to creating bootable OS images (image filesystems). Image filesystems contain OS components, your executables, and data files that need to be present and running immediately upon bootup. For general information on this topic, see Making an OS Image in the Building Embedded Systems guide, and mkifs in the Utilities Reference.

This directory includes:

/boot/build/
This directory contains the mkifs buildfiles used to build OS images. The buildfiles for a standard x86-based Neutrino system are qnxbase.build and qnxbasedma.build.
/boot/fs/
By convention, we use this directory to store image filesystems built by mkifs. To boot from one of the images, you'll need to copy it to /.boot on a bootable QNX 4-filesystem device first.
/boot/sys/
IPL and startup code are located here. This is one of the paths searched by the mkifs utility as it tries to resolve components named in the buildfile.

/dev

As described earlier, the /dev directory belongs to the process manager. This directory contains device files, possibly including:

/dev/cdn
CD-ROM block devices; see devb-* in the Utilities Reference for driver information.
/dev/conn
Text mode console TTY device; see devc-con in the Utilities Reference.
/dev/console
The device that's used for diagnostic log messages; on a full x86 system, this is a write-only device managed by the system logger, slogger. Buildfiles for embedded systems may configure a link from this path to another device, such as a serial port. See slogger in the Utilities Reference.
/dev/fdn
Floppy disk block devices; see devb-fdc in the Utilities Reference for driver details.
/dev/hdn
Hard disk block devices; data representing an entire drive, spanning all partitions; see devb-* in the Utilities Reference.
/dev/hdntn
Hard disk partition block devices; the data in these devices is a subset of that represented by the corresponding hdn file; see devb-* in the Utilities Reference.
/dev/io-net/
A directory owned and operated by io-pkt*, under which you can find files relating to the network devices for your various LANs. C programs can perform devctl() operations on these files to interact with the driver, e.g. to obtain driver statistics.

Note: Only legacy io-net drivers create entries under /dev/io-net/; native io-pkt* drivers don't.

/dev/mem
A device that represents all physical memory.
/dev/mq, /dev/mqueue
A pathname space where entries for message queues appear; for more information, see mq and mqueue in the Utilities Reference.
/dev/null
A “bit bucket” that you can direct data to. The data is discarded.
/dev/parn
Parallel ports e.g. for parallel printers; see stty for configuration, and devc-par for driver details in the Utilities Reference.
/dev/pci
Adopted by the PCI server on the machine, this device lets programs communicate with the PCI server. See pci-* in the Utilities Reference.
/dev/phfont
Adopted by the Photon font server, either io-graphics using the phfont.so library, or phfont running as a separate process. This file lets programs communicate with the font server. See io-graphics and phfont in the Utilities Reference.
/dev/photon
A special file that programs use to attach to a Photon server running on this machine. For more information, see Photon in the Utilities Reference.
/dev/pipe
Adopted by the pipe manager. The presence of this file tells other programs (such as a startup script built into an OS image) that the Pipe manager is successfully running.
/dev/ptypx, /dev/ptyqx, /dev/ptyrx
The control side of a pseudo-terminal device pair. Pseudo-ttys are numbered with a hexadecimal digit. When more than 16 pseudo-ttys are present, devc-pty uses the additional prefixes, /dev/ptyq, /dev/ptyr, and so on, as necessary, to accommodate the additional ttys. See devc-pty in the Utilities Reference.
/dev/random
Read from this device to obtain random data; see random in the Utilities Reference.
/dev/sem
A pathname space where entries for named semaphores appear.
/dev/sern
Serial ports. See stty for configuration, and devc-ser* for driver details in the Utilities Reference.
/dev/shmem/
Contains files representing shared memory regions on the system (also sometimes used for generic memory-mapped files). For more information, see the description of the RAM “filesystem” in Working with Filesystems.
/dev/slog
A device managed by slogger, used to read or write system log messages. Try sloginfo /dev/slog. See slogger and sloginfo in the Utilities Reference for more information.
/dev/socket/
This directory is owned and managed through the TCP/IP stack, which is included in io-pkt*. This directory contains pathnames through which applications interact with the stack. For more information, see the TCP/IP Networking chapter in this guide.
/dev/text
This file is managed by procnto. Text written to this device is output through debug output routines encoded in the startup code for your system.

The actual result, therefore, varies from board to board. On a standard PC (using startup-BIOS), the default is to write to the PC console. For more information, see startup-* in the Utilities Reference.

/dev/tty
A virtual device owned by the process manager (procnto) that resolves to the controlling terminal device associated with the session of any process that opens the file. This is useful for programs that may have closed their standard input, standard output, or standard error, and later wish to write to the terminal device.
/dev/ttypx, /dev/ttyqx, /dev/ttyrx
The slave side of the corresponding /dev/ptypx file. The program being controlled typically uses one of these files for its standard input, standard output, and standard error.
/dev/zero
Supplies an endless stream of bytes having a value of zero.

/etc

The /etc directory contains host-specific system files and programs used for administration and configuration, including:

/etc/acl.conf
Specifies permitted operations on a defined SNMP context. See /etc/acl.conf in the Utilities Reference.
/etc/autoconnect
Automatic TCP/IP connection-configuration script. See /etc/autoconnect in the Utilities Reference.
/etc/bootptab
Network boot protocol server configuration file. See /etc/bootptab in the Utilities Reference.
/etc/config/
A directory that contains system-configuration files, such as the ttys file that tinit uses to configure terminal devices.
/etc/context.conf
Context definitions for SNMP v2. See /etc/context.conf in the Utilities Reference.
/etc/country
Set by phlocale, this is used by applications to tailor behavior for the country that you're running the system in.
/etc/default/
A directory that contains default configuration files, primarily for TCP/IP facilities.
/etc/dhcpd.conf
Dynamic Host Configuration Protocol configuration; see /etc/dhcpd.conf in the Utilities Reference.
/etc/ftpd.conf
Specifies configuration options for ftpd that apply once you've authenticated your connection. See /etc/ftpd.conf in the Utilities Reference.
/etc/ftpusers
Defines users who may access the machine via the File Transfer Protocol. See /etc/ftpusers in the Utilities Reference.
/etc/group
User account group definitions; see Managing User Accounts.
/etc/hosts
Network hostname lookup database; see also /etc/nsswitch.conf and /etc/resolv.conf, below. See /etc/hosts in the Utilities Reference.
/etc/inetd.conf
Internet super-server configuration file that defines Internet services that inetd starts and stops dynamically as needed. See /etc/inetd.conf in the Utilities Reference.
/etc/mib.txt
Defines the format for specifying variable names for SNMP utilities; see /etc/mib.txt in the Utilities Reference.
/etc/motd
Contains an ASCII message of the day that may be displayed when users log in, as long as /etc/profile is configured to display it.

The default /etc/profile displays this file only if the /etc/motd file is more recent than the time you last logged in to the system, as determined by the time your $HOME/.lastlogin file was last modified. For more information, see the description of /etc/profile in Configuring Your Environment.

/etc/networks
Network name database file. For more information, see /etc/networks in the Utilities Reference.
/etc/nsswitch.conf
Name-service switch configuration file. For more information, see /etc/nsswitch.conf in the Utilities Reference.
/etc/opasswd
Backup of /etc/passwd file before its last change via the passwd utility. See the Managing User Accounts chapter.
/etc/oshadow
Backup of /etc/shadow file before its last change via the passwd utility. See Managing User Accounts.
/etc/party.conf
Configuration file for SNMP v2 party definitions. See /etc/party.conf in the Utilities Reference for more details.
/etc/passwd
This file defines login accounts. See the chapter Logging In, Logging Out, and Shutting Down, as well as Managing User Accounts for more details; also, see passwd, login, phlogin2, and phlogin in the Utilities Reference.
/etc/photon/
A directory that contains some Photon-related configuration files, including:
pterm
Configuration files for pterm.
shelf/
A directory that contains the default configuration file for the shelf, and the default layout of the Launch menu.
shells/
An optional directory where you can put configuration files for phlogin2 or phlogin.
wm
Configuration files for the window manager, pwm.

For more information, see Using the Photon microGUI.

/etc/printers/
A directory that contains printertype.cfg files and a fontmap file used by the phs-to-ps utility. For more information, see Printing with spooler in the Printing chapter.
/etc/profile
The startup profile script executed by the shell when you log in; it's executed before $HOME/.profile. See Configuring Your Environment.
/etc/profile.d/
A directory where the default /etc/profile script looks for scripts to run when any user logs in. The /etc/profile script runs each script in this directory that matches *.$(SHELL##*/}. For example, if the value of the SHELL environment variable is /bin/sh, the script runs the scripts that match *.sh.
/etc/rc.d/
A directory where you usually keep local system-initialization files. For more information, see the description of /etc/system/sysinit in Controlling How Neutrino Starts.
/etc/resolv.conf
Resolver configuration file; see also /etc/hosts, above. See /etc/resolv.conf in the Utilities Reference.
/etc/skel/
A directory that holds the default version of .profile. When you add a new user to the system, this file is copied to the user's home directory. For more information, see the description of /etc/default/passwd in the documentation for passwd, and the description of .profile in Configuring Your Environment.
/etc/system/
A directory that includes files and directories used when you boot the system, including:

For more information, see the Controlling How Neutrino Starts chapter.

/etc/timezone/
A directory where phlocale looks for a list of possible time zones; see Setting the time zone in Configuring Your Environment.

/fs

Additional filesystems are mounted under /fs. See Working with Filesystems in this guide, and devb-* and mount in the Utilities Reference. This directory can include:

/fs/cdn/
CD-ROM filesystems.
/fs/fdn/
Floppy disk filesystems.
/fs/hdn-type[-number]/
Filesystems on hard disk partitions.

/home

The home directories of regular users are found here. The name of your home directory is often the same as your user name.

/lib

A directory that contains essential shared libraries that programs need in order to run (filename.so), as well as static libraries used during development. See also /usr/lib and /usr/local/lib.

The /lib directory includes:

/lib/dll/
Contains additional shared libraries that implement OS drivers and services, such as drivers, filesystem managers, and so on. For some examples of how shared libraries are used for certain types of drivers and services, see Filesystems, Native Networking (Qnet), and TCP/IP Networking in the System Architecture guide. For details about specific shared objects in the /lib/dll directory, see their respective entries in the Utilities Reference.

/proc

Owned by the process manager (procnto), this virtual directory can give you information about processes and pathname-space configuration.

The /proc directory contains a subdirectory for each process; the process ID is used as the name of the directory. These directories each contain an entry (as) that defines the process's address space. Various utilities use this entry to get information about a process. For more information, see Controlling processes via the /proc filesystem in the Processes chapter of the QNX Neutrino Programmer's Guide.

The /proc directory also includes:

/proc/boot/
The image filesystem that comprises the boot image. For more information, see Making an OS Image in Building Embedded Systems.
/proc/dumper
A special entry that receives notification when a process terminates abnormally. The dumper utility watches this entry.
/proc/mount/
Pathname-space mountpoints.

Note: If you list the contents of the /proc directory, /proc/mount doesn't show up, but you can list the contents of /proc/mount.

/proc/qnetstats
If you're using Transparent Distributed Processing (TDP), the lsm-qnet.so module places a qnetstats entry in /proc. If you open this name and read from it, the Qnet resource manager code responds with the current statistics for Qnet.
/proc/self/
The address space for yourself (i.e. for the process that's making the query).

/root

The /root directory is the home directory for the root user.

/sbin

This directory contains essential system binaries, including:

Many of these files are used when you boot the system; for more information, see Controlling How Neutrino Starts.

/tmp

This directory contains temporary files. Programs are supposed to remove their temporary files after using them, but sometimes they don't, either due to poor coding or abnormal termination. You can periodically clean out extraneous temporary files when your system is idle.

/usr

The /usr directory is a secondary file hierarchy that contains shareable, read-only data, and includes:

/usr/bin/
A directory that contains most user commands, such as diff, errno, and wc.
/usr/help/
A directory that contains the documentation (in the product directory) and common images (in the lib/images directory). For more information, see Getting help with the Helpviewer in Using the Photon microGUI, and helpviewer in the Utilities Reference.
/usr/include/
The top of a directory structure that contains the C and C++ header files. This directory includes sys, platform-specific, and other directories.
/usr/info/
Documentation for various utilities.
/usr/lib/
Object files, libraries, and internal binaries that you shouldn't execute directly or in scripts. You'll link against these libraries if you write any programs.
/usr/libexec/
A directory that could contain system daemons and system utilities; in general, these are run only by other programs.
/usr/local/
A directory where the system administrator can install software locally. It's initially empty.
/usr/man/
“Manual pages” for various utilities.
/usr/photon/
The top of a directory structure that contains executables, data files, and so on, associated with Photon.
/usr/qde/
The top of a directory structure that contains executables, data files, plugins, etc. associated with the Integrated Development Environment (IDE), which is shipped as part of the QNX Momentics Tool Suite on Linux and Windows.
/usr/sbin/
Nonessential system binaries, such as cron, dumper, and nicinfo.
/usr/share/
Data that's independent of the architecture, such as icons, backdrops, and various gawk programs.
/usr/src/
A directory for source code.

/var

The /var directory contains variable data files, including cache files, lock files, log files, and the following:

/var/dumps
The directory where dumper saves any dumps that result when a program terminates abnormally.

File ownership and permissions

Each file and directory belongs to a specific user ID and group ID, and has a set of permissions (also referred to as modes) associated with it. You can use these utilities to control ownership and permissions:

To: Use:
Specify the permissions for a file or directory chmod
Change the owner (and optionally the group) for a file or directory chown
Change the group for a file or directory chgrp

For details, see the Utilities Reference.


Note: You can change the permissions and ownership for a file or directory only if you're its owner or you're logged in as root. If you want to change both the permissions and the ownership, change the permissions first. Once you've assigned the ownership to another user, you can't change the permissions.

Permissions are divided into these categories:

u
Permissions for the user (i.e. the owner)
g
Permissions for the group.
o
Permissions for others (i.e. everyone who isn't in the group).

Each set of permissions includes:

r
Read permission.
w
Write permission.
x
Execute permission. For a directory, this is permission to list or search the directory.
s or S
Setuid or setgid (see below).
t or T
Sticky bit (see below).

For example, if you list your home directory (using ls -al), you might get output like this:

total 94286
drwxr-xr-x 18 barney    techies        6144 Sep 26 06:37 ./
drwxrwxr-x  3 root      root           2048 Jul 15 07:09 ../
drwx------  2 barney    techies        4096 Jul 04 11:17 .AbiSuite/
-rw-rw-r--  1 barney    techies         185 Oct 27  2000 .Sig
-rw-------  1 barney    techies          34 Jul 05  2002 .cvspass
drwxr-xr-x  2 barney    techies        2048 Feb 26  2003 .ica/
-rw-rw-r--  1 barney    techies         320 Nov 11  2002 .kshrc
-rw-rw-r--  1 barney    techies           0 Oct 02 11:17 .lastlogin
drwxrwxr-x  3 barney    techies        2048 Oct 17  2002 .mozilla/
drwxrwxr-x 11 barney    techies        2048 Sep 08 09:08 .ph/
-rw-r--r--  1 barney    techies         254 Nov 11  2002 .profile
drwxrwxr-x  2 barney    techies        4096 Jul 04 09:06 .ws/
-rw-rw-r--  1 barney    techies        3585 Dec 05  2002 123.html

The first column is the set of permissions. A leading d indicates that the item is a directory; see Types of files,” earlier in this chapter.

You can also use octal numbers to indicate the modes; see chmod in the Utilities Reference.

Setuid and setgid

Some programs, such as passwd, need to run as a specific user in order to work properly:

$ which -l passwd
-rwsrwxr-x  1 root      root         21544 Mar 30 23:34 /usr/bin/passwd

Notice that the third character in the owner's permissions is s. This indicates a setuid (“set user ID”) command; when you run passwd, the program runs as the owner of the file (i.e. root). An S means that the setuid bit is set for the file, but the execute bit isn't set.

You might also find some setgid (“set group ID”) commands, which run with the same group ID as the owner of the file, but not with the owner's user ID. If setgid is set on a directory, files created in the directory have the directory's group ID, not that of the file's creator. This scheme is commonly used for spool areas, such as /usr/spool/mail, which is setgid and owned by the mail group, so that programs running as the mail group can update things there, but the files still belong to their normal owners.


Note: If you change the ownership of a setuid command, the setuid bit is cleared, unless you're logged in as root. Similarly, if you change the group of a setgid command, the setgid bit is cleared, unless you're root.

When running on a Windows host, mkefs, mketfs, and mkifs can't get the execute (x), setuid (“set user ID”), or setgid (“set group ID”) permissions from the file. Use the perms attribute to specify these permissions explicitly. You might also have to use the uid and gid attributes to set the ownership correctly. To determine whether or not a utility needs to have the setuid or setgid permission set, see its entry in the Utilities Reference.



Caution: Setuid and setgid commands can cause a security problem. If you create any, make sure that only the owner can write them, and that a malicious user can't hijack them — especially if root owns them.

Sticky bit

The sticky bit is an access permission that affects the handling of executable files and directories:

If the third character in a set of permissions is t (e.g. r-t), the sticky bit and execute permission are both set; T indicates that only the sticky bit is set.

Default file permissions

Use the umask command to specify the mask for setting the permissions on new files. The default mask is 002, so any new files give read and write permission to the user (i.e. the owner of the file) and the rest of the user's group, and read permission to other users. If you want to remove read and write permissions from the other users, add this command to your .profile:

umask 006

If you're the system administrator, and you want this change to apply to everyone, change the umask setting in /etc/profile. For more information about profiles, see Configuring Your Environment.

Filename extensions

This table lists some common filename extensions used in a Neutrino system:

Extension Description Related programs/utilities
.1 Troff-style text, e.g. from UNIX “man” (manual) pages. man and troff (third-party software)
.a Library archive ar
.awk Awk script gawk
.b Bench calculator library or program bc
.bat MS-DOS batch file For use on DOS systems; won't run under Neutrino. See Writing Shell Scripts and ksh for information on writing shell scripts for Neutrino.
.bmp Bitmap graphical image pv (Photon viewer)
.build OS image buildfile mkifs
.c C program source code qcc, make (QNX Momentics Tool Suite required)
.C, .cc, .cpp C++ program source code QCC, make (QNX Momentics Tool Suite required)
.cfg Configuration files, various formats Various programs; formats differ
.conf Configuration files, various formats Various program; formats differ
.css Cascading style sheet Used in the QNX Momentics Tool Suite for Eclipse documentation
.def C++ definition file QCC, make (QNX Momentics Tool Suite required)
.dll MS-Windows dynamic link library Not used directly in Neutrino; necessary in support of some programs that run under MS-Windows, such as some of the QNX Momentics tools. See .so (shared objects) for the Neutrino equivalent.
.gif GIF graphical image pv (Photon viewer)
.gz Compressed file gzip; Backing Up and Recovering Data
.h C header file qcc, make (QNX Momentics Tool Suite required)
.htm HyperText Markup Language (HTML) file for Web viewing Web browser
.html HyperText Markup Language (HTML) file for Web viewing helpviewer, web browser
.ifs, .img A QNX Image filesystem, typically a bootable image mkifs; see also Making an OS Image in Building Embedded Systems
.jar Java archive, consisting of multiple java files (class files etc.) compressed into a single file Java applications e.g. the QNX Momentics IDE
.jpg JPEG graphical image pv (Photon viewer)
.kbd Compiled Photon keyboard definition files Photon, mkkbd
.kdef Source Photon keyboard definition files mkkbd
.mk Makefile source, typically used within QNX recursive makes make (QNX Momentics Tool Suite)
.o Binary output file that results from compiling a C, C++, or Assembly source file qcc, make (QNX Momentics Tool Suite)
.pal Photon palette file Photon
.pfr Bitstream TrueDoc Portable Font Resource file phfont
.phf Bitmapped font file phfont
.S, .s Assembly source code file GNU assembler as (QNX Momentics Tool Suite)
.so, .so.n Shared object qcc, make (QNX Momentics Tool Suite)
.tar Tape archive tar; Backing Up and Recovering Data
.tar.gz, .tgz Compressed tape archive gzip, tar; Backing Up and Recovering Data
.toc Helpviewer table of contents file helpviewer
.TTF TrueType fonts phfont
.txt ASCII text file Many text-based editors, applications, and individual users
.ttf TrueType font file phfont
.use Usage message source for programs that don't embed usage in the program source code (QNX recursive make) make (QNX Momentics Tool Suite)
.wav Audio wave file
.xml Extensible Markup Language file; multiple uses, including IDE documentation in a QNX Momentics Tool Suite
.zip Compressed archive file gzip

If you aren't sure about the format of a file, use the file utility:

file filename

Troubleshooting

Here are a few problems that you might have with files:

I'm trying to write a file, but I get a “permission denied” message.
You don't have write permission for the file. If you're the owner (or root) you can change the permissions; see File ownership and permissions,” above.
I'm trying to list a directory that I have write permission for, but I get a “permission denied” message.
You need to have read or execute permission for a directory in order to list it. See File ownership and permissions,” above.
I'm having trouble with a file that has a space in its name.
The command interpreter, or shell, parses the command line and uses the space character to break the command into tokens. If your filename includes a space, you need to “quote” the space so that the shell knows you want a literal space. For more information, including other special characters that you need to watch for, see Quoting special characters in Using the Command Line.