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

Configuring Your Environment

This chapter includes:

The Controlling How Neutrino Starts chapter describes what happens when you boot your system, and what you can do to customize the system. This chapter describes how you can customize the environment that you get when you log in, and then describes some of the setup you might need to do.

What happens when you log in?

Before you start customizing your login environment, you should understand just what happens when you log in, because the nature of the customization determines where you should make it. You should consider these questions:

When you log in, the system starts the login shell that's specified in your entry in the account database (see /etc/passwd in Managing User Accounts). The login shell is typically sh, which is usually just a link to the Korn shell, ksh.

When ksh starts as a login shell, it executes these profiles, if they exist and are executable:

Why have two profiles? Settings that apply to all users go into /etc/profile; your own customizations go into your own .profile. As you might expect, you need to be root to edit /etc/profile.

There's actually a third profile for the shell. The special thing about it is that it's executed whenever you start a shell; see ksh's startup file,” below.

Customizing your home

Your home directory is where you can store all the files and directories that are relevant to you. It's a good place to store your own binaries and scripts. Your entry in the password database specifies your home directory (see /etc/passwd in Managing User Accounts), and the HOME environment variable stores this directory's name.

Your home directory is also where you store information that configures your environment when you log in. By default, applications pick this spot to install configuration files. Configuration files are generally preceded by a period (.) and run either when you log in (such as .profile) or when you start an application (such as .jedrc).

Photon applications are a special case. Applications that are run in Photon generally store their configurations in the $HOME/.ph directory. If you want to automatically start any applications when you start Photon, put the commands in your $HOME/.ph/phapps file.

Configuring your shell

There are many files that configure your environment; this section describes some of the more useful ones:

/etc/profile

The login shell executes /etc/profile if this file exists and is readable. This file does the shell setup that applies to all users, so you'll be interested in it if you're the system administrator; you need to log in as root in order to edit it.

The /etc/profile file:

If you have a script that you want to run whenever anyone on the system runs a login shell, put it in the /etc/profile.d directory. You must have root-level privileges to add a file to this directory.

For example, if you need to set global environment variables or run certain tasks when anyone logs in, then this is the place to put a script to handle it. If you're using sh as your login shell, make sure that the script has a .sh extension.

$HOME/.profile

The system runs $HOME/.profile whenever you log in, after it runs /etc/profile. If you change your .profile, the changes don't go into effect until you next log in.

You should use your .profile to do the customizations that you need to do only once, or that you want all shells to inherit. For example, you could:


Note: If you want to create an alias, you should do it in your shell's profile (see ksh's startup file,” below), not in .profile, because the shell doesn't export aliases. If you do set an alias in .profile, the alias is set only in shells that you start as login shells, using the -l option.

Don't start Photon applications in .profile, because Photon isn't running when this script is executed; use the $HOME/.ph/phapps file instead.


For an example of .profile, see the Examples appendix.

ksh's startup file

As described above, the login shell runs certain profiles. In addition, you can have a profile that ksh runs whenever you start a shell — whether or not it's a login shell.

This profile doesn't have a specific name; when you start ksh, it checks the ENV environment variable. If this variable exists, ksh gets the name of the profile from it. To set up ENV, add a line like this to your $HOME/.profile file:

export ENV=$HOME/.kshrc

People frequently call the profile .kshrc, but you can give it whatever name you want. This file doesn't need to be executable.

Use ksh's profile to set up your favorite aliases, and so on. For example, if you want ls to always display characters that tell you if a file is executable, a directory, or a link, add this line to the shell's profile:

alias ls="ls -F"

Any changes that you make to the profile apply to new shells, but not to existing instances.

For an example of .kshrc, see the Examples appendix.

Environment variables

Many applications use environment variables to control their behavior. For example, less gets the width of the terminal or window from the COLUMNS environment variable; many utilities write any temporary files in the directory specified by TMPDIR. For more information, see the Commonly Used Environment Variables appendix of the Utilities Reference.

When you start a process, it inherits a copy of its parent's environment. This means that you can set an environment variable in your .profile, and all your shells and processes inherit it — provided that no one in the chain undefines it.

For example, if you have your own bin directory, you can add it to your PATH by adding a line like this to your .profile:

export PATH=$PATH:/home/username/bin

