swapctl - manage swap space


     #include <sys/stat.h>
     #include <sys/swap.h>

     int swapctl(int cmd, void *arg);


     The swapctl() function adds,  deletes, or  returns  informa-
     tion  about swap resources. cmd specifies one of the follow-
     ing 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 */

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

     The sr_start and sr_length members are specified in 512-byte
     blocks.  A  swap  resource can only be removed by specifying
     the same values for the sr_start and  sr_length  members  as
     were specified when it was added. Swap resources need not be
     removed in the order in which they were added.

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

     The SC_LIST function 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

     When SC_GETNSWP is specified, swapctl() returns as its value
     the number of swap resources in use. arg is ignored for this

     The SC_ADD and SC_REMOVE functions will fail if calling pro-
     cess does not have appropriate privileges.


     Upon successful completion, the function swapctl() returns a
     value  of  0  for  SC_ADD 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.


     Under the following conditions, the function swapctl() fails
     and sets errno to:

           Part of the range specified by sr_start and  sr_length
           is  already  being  used for swapping on the specified
           resource (SC_ADD).

           Either arg, sr_name, or ste_path points to an  illegal

           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 the speci-
           fied swap area is less than one page (SC_ADD).

           The path specified for SC_ADD is a directory.

     ELOOP Too many symbolic links were encountered in  translat-
           ing the pathname provided to SC_ADD or SC_REMOVE.

           The length of a component of the  path  specified  for
           SC_ADD or SC_REMOVE exceeds NAME_MAX characters or the
           length of the path  exceeds  PATH_MAX  characters  and
           _POSIX_NO_TRUNC is in effect.

           The pathname specified for SC_ADD  or  SC_REMOVE  does
           not exist.

           An insufficient number of  struct  swapent  structures
           were  provided  to SC_LIST, or there were insufficient
           system storage resources available during an SC_ADD or
           SC_REMOVE,  or  the  system would not have enough swap
           space after an SC_REMOVE.

           The pathname specified for SC_ADD or SC_REMOVE is  not
           a file or block special device.

           Pathname provided to SC_ADD or SC_REMOVE  contained  a
           component in the path prefix that was not a directory.

     EPERM The effective user  of  the  calling  process  is  not

     EROFS The pathname specified for SC_ADD is a read-only  file

     Additionally, the swapctl() function will  fail  for  32-bit
     interfaces if:

           The amount of swap space configured on the machine  is
           too large to be represented by a 32-bit quantity.


     Example 1: The usage of the SC_GETNSWP and SC_LIST commands.

     The  following  example  demonstrates  the  usage   of   the
     SC_GETNSWP and SC_LIST commands.

     #include <sys/stat.h>
     #include <sys/swap.h>
     #include <stdio.h>

     #define MAXSTRSIZE 80

     main(argc, argv)
         int            argc;
         char           *argv[];
         swaptbl_t      *s;
         int            i, n, num;
         char           *strtab;    /* string table for path names */

         if ((num = swapctl(SC_GETNSWP, 0)) == -1) {
             perror("swapctl: GETNSWP");
         if (num == 0) {
             fprintf(stderr, "No Swap Devices Configured\n");
         /* allocate swaptable for num+1 entries */
         if ((s = (swaptbl_t *)
             malloc(num * sizeof(swapent_t) +
                 sizeof(struct swaptable))) ==
             (void *) 0) {
             fprintf(stderr, "Malloc Failed\n");
         /* allocate num+1 string holders */
         if ((strtab = (char *)
             malloc((num + 1) * MAXSTRSIZE)) == (void *) 0) {
             fprintf(stderr, "Malloc Failed\n");
         /* initialize string pointers */
         for (i = 0; i < (num + 1); i++) {
             s->swt_ent[i].ste_path = strtab + (i * MAXSTRSIZE);

         s->swt_n = num + 1;
         if ((n = swapctl(SC_LIST, s)) < 0) {
         if (n > num) {        /* more were added */
             goto again;
         for (i = 0; i < n; i++)
             printf("%s %ld\n",
                 s->swt_ent[i].ste_path, s->swt_ent[i].ste_pages);

Man(1) output converted with man2html