share/man/man2/swapctl.2

   1 '\" te
   2 .\"  Copyright 1989 AT&T  Copyright (c) 1997, Sun Microsystems, Inc.  All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH SWAPCTL 2 "Sep 25, 1997"
   7 .SH NAME
   8 swapctl \- manage swap space
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/stat.h>
  13 #include <sys/swap.h>
  14
  15 \fBint\fR \fBswapctl\fR(\fBint\fR \fIcmd\fR, \fBvoid *\fR\fIarg\fR);
  16 .fi
  17
  18 .SH DESCRIPTION
  19 .sp
  20 .LP
  21 The \fBswapctl()\fR function adds,  deletes, or returns information about swap
  22 resources. \fIcmd\fR specifies one of the following options contained in
  23 <\fBsys/swap.h\fR>:
  24 .sp
  25 .in +2
  26 .nf
  27 SC_ADD        /* add a resource for swapping */
  28 SC_LIST       /* list the resources for swapping */
  29 SC_REMOVE     /* remove a resource for swapping */
  30 SC_GETNSWP    /* return number of swap resources */
  31 .fi
  32 .in -2
  33
  34 .sp
  35 .LP
  36 When \fBSC_ADD\fR or \fBSC_REMOVE\fR is specified, \fIarg\fR is a pointer to a
  37 \fBswapres\fR structure containing the following members:
  38 .sp
  39 .in +2
  40 .nf
  41 char    *sr_name;    /* pathname of resource */
  42 off_t   sr_start;    /* offset to start of swap area */
  43 off_t   sr_length;   /* length of swap area */
  44 .fi
  45 .in -2
  46
  47 .sp
  48 .LP
  49 The \fBsr_start\fR and \fBsr_length\fR members are specified in 512-byte
  50 blocks. A swap resource can only be removed by specifying the same values for
  51 the \fBsr_start\fR and \fBsr_length\fR members as were specified when it was
  52 added. Swap resources need not be removed in the order in which they were
  53 added.
  54 .sp
  55 .LP
  56 When \fBSC_LIST\fR is specified, \fIarg\fR is a pointer to a \fBswaptable\fR
  57 structure containing the following members:
  58 .sp
  59 .in +2
  60 .nf
  61 int             swt_n;       /* number of swapents following */
  62 struct swapent  swt_ent[];   /* array of swt_n swapents */
  63 .fi
  64 .in -2
  65
  66 .sp
  67 .LP
  68 A \fBswapent\fR structure contains the following members:
  69 .sp
  70 .in +2
  71 .nf
  72 char   *ste_path;    /* name of the swap file */
  73 off_t  ste_start;    /* starting block for swapping */
  74 off_t  ste_length;   /* length of swap area */
  75 long   ste_pages;    /* number of pages for swapping */
  76 long   ste_free;     /* number of ste_pages free */
  77 long   ste_flags;    /* ST_INDEL bit set if swap file */
  78                      /* is now being deleted */
  79 .fi
  80 .in -2
  81
  82 .sp
  83 .LP
  84 The \fBSC_LIST\fR function causes \fBswapctl()\fR to return at most \fBswt_n\fR
  85 entries. The return value of \fBswapctl()\fR is the number actually returned.
  86 The \fBST_INDEL\fR bit is turned on in \fBste_flags\fR if the swap file is in
  87 the process of being deleted.
  88 .sp
  89 .LP
  90 When \fBSC_GETNSWP\fR is specified, \fBswapctl()\fR returns as its value the
  91 number of swap resources in use. \fIarg\fR is ignored for this operation.
  92 .sp
  93 .LP
  94 The \fBSC_ADD\fR and \fBSC_REMOVE\fR functions will fail if calling process
  95 does not have appropriate privileges.
  96 .SH RETURN VALUES
  97 .sp
  98 .LP
  99 Upon successful completion, the function \fBswapctl()\fR returns a value of
 100 \fB0\fR for \fBSC_ADD\fR or \fBSC_REMOVE\fR, the number of \fBstruct\fR
 101 \fBswapent\fR entries actually returned  for \fBSC_LIST\fR, or the number of
 102 swap resources in use for \fBSC_GETNSWP\fR. Upon failure, the function
 103 \fBswapctl()\fR returns a value  of \fB\(mi1\fR and sets \fBerrno\fR to
 104 indicate an error.
 105 .SH ERRORS
 106 .sp
 107 .LP
 108 Under the following conditions, the function \fBswapctl()\fR fails and sets
 109 \fBerrno\fR to:
 110 .sp
 111 .ne 2
 112 .na
 113 \fB\fBEEXIST\fR\fR
 114 .ad
 115 .RS 16n
 116 Part of the range specified by \fBsr_start\fR and \fBsr_length\fR is already
 117 being used for swapping on the specified resource (\fBSC_ADD\fR).
 118 .RE
 119
 120 .sp
 121 .ne 2
 122 .na
 123 \fB\fBEFAULT\fR\fR
 124 .ad
 125 .RS 16n
 126 Either \fIarg\fR, \fBsr_name\fR, or \fBste_path\fR points to an illegal
 127 address.
 128 .RE
 129
 130 .sp
 131 .ne 2
 132 .na
 133 \fB\fBEINVAL\fR\fR
 134 .ad
 135 .RS 16n
 136 The specified function value is not valid, the path specified is not a swap
 137 resource (\fBSC_REMOVE\fR), part of the range specified by \fBsr_start\fR and
 138 \fBsr_length\fR lies outside the resource specified (\fBSC_ADD\fR), or the
 139 specified swap area is less than one page (\fBSC_ADD\fR).
 140 .RE
 141
 142 .sp
 143 .ne 2
 144 .na
 145 \fB\fBEISDIR\fR\fR
 146 .ad
 147 .RS 16n
 148 The path specified for \fBSC_ADD\fR is a directory.
 149 .RE
 150
 151 .sp
 152 .ne 2
 153 .na
 154 \fB\fBELOOP\fR\fR
 155 .ad
 156 .RS 16n
 157 Too many symbolic links were encountered in translating the pathname provided
 158 to \fBSC_ADD\fR or \fBSC_REMOVE\fR.
 159 .RE
 160
 161 .sp
 162 .ne 2
 163 .na
 164 \fB\fBENAMETOOLONG\fR\fR
 165 .ad
 166 .RS 16n
 167 The length of a component of the path specified for \fBSC_ADD\fR or
 168 \fBSC_REMOVE\fR exceeds \fBNAME_MAX\fR characters or the length of the path
 169 exceeds \fBPATH_MAX\fR characters and \fB_POSIX_NO_TRUNC\fR is in effect.
 170 .RE
 171
 172 .sp
 173 .ne 2
 174 .na
 175 \fB\fBENOENT\fR\fR
 176 .ad
 177 .RS 16n
 178 The pathname specified for \fBSC_ADD\fR or \fBSC_REMOVE\fR does not exist.
 179 .RE
 180
 181 .sp
 182 .ne 2
 183 .na
 184 \fB\fBENOMEM\fR\fR
 185 .ad
 186 .RS 16n
 187 An insufficient number of \fBstruct\fR \fBswapent\fR structures were provided
 188 to \fBSC_LIST\fR, or there were insufficient system storage resources available
 189 during an \fBSC_ADD\fR or \fBSC_REMOVE\fR, or the system would not have enough
 190 swap space after an \fBSC_REMOVE\fR.
 191 .RE
 192
 193 .sp
 194 .ne 2
 195 .na
 196 \fB\fBENOSYS\fR\fR
 197 .ad
 198 .RS 16n
 199 The pathname specified for \fBSC_ADD\fR or \fBSC_REMOVE\fR is not a file or
 200 block special device.
 201 .RE
 202
 203 .sp
 204 .ne 2
 205 .na
 206 \fB\fBENOTDIR\fR\fR
 207 .ad
 208 .RS 16n
 209 Pathname provided to \fBSC_ADD\fR or \fBSC_REMOVE\fR contained a component in
 210 the path prefix that was not a directory.
 211 .RE
 212
 213 .sp
 214 .ne 2
 215 .na
 216 \fB\fBEPERM\fR\fR
 217 .ad
 218 .RS 16n
 219 The {\fBPRIV_SYS_MOUNT\fR} was not asserted in the effective set of the calling
 220 process.
 221 .RE
 222
 223 .sp
 224 .ne 2
 225 .na
 226 \fB\fBEROFS\fR\fR
 227 .ad
 228 .RS 16n
 229 The pathname specified for \fBSC_ADD\fR is a read-only file system.
 230 .RE
 231
 232 .sp
 233 .LP
 234 Additionally, the \fBswapctl()\fR function will fail for 32-bit interfaces if:
 235 .sp
 236 .ne 2
 237 .na
 238 \fB\fBEOVERFLOW\fR\fR
 239 .ad
 240 .RS 13n
 241 The amount of swap space configured on the machine is too large to be
 242 represented by a 32-bit quantity.
 243 .RE
 244
 245 .SH EXAMPLES
 246 .LP
 247 \fBExample 1 \fRThe usage of the \fBSC_GETNSWP\fR and \fBSC_LIST\fR commands.
 248 .sp
 249 .LP
 250 The following example demonstrates the usage of the \fBSC_GETNSWP\fR and
 251 \fBSC_LIST\fR commands.
 252
 253 .sp
 254 .in +2
 255 .nf
 256 #include <sys/stat.h>
 257 #include <sys/swap.h>
 258 #include <stdio.h>
 259
 260 #define MAXSTRSIZE 80
 261
 262 main(argc, argv)
 263     int            argc;
 264     char           *argv[];
 265 {
 266     swaptbl_t      *s;
 267     int            i, n, num;
 268     char           *strtab;    /* string table for path names */
 269
 270 again:
 271     if ((num = swapctl(SC_GETNSWP, 0)) == -1) {
 272         perror("swapctl: GETNSWP");
 273         exit(1);
 274     }
 275     if (num == 0) {
 276         fprintf(stderr, "No Swap Devices Configured\en");
 277         exit(2);
 278     }
 279     /* allocate swaptable for num+1 entries */
 280     if ((s = malloc(num * sizeof(swapent_t) +
 281             sizeof(struct swaptable))) == NULL) {
 282         fprintf(stderr, "Malloc Failed\en");
 283         exit(3);
 284     }
 285     /* allocate num+1 string holders */
 286     if ((strtab = malloc((num + 1) * MAXSTRSIZE)) == NULL) {
 287         fprintf(stderr, "Malloc Failed\en");
 288         exit(3);
 289     }
 290     /* initialize string pointers */
 291     for (i = 0; i < (num + 1); i++) {
 292         s->swt_ent[i].ste_path = strtab + (i * MAXSTRSIZE);
 293     }
 294
 295     s->swt_n = num + 1;
 296     if ((n = swapctl(SC_LIST, s)) < 0) {
 297         perror("swapctl");
 298         exit(1);
 299     }
 300     if (n > num) {        /* more were added */
 301         free(s);
 302         free(strtab);
 303         goto again;
 304     }
 305     for (i = 0; i < n; i++)
 306         printf("%s %ld\en",
 307             s->swt_ent[i].ste_path, s->swt_ent[i].ste_pages);
 308 }
 309 .fi
 310 .in -2
 311
 312 .SH SEE ALSO
 313 .sp
 314 .LP
 315 \fBprivileges\fR(5)