If you're the system administrator, and you want this change to apply to everyone, export the environment variables from /etc/profile or from a script in /etc/profile.d. For more information, see the discussion of /etc/profile earlier in this chapter.

Setting PATH and LD_LIBRARY_PATH

The login utility doesn't preserve environment variables, except for a few special ones, such as PATH and TERM.

The PATH environment variable specifies the search paths for commands, while LD_LIBRARY_PATH specifies the search paths for shared libraries for the linker.

The initial default values of PATH and LD_LIBRARY_PATH are specified in the buildfile before procnto is started. Two configuration strings (see Configuration strings,” below), _CS_PATH and _CS_LIBPATH, take the default values of PATH and LD_LIBRARY_PATH. The login utility uses _CS_PATH to set the value of PATH and passes this environment variable and both configuration strings to its child processes.

If you type set or env in a shell that was started from login, you'll see the PATH variable, but not LD_LIBRARY_PATH; _CS_LIBPATH works in the same manner as LD_LIBRARY_PATH.

You can use the /etc/default/login file to indicate which environment variables you want login to preserve. You can edit this file to add new variables, such as LD_LIBRARY_PATH, but you can't change existing variables such as PATH and TERM.

If you use ksh as your login shell, you can edit /etc/profile and $HOME/.profile to override existing variables and add new ones. Any environment variables set in /etc/profile override previous settings in /etc/default/login; and $HOME/.profile overrides both /etc/default/login and /etc/profile.

For more information on configuration strings, see Configuration strings,” below.

Configuration strings

In addition to environment variables, Neutrino uses configuration strings. These are system variables that are like environment variables, but are more dynamic.

When you set an environment variable, the new value affects only the current instance of the shell and any of its children that you create after setting the variable; when you set a configuration string, its new value is immediately available to the entire system.


Note: Neutrino also supports configurable limits, which are variables that store information about the system. For more information, see the Understanding System Limits chapter.

You can use the POSIX getconf utility to get the value of a configurable limit or a configuration string. Neutrino also defines a non-POSIX setconf utility that you can use to set configuration strings if you're logged in as root. In a program, call confstr() to get the value of a configuration string.

The names of configuration strings start with _CS_ and are in uppercase, although getconf and setconf let you use any case, omit the leading underscore, or the entire prefix — provided that the rest of the name is unambiguous.

The configuration strings include:

_CS_ARCHITECTURE
The name of the instruction-set architecture.
_CS_DOMAIN
The domain of this node in the network.
_CS_HOSTNAME
The name of this node in the network.

Note: A hostname can consist only of letters, numbers, and hyphens, and must not start or end with a hyphen. For more information, see RFC 952.

If you change this configuration string, be sure you also change the HOSTNAME environment variable. The hostname utility always gives the value of the _CS_HOSTNAME configuration string.


_CS_HW_PROVIDER
The name of the hardware's manufacturer.
_CS_HW_SERIAL
The serial number associated with the hardware.
_CS_LIBPATH
The default path for locating shared objects. For more information, see Setting PATH and LD_LIBRARY_PATH,” below.
_CS_LOCALE
The locale string.
_CS_MACHINE
The type of hardware the OS is running on.
_CS_PATH
The default path for finding system utilities. For more information, see Setting PATH and LD_LIBRARY_PATH,” below.
_CS_RELEASE
The current release level of the OS.
_CS_RESOLVE
An in-memory version of the /etc/resolv.conf file, excluding the domain name.
_CS_SRPC_DOMAIN
The secure RPC (Remote Procedure Call) domain.
_CS_SYSNAME
The name of the OS.
_CS_TIMEZONE
An alternate source to the TZ for time-zone information. For more information, see Setting the time zone,” below.
_CS_VERSION
The version of the OS.

Setting the time zone

If you're running Photon, the easiest way to set the time zone is via phlocale. You simply select the appropriate zone, and phlocale does everything else.

If you aren't running Photon, you need to set the TZ environment variable or the _CS_TIMEZONE configuration string. To set the time zone when you boot your machine, you have to put the same information in the /etc/TIMEZONE file; see the description of /etc/system/sysinit in Controlling How Neutrino Starts.


Note: If TZ isn't set, the system uses the value of the _CS_TIMEZONE configuration string instead. The POSIX standards include the TZ environment variable; _CS_TIMEZONE is a Neutrino implementation. The description below applies to both.

