---

Configuring Your Environment

This chapter includes:

• What happens when you log in?
• Customizing your home
• Configuring your shell
• Environment variables
• Configuration strings
• Setting the time zone
• Customizing Photon
• Terminal types
• Troubleshooting

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:

• Does this change apply to all users, or just to me?
• Do I need to do something only when I first log in, or whenever I start a shell?

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:

• /etc/profile
• $HOME/.profile

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
• $HOME/.profile
• ksh's startup file

/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:

• sets the HOSTNAME, PROCESSOR, and SYSNAME environment variables if they aren't already set
• adds the appropriate directories to the PATH environment variable (the root user's PATH includes directories such as /sbin that contain system executables)
• sets up the file-permission mask (umask); see “File ownership and permissions” in Working with Files
• displays the date you logged in, the “message of the day” (found in /etc/motd), and the date you last logged in
• sets the TMPDIR environment variable to /tmp if it isn't already set.
• runs any scripts in the /etc/profile.d directory as “dot” files (i.e. instead of executing them as separate shells, the current shell loads their commands into itself). For more information about dot files, see “. (dot) builtin command” in the documentation for ksh in the Utilities Reference.

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:

• set environment variables; see “Environment variables,” below
• run any commands that you need
• set your file-permission mask; see “File ownership and permissions” in Working with Files

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.

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.

---

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.

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

• The phlocale utility gets its list of time zones from /etc/timezone/uc_tz_t, but we don't guarantee that this file defines all of the world's time zones or that it's up-to-date; time zones depend on local legislation and may differ from those given in this file. The abbreviated names in this file above aren't necessarily standard and might not uniquely identify the time zone.
• The USA changed its time zone rules, effective March 1, 2007, as part of the Energy Policy Act of 2005. The change affected when daylight saving time starts and ends:

  Daylight Saving Time:	Old:	New:
  Starts	The first Sunday in April	The second Sunday in March
  Ends	The last Sunday in October	The first Sunday in November

  While the standard rule changed across all states, US states still have the right not to observe daylight saving time, as per the Uniform Time Act of 1966. For information about American time zones, see http://www.time.gov.

• Canada changed its time zones in a similar way; for more information, see http://inms-ienm.nrc-cnrc.gc.ca/faq_time_e.html.
• The calculation of local time in Neutrino isn't sophisticated enough to apply the old rules before March 1, 2007, and the new rules after that. The setting you use for TZ applies to all local times.
• The library interprets a short time zone specification (e.g. EST5EDT) according to the new rules.

Examples

This section examines some sample time-zone settings.

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:

• Eastern Standard Time is 5 hours earlier than Coordinated Universal Time (UTC). Standard time and daylight saving time both apply to this locale.
• By default, Eastern Daylight Time (EDT) is one hour ahead of standard time (i.e. EDT4).
• Daylight saving time starts on the second (2) Sunday (0) of March (3) at 2:00 A.M. and ends on the first (1) Sunday (0) of November (11) at 2:00 A.M.

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:

• Pacific Standard Time is 8 hours earlier than Coordinated Universal Time (UTC).
• Standard time and daylight saving time both apply to this locale.
• By default, Pacific Daylight Time is one hour ahead of standard time (that is, PDT7).
• Daylight saving time starts on the second (2) Sunday (0) of March (3) at 2:00 A.M. and ends on the first (1) Sunday (0) of November (11) at 2:00 A.M.

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:

• Newfoundland Standard Time is 3.5 hours earlier than Coordinated Universal Time (UTC).
• Standard time and daylight saving time both apply to this locale.
• Newfoundland Daylight Time is 2.5 hours earlier than Coordinated Universal Time (UTC).
• Daylight saving time starts on the second (2) Sunday (0) of March (3) at 12:01:00 A.M. and ends on the first (1) Sunday (0) of November (11) at 12:01:00 A.M.

Central European time

The specification for Central European time is:

Central Europe Time-2:00

• Central European Time is 2 hours later than Coordinated Universal Time (UTC).
• Daylight saving time doesn't apply in this locale.

Japanese time

The specification for Japanese time is:

JST-9

• Japanese Standard Time is 9 hours earlier than Coordinated Universal Time (UTC).
• Daylight saving time doesn't apply in this locale.

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 &
  

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:

• Make sure that the script's name has .ksh or .sh as its extension.
• Make sure the executable bit is set on the script.
• Make sure that the script begins with the line:

  #! /bin/sh
    

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.

---