swap(1M) swap(1M) NAME swap - swap administrative interface SYNOPSIS /sbin/swap -a [-i][-ppri][-vvlen] name [low [len]] /sbin/swap -d name/lswap [low] /sbin/swap -l [-n][-f][-b] /sbin/swap -s [-b] /sbin/swap -m /sbin/swap -u DESCRIPTION swap provides a method of adding, deleting, and monitoring the system swap areas used by the memory manager. The following options are recognized: -a Add the specified swap resource. name is the name of the block special partition, for example, /dev/dsk/dks0d1s1 or a regular file. Files on NFS mounted file systems are also permitted (see Swapping to NFS Files below). low is the offset in 512-byte blocks into the partition/file where the swap area should begin. If low is absent, a default of 0 is used. This value is rounded up to a multiple of the system defined swap page size. len is the length of the swap area in 512-byte blocks. If len is absent, the new swap area will use the entire partition/file. This value is rounded down to a multiple of the system defined swap page size. Files used as swap devices must exist and have been previously grown to the appropriate size (see mkfile(1m)). A maximum of 255 swap resources can be active at a given time. This option can only be used by a privileged user. Swap areas are normally added by modifying the /etc/fstab file to contain the various files and partitions that should be added when the system is booted. When using the -a or -m option, /etc/fstab is scanned for an entry whose type field contains swap and whose filesystem field matches name. name is made into a full path name. If an entry is found in /etc/fstab, any supplied options are used to supplement any options given on the command line (e.g. priority). -i Ignore safety checks. Normally, when adding a block special device as a swap resource, a check is made to try to be certain that the block device does not overlap any existing file systems. This option turns off that check. -p pri Swap resources have a priority between 0 and 7 inclusive where lower priority swap resources are allocated from first. Within a priority, allocations are done round-robin. By default, block devices are assigned a priority of 0, files on local file systems are assigned a priority of 2 and files on NFS mounted file systems are assigned a priority of 4. This option is only valid when adding a swap resource. -v vlength Set the virtual length of the swap area to vlength. Normally, if this field is not specified, the amount of logical swap is increased by the size of the physical swap device being added. This option tells the system to increase the logical swap amount by vlength. Thus, the difference between vlength and the actual size of the device is amount of virtual swap that is added. The virtual length must be greater than or equal to the physical length of the swap area. If not specified, the virtual length is set equal to the actual length. See swapctl(2) for a discussion on virtual swap spaces. In general, this option should only be used when there is no other way to get enough swap resources (even via NFS) and it is understood the potential problems creating virtual swap can cause. See the discussion of Logical Swap Space below. -d Delete the specified swap resource. name is the name of block special partition, for example, /dev/dsk/dks0d1s1 or a regular file. If name starts with a digit, it is interpreted as the logical swap number of the device to be deleted. This is useful when the file or device directory entry has been inadvertently been removed. low is the offset in 512-byte blocks into the swap area to be deleted. If not specified, a default of 0 is used. Using this option marks the swap area as ``INDEL'' (in the process of being deleted). The system will not allocate any new blocks from the area, and will try to free swap blocks from it. The area will remain in use until all blocks from it are freed. This option can be used only by a privileged user. -m Add all swap resources specified in /etc/fstab ( type field is swap). An entry with the name /dev/swap is ignored, as are all entries with the noauto option present. This option is primarily for the system start up script /etc/init.d/swap which, at boot time, adds all the administrator configured swap resources. This option can be used only by a privileged user. -u Delete all swap resources except the original boot swap resource. This option is primarily for the system shutdown script /etc/init.d/swap which, at system shutdown time, deletes all the configured swap resources. The original boot swap resource may be explicitly deleted using the -d option. This option can be used only by a privileged user. -l List the status of all the swap areas. The output has either seven or nine columns depending on various options. By default, the listing contains nine columns and all values are in 512 byte blocks. The -n option enables a new easier to read output format which defaults to printing the important seven columns (the additional two columns are printed if the -f option is specified). Values with the -n option are printed in either bytes, or with the -b option, in 512-byte blocks. The -f and -b options are only recognized when the new output format is specified. # The logical swap number. This ranges from 1 to 255. This is column is labeled lswap in the default listing format. path The path name for the swap area. dev The major/minor device number in decimal. This is printed in the default list format or in the new format if the -f option is present. If the swap resource is a block special device, this major/minor pair refers to the special device itself. If the swap resource is a regular file, the major/minor number is for the underlying file system that the file resides on. If the stat(2) on path fails, '?,?' is printed. pri The priority of the swap resource. swaplo The swaplow value for the area in 512-byte blocks. This is printed in the default list format or in the new format if the -f option is present. This value is rounded up to a multiple of the system defined swap page size. pswap The swaplen value for the area. This value is rounded down to a multiple of the system defined swap page size. This is column is labeled blocks in the default listing format. free The amount of free swap in the area. maxswap The maximum size the area will be grown to. vswap The size over and above any physical space that the system is assuming it can use (see the discussion of logical swap space below, and the -v option above). There are four status flags that may be printed after the last column. Normally functioning swap resources will not have any status flags. These flags are: INDEL The swap area is being deleted. No allocations will be made from this device. EACCES The swap area was on an NFS mounted file system and 'root' does not have permission to write the file. The swap area is immediately taken off line. ESTALE The swap area was on an NFS mounted file system and the file was removed on the NFS server. The swap area is immediately taken off line. Processes with pages on the swap area will be terminated abnormally the first time they attempt to access any page that had been stored on the swap area. IOERR An I/O error occurred on the device. This could result in the abnormal termination of a process. Look in /var/adm/SYSLOG for more details. Even with I/O errors, the swap area is still allocated from and used until deleted. -s Print information about total logical swap space usage. Values are printed in either bytes, or with the -b option, in 512-byte blocks. allocated The amount of swap space allocated to private pages. reserved The amount of swap space not currently allocated, but claimed by private memory mappings. used The total amount of logical swap space that is either allocated or reserved. available The total logical swap space that is currently available for future reservation and allocation. SWAPPING TO NFS FILES Swapping to regular files on NFS mounted file systems is permitted but should be done only with hard mounted file systems with the intr option turned off (see fstab(4)). When using either soft mounted file systems or the intr option, NFS may return an error during a swap I/O operation. An I/O error that occurs when swapping in a page causes the process requesting the page to be killed, since it's address space is no longer accessible. Since it is possible for the init process to be swapped out to the NFS file, a timeout from a soft mounted file system that occurs while the system is swapping in a page for init will cause init to die. Since the system is unable to run without init, the system will in turn panic. Using hard mounted file systems without the intr flag avoids these problems. Even when using hard mounted NFS file systems, the system may appear to hang if the NFS server fails to respond. If the window manager, shell, or other key process is swapped out to the NFS file and the server fails to respond during swap-in, then the system will wait and retry the NFS file read indefinitely. During this time, programs attempting to swap-in pages from that server will not run and will appear to be hung. Once the NFS server starts responding again, normal system activity will resume. Finally, the system administrator must ensure that the swap file on the NFS server is not deleted. This would cause subsequent swap-ins to fail and again cause the associated processes to be killed. LOGICAL SWAP SPACE Logical swap space is the sum total of physical memory (less space occupied by the kernel) and all swap devices. The system reserves logical swap space for the private portions of a process's virtual address space (data, bss, stack, MAP_PRIVATE mmap mappings, etc.) when virtual address spaces are created (via fork(2)), when they are grown (via brk(2), sbrk(2), or malloc(3C)), or when new segments are attached (via mmap(2), or shmat(2)). Logical swap space is not required for shared text or MAP_SHARED mapped files (except for mappings of the /dev/zero device). If the amount of private virtual space requested exceeds the available logical swap space, the system call fails with EAGAIN and an "out of logical swap space" message is logged on the console. The system does this in order to prevent memory deadlocks from occurring. Note that the system may report being out of swap space when the -l option shown above reports free swap space available. This happens when the logical swap space has been reserved, but physical space has not yet been allocated, so the blocks are still marked as being free. The -s option to the swap command will report the amount of logical swap space reserved and allocated. Programs that have large address spaces and large programs that fork, may receive EAGAIN along with the "out of logical swap space" message on the console. This can also happen when debugging a large program with dbx or other debugger. There are two ways to avoid this error: adding more real swap space, or adding virtual swap space. Adding real swap space means allocating an additional disk partition or a regular file (either local or remote via NFS) to be used as a swap device (using the -a option shown above and the examples below). This is the required approach for programs that use most of the virtual addresses they allocate. The advantage of this approach is that it continues to avoid memory deadlocks, but requires physical disk space to be allocated. The alternative is to add virtual swap space using the -v option. This increases the amount of logical swap space without using any physical disk space. This is suitable when the programs involved do not intend to use the virtual address space they allocate (i.e., when the address space is sparse or when a large program that forks intends to exec soon afterwards without modifying many pages). In these cases, physical swap space is not required and so adding virtual swap space allows the kernel to complete the logical swap space reservation and avoid the EAGAIN errors. The advantage of this approach is that it does not require any disk space, but adds the risk of encountering a memory deadlock. Memory deadlocks occur when the system has over-committed logical swap space by allowing the total private virtual space of the processes on the system to exceed real swap space. When processes attempt to use the allocated virtual space, the kernel has no place to store the data (since virtual swap space has no associated disk space), and a memory deadlock results. In these instances, the kernel kills one or more processes to free up enough logical swap space to break the deadlock. For this reason, virtual swap space should not be used in cases where the program will attempt to use the memory. For example, programs that expect malloc(3C) to return NULL when there is no more memory will in fact be allocated virtual memory that they could not use without causing a memory deadlock. The -v option should therefore be used with care. NOTES The ability to request that a swap resource be automatically grown has not been implemented. EXAMPLES The following swap example requests 10K of swap area (twenty 512-byte blocks) on the device /dev/dsk/dks0d1s1: /sbin/swap -a /dev/dsk/dks0d1s1 0 20 The following adds 50Mb of swap space to the system using a file in the /swap directory: /usr/sbin/mkfile 50m /swap/swap1 /sbin/swap -a /swap/swap1 To make this swap area permanent (automatically added at boot time) add the following line to /etc/fstab: /swap/swap1 swap swap pri=3 0 0 The following example adds the regular file swap1 as a swap resource. Its priority is set to 5, and the system is told that it should add 100 Mbytes (204800 512-byte blocks) to the virtual swap total. The example assumes that swap1 is less than 100 Mbytes in length: /sbin/swap -a -p 5 -v 204800 swap1 The following line in /etc/fstab will add the same swap resource as the previous example, except that it will occur automatically at system startup time: /swap/swap1 swap swap pri=5,vlength=204800 0 0 FILES /etc/fstab swap and/or vswap to add at system boot /etc/config/vswap.options sets default size of virtual swap at boot /etc/init.d/swap adds/removes swap and/or vswap at boot/shutdown SEE ALSO mkfile(1M), mount(1M), swapctl(2), fstab(4). Page 6