Various time functions use the time-zone information to compute times relative to Coordinated Universal Time (UTC), formerly known as Greenwich Mean Time (GMT).

You usually set the time on your computer to UTC. Use the date command if the time isn't automatically maintained by the computer hardware.

You can set the TZ environment variable by using the env utility or the export shell command. You can use setconf to set _CS_TIMEZONE. For example:

env TZ=PST8PDT
export TZ=PST8PDT
setconf _CS_TIMEZONE PST8PDT

The format of the TZ environment variable or _CS_TIMEZONE string is as follows (spaces are for clarity only):

std offset dst offset, rule

The expanded format is as follows:

stdoffset[dst[offset][,start[/time],end[/time]]]

The components are:

std and dst
Three or more letters that you specify to designate the standard or daylight saving time zone. Only std is required. If you omit dst, then daylight saving time doesn't apply in this locale. Upper- and lowercase letters are allowed. Any characters except for a leading colon (:), digits, comma (,), minus (-), plus (+), and ASCII NUL (\0) are allowed.
offset
The value you must add to the local time to arrive at Coordinated Universal Time (UTC). The offset has the form:

hh[:mm[:ss]]

Minutes (mm) and seconds (ss) are optional. The hour (hh) is required; it may be a single digit.

The offset following std is required. If no offset follows dst, summer time is assumed to be one hour ahead of standard time.

You can use one or more digits; the value is always interpreted as a decimal number. The hour may be between 0 and 24; the minutes (and seconds), if present, between 0 and 59. If preceded by a -, the time zone is east of the prime meridian; otherwise it's west (which may be indicated by an optional preceding “+”).

rule
Indicates when to change to and back from summer time. The rule has the form:

date/time,date/time

where the first date describes when the change from standard to summer time occurs, and the second date describes when the change back happens. Each time field describes when, in current local time, the change to the other time is made.

The format of date may be one of the following:

Jn
The Julian day n (1 <= n <= 365). Leap days aren't counted. That is, in all years — including leap years — February 28 is day 59 and March 1 is day 60. It's impossible to refer explicitly to the occasional February 29.
n
The zero-based Julian day (0 <= n <= 365). Leap years are counted; it's possible to refer to February 29.
Mm.n.d
The dth day (0 <= d <= 6) of week n of month m of the year (1 <= n <= 5, 1 <= m <= 12, where week 5 means “the last d day in month m, which may occur in the fourth or fifth week). Week 1 is the first week in which the dth day occurs. Day zero is Sunday.

The time has the same format as offset, except that no leading sign (“+” or “-”) is allowed. The default, if time is omitted, is 02:00:00.

Caveats

Examples

This section examines some sample time-zone settings.


Note: As mentioned above, the library interprets the short specifications of North American time zones according to the rules that went into effect March 1, 2007.

Eastern time

The default time zone is Eastern time; the short specification is:

EST5EDT

The full specification is:

EST5EDT4,M3.2.0/02:00:00,M11.1.0/02:00:00

Both are interpreted as follows:

Pacific time

The short specification for Pacific time is:

PST8PDT

The full specification is:

PST08PDT07,M3.2.0/2,M11.1.0/2

Both are interpreted as follows:

Newfoundland time

The short specification for Newfoundland time is:

NST3:30NDT2:30

The full specification is:

NST03:30NDT02:30,M3.2.0/00:01,M11.1.0/00:01

Both are interpreted as follows:

Central European time

The specification for Central European time is:

Central Europe Time-2:00

Japanese time

The specification for Japanese time is:

JST-9

Programming with time zones

Inside a program, you can set the TZ environment variable by calling setenv() or putenv():

setenv( "TZ", "PST08PDT07,M3.2.0/2,M11.1.0/2", 1 );
putenv( "TZ=PST08PDT07,M3.2.0/2,M11.1.0/2" );

To obtain the value of the variable, use the getenv() function:

char *tzvalue;
…
tzvalue = getenv( "TZ" );

You can get the value of _CS_TIMEZONE by calling confstr(), like this:

confstr( _CS_TIMEZONE, buff, BUFF_SIZE );

or set it like this:

confstr( _CS_SET | _CS_TIMEZONE, "JST-9", 0 );

The tzset() function gets the current value of TZ — or _CS_TIMEZONE if TZ isn't set — and sets the following global variables:

