swapctl(2) swapctl(2) NAME swapctl - manage swap space SYNOPSIS #include <sys/stat.h> #include <sys/swap.h> int swapctl(int cmd, void *arg); DESCRIPTION swapctl adds, deletes, or returns information about swap resources. Swap resources can be local disk partitions (block devices), local file system files, and files on file systems mounted via nfs. cmd specifies one of the following options contained in <sys/swap.h>: SC_ADD /* add a resource for swapping */ SC_LIST /* list the resources for swapping */ SC_REMOVE /* remove a resource for swapping */ SC_GETNSWP /* return number of swap resources */ SC_SGIADD /* add a resource for swapping */ SC_LREMOVE /* remove a resource for swapping */ SC_GETFREESWAP /* get amount of free swap */ SC_GETSWAPMAX /* get maximum amount of physical swap */ SC_GETSWAPVIRT /* get amount of virtual swap */ SC_GETRESVSWAP /* get amount of reserved logical swap */ SC_GETSWAPTOT /* get current amount of physical swap */ SC_GETLSWAPTOT /* get amount of logical swap */ When SC_SGIADD is specified, arg is a pointer to a xswapres structure containing the following members: char *sr_name; /* pathname of resource */ off_t sr_start; /* offset to start of swap area */ off_t sr_length; /* length of swap area */ off_t sr_maxlength;/* max length */ off_t sr_vlength; /* virtual length */ signed char sr_pri; /* priority */ sr_start, sr_maxlength, sr_vlength, and sr_length are specified in 512- byte blocks. sr_length specifies the number of blocks of the specified resource that should be used for new swap area. It must be less than or equal to the size of the resource (e.g. file size or partition size). If a -1 is specified, sr_length, sr_maxlength, and sr_vlength are all set to the size of the resource. sr_maxlength specifies the number of blocks the specified resource should, if required, be grown to. This option is currently unsupported, and sr_maxlength should always be set equal to sr_length. sr_vlength specifies the number of blocks the system should assume the new swap area can handle. Normally, this should be equal to sr_length - meaning that the system will never over commit its memory resources. If sr_vlength is set larger than sr_length, then the system believes that it has more swap space than it really does. As long as no process actually requires that space, there is no problem. This permits very large applications that wish to fork(2) but have no intention of creating two large processes, to do so without requiring a lot of swap space that is really not needed. It also permits applications that have sparse data to effectively run on machines with small swap spaces. Because the system can in fact over commit its memory resources, deadlocks can result where there is no more memory and no more swap space. These deadlocks are detected by the system and an appropriate process is killed that will permit the system to continue operating. sr_pri set the priority of the new swap area. Swap areas with a higher priority are allocated from first. If sr_pri is set to -1 the system will assign the priority based on the type of swap resource. Highest priority (0) is the default for block devices. Priority 2 for local file system files, and priority 4 for nfs mounted files. The sr_start value will be rounded up to the next multiple of the system swap page size (4096 bytes or 16384 depending on the return value of the getpagesize(2) system call). The sr_length, sr_vlength, and sr_maxlength values will be rounded down to the next multiple of the system swap page size. When SC_ADD or SC_REMOVE is specified, arg is a pointer to a swapres structure containing the following members: char *sr_name; /* pathname of resource */ off_t sr_start; /* offset to start of swap area */ off_t sr_length; /* length of swap area */ sr_start and sr_length are specified in 512-byte blocks. When SC_LIST is specified, arg is a pointer to a swaptable structure containing the following members: int swt_n; /* number of swapents following */ struct swapent swt_ent[];/* array of swt_n swapents */ A swapent structure contains the following members: char *ste_path; /* name of the swap file */ off_t ste_start; /* starting block for swapping */ off_t ste_length; /* length of swap area */ long ste_pages; /* number of pages for swapping */ long ste_free; /* number of ste_pages free */ long ste_flags; /* ST_INDEL bit set if swap file */ /* is now being deleted */ long ste_vpages; /* virtual pages for swap */ long ste_maxpages;/* max pages swap can grow to */ short ste_lswap; /* logical swap # */ signed char ste_pri; /* swap resource priority */ SC_LIST causes swapctl to return at most swt_n entries. The return value of swapctl is the number actually returned. The ST_INDEL bit is turned on in ste_flags if the swap file is in the process of being deleted. The ST_STALE bit is turned on in ste_flags if the swap file is on an NFS mounted file system, and the file on the server was removed. No further allocations will be made from a swap resource that has this bit set. The ST_LOCAL bit is turned on in ste_flags if the swap resource resides on a local disk. The ST_IOERR bit is turned on in ste_flags if any errors have occurred when reading or writing the swap resource. Allocations will still be satisfied from swap resources with this bit set. The ST_EACCES bit is turned on in ste_flags if a permission error occurs when attempting to write to the swap resource. This occurs most often when user id 0 does not have the appropriate privileges on an NFS mounted file system. No further allocations will be made from a swap resource that has this bit set. The ST_BOOTSWAP bit is turned on in ste_flags if this swap device was the initial swap device configured at boot time. When SC_GETNSWP is specified, swapctl returns as its value the number of swap resources in use. arg is ignored for this operation. SC_LREMOVE causes swapctl removes the logical swap resource specified by arg. When SC_GETFREESWAP is specified, swapctl copies the number of currently free swap blocks (512 bytes) to the address given by arg. This is the sum of each swap area's ste_free value, converted to 512 byte blocks. When SC_GETSWAPVIRT is specified, swapctl copies the total number of virtual swap blocks (512 bytes) to the address given by arg. This is the sum of each swap area's ste_vpages value, converted to 512 byte blocks. When SC_GETRESVSWAP is specified, swapctl copies the number of logical swap blocks (512 bytes) that have been reserved by all existing processes to the address given by arg. When this value is greater than the value returned by SC_GETLSWAPTOT minus the value returned by SC_SWAPMAX, there is the potential for deadlock if every process suddenly requires all that it has reserved. When SC_GETLSWAPTOT is specified, swapctl copies the current number of logical swap blocks (512 bytes) to the address given by arg. This is value is the sum of the amount of physical memory potentially available for processes plus the number of virtual swap blocks plus the number of physical swap blocks. When SC_GETSWAPTOT is specified, swapctl copies the current number of physical swap blocks (512 bytes) to the address given by arg. This is the sum of each swap area's ste_pages value, converted to 512 byte blocks. When SC_GETSWAPMAX is specified, swapctl copies the maximum number of swap blocks (512 bytes) to the address given by arg. This is the sum of each swap area's ste_maxpages value, converted to 512 byte blocks. Since growable swap areas is not yet supported this value will always be the same as that returned by SC_GETSWAPTOT. When specifying SC_GETFREESWAP, SC_GETSWAPVIRT, SC_GETRESVSWAP, SC_GETLSWAPTOT, SC_GETSWAPTOT, or SC_GETSWAPMAX, arg should be a pointer to a variable of type off_t. The SC_SGIADD, SC_ADD, and SC_REMOVE functions will fail if the calling process does not have appropriate privilege. RETURN VALUE Upon successful completion, the function swapctl returns a value of 0 for SC_ADD, SC_SGIADD, SC_GETRESVSWAP, SC_GETSWAPMAX, SC_GETSWAPVIRT, SC_GETFREESWAP, SC_GETSWAPTOT, SC_GETLSWAPTOT, or SC_REMOVE, the number of struct swapent entries actually returned for SC_LIST, or the number of swap resources in use for SC_GETNSWP. Upon failure, the function swapctl returns a value of -1 and sets errno to indicate an error. ERRORS Under the following conditions, the function swapctl fails and sets errno to: EEXIST Part of the range specified by sr_start and sr_length is already being used for swapping on the specified resource (SC_ADD or SC_SGIADD). EFAULT arg, sr_name, or ste_path points outside the allocated address space. EINVAL sr_length is not -1 and either sr_maxlength is not equal to sr_length, or sr_vlength is less than either sr_length or sr_maxlength. ENXIO The pathname specified for SC_ADD or SC_SGIADD specifies a non-configured block device or the block device does not have a size routine. EINVAL sr_pri is not equal to -1 and it greater than 7. ENOSPC There are no more logical swap devices available (maximum 255) (SC_ADD or SC_SGIADD). EBUSY The in-use pages for the swap area to be deleted cannot at this time be reclaimed (SC_REMOVE or SC_LREMOVE). EBUSY The specified resource is already in use as a swap area (SC_ADD or SC_SGIADD). EINVAL The specified function value is not valid, the path specified is not a swap resource (SC_REMOVE), part of the range specified by sr_start and sr_length lies outside the resource specified (SC_ADD or SC_SGIADD), or the specified swap area is less than one page (SC_ADD or SC_SGIADD). EISDIR The path specified for SC_ADD or SC_SGIADD is a directory. ELOOP Too many symbolic links were encountered in translating the pathname provided to SC_ADD, SC_SGIADD, or SC_REMOVE . ENAMETOOLONGThe length of a component of the path specified for SC_ADD, SC_SGIADD, or SC_REMOVE exceeds {NAME_MAX} characters or the length of the path exceeds {PATH_MAX} characters and {_POSIX_NO_TRUNC} is in effect. ENOENT The pathname specified for SC_ADD, SC_SGIADD, or SC_REMOVE does not exist. ENOMEM An insufficient number of struct swapent structures were provided to SC_LIST, or there were insufficient system storage resources available during an SC_ADD, SC_SGIADD, or SC_REMOVE, or the system would not have enough swap space after an SC_REMOVE. ENOSYS The pathname specified for SC_ADD, SC_SGIADD, or SC_REMOVE is not a file or block special device. The file system on which pathname resides does not permit mapping or swapping. ENOTDIR Pathname provided to SC_ADD, SC_SGIADD, or SC_REMOVE contained a component in the path prefix that was not a directory. EPERM The process does not have appropriate privilege. EROFS The pathname specified for SC_ADD or SC_SGIADD is a read-only file system. Page 5