usr/src/uts/common/syscall/SYSCALL.README

   1
   2 CDDL HEADER START
   3
   4 The contents of this file are subject to the terms of the
   5 Common Development and Distribution License, Version 1.0 only
   6 (the "License").  You may not use this file except in compliance
   7 with the License.
   8
   9 You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
  10 or http://www.opensolaris.org/os/licensing.
  11 See the License for the specific language governing permissions
  12 and limitations under the License.
  13
  14 When distributing Covered Code, include this CDDL HEADER in each
  15 file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  16 If applicable, add the following below this CDDL HEADER, with the
  17 fields enclosed by brackets "[]" replaced with your own identifying
  18 information: Portions Copyright [yyyy] [name of copyright owner]
  19
  20 CDDL HEADER END
  21
  22 Copyright 2000 Sun Microsystems, Inc.  All rights reserved.
  23 Use is subject to license terms.
  24
  25 ident   "%Z%%M% %I%     %E% SMI"
  26
  27 System Call Files
  28 ------ ---- -----
  29
  30 The universal dumping grounds for system calls in Solaris 2.x,
  31 common/os/scalls.c and common/fs/vncalls.c, have been sub-divided into
  32 smaller files.
  33
  34 The old files had become quite large, and contained much completely
  35 unrelated code. From a software engineering standpoint, it didn't seem
  36 like a good idea to permit system calls or underlying routines
  37 to be cognizant of the internal interfaces and underlying routines
  38 of unrelated system calls.
  39
  40 From a practical standpoint, recompiling all of scalls.c or vncalls.c
  41 after making only a small change in one system call seemed like
  42 cruel and unusual punishment.  Also, running "bringover" after
  43 changing scalls.c or vncalls.c in one's own environment had a
  44 high probability of encountering a conflict.
  45
  46 In an attempt to improve maintainability, we have split these files
  47 and created new directories to hold the results. One hopes that this
  48 new organization will prove easier to maintain and change.
  49
  50 The principles listed below guided the split-up. Please try to adhere
  51 to them if you add new system calls.
  52
  53
  54 1) System calls now live in directories called "syscall". Architecture
  55    independant system calls live in common/syscall and architecture
  56    dependant system calls live in sparc/syscall or i86/syscall.
  57
  58 2) Most system calls have their own separate file. We try to keep
  59    these files as small as possible.
  60
  61 3) Unrelated system calls should NEVER be put in the same file. Do
  62    not consider any of these files "dumping grounds" for new system
  63    call work.
  64
  65 4) Some files DO contain more than one system call. This occurs
  66    under the following restricted conditions:
  67
  68         o System calls that are internally related, either because
  69           they alone call a set of static functions to do the dirty
  70           work, or because they access locally-defined static data.
  71           The system calls in sigqueue.c and lwpsys.c are examples
  72           of the first case; lwp_sobj.c is an example of the second.
  73
  74         o Fairly trivial pairs of "get-" and "set-" operation system
  75           calls. The file rlimit.c, containing getrlimit() and
  76           setrlimit() is a case in point.
  77
  78         o System calls that are basically "variations on a theme,"
  79           such as the the different forms of stat in stat.c.
  80
  81 5) If a number of system calls make use of a local function, or,
  82    if a function is used more widely than in a few system calls,
  83    then perhaps this function needs to be moved to one of the
  84    kernel-implementation files in common/os or common/fs. For
  85    example, this was done with the functions namesetattr and
  86    fdsetattr, which were used by several different system calls.
  87    These functions were moved into common/os/fio.c, where they
  88    seemed to fit better.
  89
  90 -------------------------------------------------------------------
  91 System Call Reorganization
  92 ------ ---- --------------
  93
  94 The system calls in common/os/scalls.c, common/fs/vncalls.c
  95 have been broken up into smaller files. In addition, system
  96 calls that previously resided in <arch>/os/archdep.c have
  97 been removed from that file. The table below describes the
  98 manner in which the files have been split up.
  99
 100 The original syscall files have not been deleted, but have been
 101 renamed to reflect their diminished contents. The file scalls.c
 102 has been renamed to ssig.c, and vncalls.c has been renamed to
 103 poll.c.
 104
 105
 106 Syscall Entry Point     Old File        New File
 107 -------------------     --- ----        --- ----
 108 gtime                   scalls.c        common/syscall/time.c
 109 stime                   scalls.c        common/syscall/time.c
 110
 111 adjtime                 scalls.c        common/syscall/adjtime.c
 112
 113 times                   scalls.c        common/syscall/times.c
 114
 115 sysconfig               scalls.c        common/syscall/sysconfig.c
 116
 117 setuid                  scalls.c        common/syscall/uid.c
 118 getuid                  scalls.c        common/syscall/uid.c
 119 seteuid                 scalls.c        common/syscall/uid.c
 120
 121 setgid                  scalls.c        common/syscall/gid.c
 122 getgid                  scalls.c        common/syscall/gid.c
 123 setegid                 scalls.c        common/syscall/gid.c
 124
 125 getpid                  scalls.c        common/syscall/getpid.c
 126
 127 setgroups               scalls.c        common/syscall/groups.c
 128 getgroups               scalls.c        common/syscall/groups.c
 129
 130 setpgrp                 scalls.c        common/syscall/pgrpsys.c
 131
 132 pause                   scalls.c        common/syscall/pause.c
 133
 134 ssig                    scalls.c        common/syscall/ssig.c
 135
 136 sigtimedwait            scalls.c        common/syscall/sigtimedwait.c
 137
 138 sigsuspend              scalls.c        common/syscall/sigsuspend.c
 139
 140 sigaltstack             scalls.c        common/syscall/sigaltstack.c
 141
 142 sigpending              scalls.c        common/syscall/sigpending.c
 143
 144 sigprocmask             scalls.c        common/syscall/sigprocmask.c
 145
 146 sigaction               scalls.c        common/syscall/sigaction.c
 147
 148 kill                    scalls.c        common/syscall/sigqueue.c
 149 sigqueue                scalls.c        common/syscall/sigqueue.c
 150
 151 sigsendsys              scalls.c        common/syscall/sigsendset.c
 152
 153 profil                  scalls.c        common/syscall/profil.c
 154
 155 alarm                   scalls.c        common/syscall/alarm.c
 156
 157 umask                   scalls.c        common/syscall/umask.c
 158
 159 ulimit                  scalls.c        common/syscall/rlimit.c
 160 getrlimit               scalls.c        common/syscall/rlimit.c
 161 setrlimit               scalls.c        common/syscall/rlimit.c
 162
 163 utssys                  scalls.c        common/syscall/utssys.c
 164
 165 uname                   scalls.c        common/syscall/uname.c
 166
 167 uadmin                  scalls.c        common/syscall/uadmin.c
 168
 169 systeminfo              scalls.c        common/syscall/systeminfo.c
 170
 171 syslwp_create           scalls.c        common/syscall/lwp_create.c
 172 syslwp_exit             scalls.c        common/syscall/lwp_create.c
 173
 174 syslwp_syspend          scalls.c        common/syscall/lwpsys.c
 175 syslwp_continue         scalls.c        common/syscall/lwpsys.c
 176 lwp_kill                scalls.c        common/syscall/lwpsys.c
 177 lwp_wait                scalls.c        common/syscall/lwpsys.c
 178
 179 yield                   scalls.c        common/syscall/yield.c
 180
 181 lwp_self                scalls.c        common/syscall/lwp_self.c
 182
 183 lwp_info                scalls.c        common/syscall/lwp_info.c
 184
 185 lwp_mutex_lock          scalls.c        common/syscall/lwp_sobj.c
 186 lwp_mutex_unlock        scalls.c        common/syscall/lwp_sobj.c
 187 lwp_cond_wait           scalls.c        common/syscall/lwp_sobj.c
 188 lwp_cond_signal         scalls.c        common/syscall/lwp_sobj.c
 189 lwp_cond_broadcast      scalls.c        common/syscall/lwp_sobj.c
 190 lwp_sema_p              scalls.c        common/syscall/lwp_sobj.c
 191 lwp_sema_v              scalls.c        common/syscall/lwp_sobj.c
 192
 193 open                    vncalls.c       common/syscall/open.c
 194 creat                   vncalls.c       common/syscall/open.c
 195
 196 close                   vncalls.c       common/syscall/close.c
 197
 198 read                    vncalls.c       common/syscall/rw.c
 199 write                   vncalls.c       common/syscall/rw.c
 200 pread                   vncalls.c       common/syscall/rw.c
 201 pwrite                  vncalls.c       common/syscall/rw.c
 202 readv                   vncalls.c       common/syscall/rw.c
 203 writev                  vncalls.c       common/syscall/rw.c
 204
 205 chdir                   vncalls.c       common/syscall/chdir.c
 206 fchdir                  vncalls.c       common/syscall/chdir.c
 207 chroot                  vncalls.c       common/syscall/chdir.c
 208 fchroot                 vncalls.c       common/syscall/chdir.c
 209
 210 mknod                   vncalls.c       common/syscall/mknod.c
 211 xmknod                  vncalls.c       common/syscall/mknod.c
 212
 213 mkdir                   vncalls.c       common/syscall/mkdir.c
 214
 215 link                    vncalls.c       common/syscall/link.c
 216
 217 rename                  vncalls.c       common/syscall/rename.c
 218
 219 symlink                 vncalls.c       common/syscall/symlink.c
 220
 221 unlink                  vncalls.c       common/syscall/unlink.c
 222
 223 rmdir                   vncalls.c       common/syscall/rmdir.c
 224
 225 getdents                vncalls.c       common/syscall/getdents.c
 226
 227 lseek                   vncalls.c       common/syscall/lseek.c
 228 llseek                  vncalls.c       common/syscall/lseek.c
 229
 230 access                  vncalls.c       common/syscall/access.c
 231
 232 stat                    vncalls.c       common/syscall/stat.c
 233 lstat                   vncalls.c       common/syscall/stat.c
 234 fstat                   vncalls.c       common/syscall/stat.c
 235 xstat                   vncalls.c       common/syscall/stat.c
 236 lxstat                  vncalls.c       common/syscall/stat.c
 237 fxstat                  vncalls.c       common/syscall/stat.c
 238
 239 fpathconf               vncalls.c       common/syscall/pathconf.c
 240 pathconf                vncalls.c       common/syscall/pathconf.c
 241
 242 readlink                vncalls.c       common/syscall/readlink.c
 243
 244 chmod                   vncalls.c       common/syscall/chmod.c
 245 fchmod                  vncalls.c       common/syscall/chmod.c
 246
 247 chown                   vncalls.c       common/syscall/chown.c
 248 lchown                  vncalls.c       common/syscall/chown.c
 249 fchown                  vncalls.c       common/syscall/chown.c
 250
 251 utime                   vncalls.c       common/syscall/utime.c
 252 utimes                  vncalls.c       common/syscall/utime.c
 253
 254 fdsync                  vncalls.c       common/syscall/fdsync.c
 255
 256 fcntl                   vncalls.c       common/syscall/fcntl.c
 257
 258 dup                     vncalls.c       common/syscall/dup.c
 259
 260 ioctl                   vncalls.c       common/syscall/ioctl.c
 261 stty                    vncalls.c       common/syscall/ioctl.c
 262 gtty                    vncalls.c       common/syscall/ioctl.c
 263
 264 poll                    vncalls.c       common/syscall/poll.c
 265
 266 acl                     vncalls.c       common/syscall/acl.c
 267 facl                    vncalls.c       common/syscall/acl.c
 268
 269 mount                   vfs.c           common/syscall/mount.c
 270
 271 statfs                  vfs.c           common/syscall/statfs.c
 272 fstatfs                 vfs.c           common/syscall/statfs.c
 273
 274 statvfs                 vfs.c           common/syscall/statvfs.c
 275 fstatvfs                vfs.c           common/syscall/statvfs.c
 276
 277 sync                    vfs.c           common/syscall/sync.c
 278
 279 sysfs                   vfs.c           common/syscall/sysfs.c
 280
 281 umount                  vfs.c           common/syscall/umount.c
 282
 283 nice                    priocntl.c      common/syscall/nice.c
 284
 285 pipe                    os/pipe.c       common/syscall/pipe.c
 286
 287 msgsys                  os/msg.c        common/syscall/msg.c
 288
 289 semsys                  os/sem.c        common/syscall/sem.c
 290
 291 shmsys                  os/shm.c        common/syscall/shm.c
 292
 293 getcontext              sparc/archdep.c sparc/syscall/getcontext.c
 294 lwp_getprivate          sparc/archdep.c sparc/syscall/lwp_private.c
 295 lwp_setprivate          sparc/archdep.c sparc/syscall/lwp_private.c
 296
 297 getcontext              i86/archdep.c   i86/syscall/getcontext.c
 298 lwp_getprivate          i86/archdep.c   i86/syscall/lwp_private.c
 299 lwp_setprivate          i86/archdep.c   i86/syscall/lwp_private.c
 300
 301 -----------------------------------------------------------------
 302
 303 Most of the system calls in this directory have been converted
 304 to use C-style argument passing, instead of the old uap-pointer
 305 method. This usually makes the system calls faster and more
 306 "natural" in implementation.