daylight
Indicates if daylight saving time is supported in the locale.
timezone
The number of seconds of time difference between the local time zone and Coordinated Universal Time (UTC).
tzname
A vector of two pointers to character strings containing the standard and daylight time zone names.

Whenever you call ctime(), ctime_r(), localtime(), or mktime(), the library sets tzname, as if you had called tzset(). The same is true if you use the %Z directive when you call strftime().

For more information about these functions and variables, see the Neutrino Library Reference.

Customizing Photon

Starting applications automatically

If you want to run a Photon application whenever Photon starts, put it in your $HOME/.ph/phapps file. Put each command on a separate line. For example, to start the Photon editor when you start Photon, include this line:

ped &
  

Note: This file isn't a shell script, so don't set any environment variables in it.

The right fonts

The Photon environment supports a wide variety of font types. Any Unicode font should work inside of the Photon environment.

The font files on your system are stored in /usr/photon/font_repository. This directory contains the following:

*.phf
Photon Font files. These are bitmapped font files. Each file contains information for a single size and style of the font.
*.TTF, *.ttf
TrueType Font files.
*.pfr
Bitstream TrueDoc PFR (Portable Font Resource) files containing hinted scalable definitions of fonts. Each file may contain multiple fonts and multiple styles. This is an older technology supported for legacy reasons.
fontdir
Directory of known fonts. Each entry in this file contains information such as the name and type of the font, its size and style, a textual description of the font family, and the range of characters defined within the font. To be available to an application, at least one font must be defined in this configuration file. Entries in this file are static; they can't be loaded dynamically.
fontext
A set of extension rules to handle character dropouts (i.e. missing characters).
fontmap
Font mappings for the system. For detailed information about the format of this file, see phfont.
fontopts
Command-line options, one option per line, for invoking the appropriate font server.

To install a new font on your system, copy the font files into the font_repository directory, and run the mkfontdir utility to create the new fontdir file. You then need to restart your font manager, which is usually io-graphics. If you run a standalone phfont server, restart it too.

Input methods

Photon includes input methods for Chinese, Japanese, and Korean. You can launch these applications by typing cpim (Chinese Input Method), vpim (Japanese), or kpim (Korean). Using a standard keyboard, you can input characters in these languages to any application that normally accepts text. For more information, see the Photon Multilingual Input bookset.

Terminal types

You need to set the TERM environment variable to indicate to your console or pterm what type of terminal you're using. The /usr/lib/terminfo directory contains directories that contain terminal database information. You can use the utilities tic and infocmp to change the mappings in the database.

For example, you could run infocmp on /usr/lib/terminfo/q/qansi-m and this would generate the source for this database. You could then modify the source and then run the tic utility on that source to compile the source back in to a reconcilable database. The /etc/termcap file is provided for compatibility with programs that use the older single-file database model as opposed to the newer library database model.

For more information, see:

Strang, John, Linda Mui, and Tim O'Reilly. 1988. termcap & terminfo. Sebastopol, CA: O'Reilly and Associates. ISBN 0937175226.

Troubleshooting

Here are some common problems you might encounter while customizing your environment:

A script I put in /etc/profile.d doesn't run.
Check the following:
How do I set the time so it's right in Neutrino and Microsoft Windows?
If you have Windows in one partition and Neutrino in another on your machine, you might notice that setting the clock on one OS changes it on the other.

Under Neutrino, you usually set the hardware clock to use UTC (Coordinated Universal Time) and then set the time zone. Under Windows, you set the hardware clock to use local time.

To set the time so that it's correct in both operating systems, set the hardware clock to use local time under Neutrino. For more information, see the description of /etc/system/sysinit in the Controlling How Neutrino Starts chapter of this guide.

How can I properly check if .kshrc is being run as a script rather than as a terminal session?
If the i option is set, then .kshrc is running in interactive mode. Here's some code that checks to see if this option is set:
case $- in
*i*)

     set -o emacs

     export EDITOR=vi
     export VISUAL=vi
     export PS1='`hostname -s`:`/bin/pwd` >'

     bind ^[[z=list
     bind ^I=complete

     ...
esac
  

The $- parameter is a concatenation of all the single-letter options that are set for the script. For more information, see Parameters in the entry for ksh in the Utilities Reference.