Documentation: syscall
1 #!/usr/bin/env bash
2 # Copyright 2009 The Go Authors. All rights reserved.
3 # Use of this source code is governed by a BSD-style
4 # license that can be found in the LICENSE file.
5
6 # The syscall package provides access to the raw system call
7 # interface of the underlying operating system. Porting Go to
8 # a new architecture/operating system combination requires
9 # some manual effort, though there are tools that automate
10 # much of the process. The auto-generated files have names
11 # beginning with z.
12 #
13 # This script runs or (given -n) prints suggested commands to generate z files
14 # for the current system. Running those commands is not automatic.
15 # This script is documentation more than anything else.
16 #
17 # * asm_${GOOS}_${GOARCH}.s
18 #
19 # This hand-written assembly file implements system call dispatch.
20 # There are three entry points:
21 #
22 # func Syscall(trap, a1, a2, a3 uintptr) (r1, r2, err uintptr);
23 # func Syscall6(trap, a1, a2, a3, a4, a5, a6 uintptr) (r1, r2, err uintptr);
24 # func RawSyscall(trap, a1, a2, a3 uintptr) (r1, r2, err uintptr);
25 #
26 # The first and second are the standard ones; they differ only in
27 # how many arguments can be passed to the kernel.
28 # The third is for low-level use by the ForkExec wrapper;
29 # unlike the first two, it does not call into the scheduler to
30 # let it know that a system call is running.
31 #
32 # * syscall_${GOOS}.go
33 #
34 # This hand-written Go file implements system calls that need
35 # special handling and lists "//sys" comments giving prototypes
36 # for ones that can be auto-generated. Mksyscall reads those
37 # comments to generate the stubs.
38 #
39 # * syscall_${GOOS}_${GOARCH}.go
40 #
41 # Same as syscall_${GOOS}.go except that it contains code specific
42 # to ${GOOS} on one particular architecture.
43 #
44 # * types_${GOOS}.c
45 #
46 # This hand-written C file includes standard C headers and then
47 # creates typedef or enum names beginning with a dollar sign
48 # (use of $ in variable names is a gcc extension). The hardest
49 # part about preparing this file is figuring out which headers to
50 # include and which symbols need to be #defined to get the
51 # actual data structures that pass through to the kernel system calls.
52 # Some C libraries present alternate versions for binary compatibility
53 # and translate them on the way in and out of system calls, but
54 # there is almost always a #define that can get the real ones.
55 # See types_darwin.c and types_linux.c for examples.
56 #
57 # * zerror_${GOOS}_${GOARCH}.go
58 #
59 # This machine-generated file defines the system's error numbers,
60 # error strings, and signal numbers. The generator is "mkerrors.sh".
61 # Usually no arguments are needed, but mkerrors.sh will pass its
62 # arguments on to godefs.
63 #
64 # * zsyscall_${GOOS}_${GOARCH}.go
65 #
66 # Generated by mksyscall.pl; see syscall_${GOOS}.go above.
67 #
68 # * zsysnum_${GOOS}_${GOARCH}.go
69 #
70 # Generated by mksysnum_${GOOS}.
71 #
72 # * ztypes_${GOOS}_${GOARCH}.go
73 #
74 # Generated by godefs; see types_${GOOS}.c above.
75
76 GOOSARCH="${GOOS}_${GOARCH}"
77
78 # defaults
79 mksyscall="./mksyscall.pl"
80 mkerrors="./mkerrors.sh"
81 zerrors="zerrors_$GOOSARCH.go"
82 mksysctl=""
83 zsysctl="zsysctl_$GOOSARCH.go"
84 mksysnum=
85 mktypes=
86 mkasm=
87 run="sh"
88
89 case "$1" in
90 -syscalls)
91 for i in zsyscall*go
92 do
93 # Run the command line that appears in the first line
94 # of the generated file to regenerate it.
95 sed 1q $i | sed 's;^// ;;' | sh > _$i && gofmt < _$i > $i
96 rm _$i
97 done
98 exit 0
99 ;;
100 -n)
101 run="cat"
102 shift
103 esac
104
105 case "$#" in
106 0)
107 ;;
108 *)
109 echo 'usage: mkall.sh [-n]' 1>&2
110 exit 2
111 esac
112
113 GOOSARCH_in=syscall_$GOOSARCH.go
114 case "$GOOSARCH" in
115 _* | *_ | _)
116 echo 'undefined $GOOS_$GOARCH:' "$GOOSARCH" 1>&2
117 exit 1
118 ;;
119 aix_ppc64)
120 mkerrors="$mkerrors -maix64"
121 mksyscall="./mksyscall_libc.pl -aix"
122 mktypes="GOARCH=$GOARCH go tool cgo -godefs"
123 ;;
124 darwin_amd64)
125 mkerrors="$mkerrors -m64"
126 mksyscall="./mksyscall.pl -darwin"
127 mktypes="GOARCH=$GOARCH go tool cgo -godefs"
128 mkasm="go run mkasm.go"
129 ;;
130 darwin_arm64)
131 mkerrors="$mkerrors -m64"
132 mksyscall="./mksyscall.pl -darwin"
133 mktypes="GOARCH=$GOARCH go tool cgo -godefs"
134 mkasm="go run mkasm.go"
135 ;;
136 dragonfly_amd64)
137 mkerrors="$mkerrors -m64"
138 mksyscall="./mksyscall.pl -dragonfly"
139 mksysnum="curl -s 'http://gitweb.dragonflybsd.org/dragonfly.git/blob_plain/HEAD:/sys/kern/syscalls.master' | ./mksysnum_dragonfly.pl"
140 mktypes="GOARCH=$GOARCH go tool cgo -godefs"
141 ;;
142 freebsd_386)
143 mkerrors="$mkerrors -m32"
144 mksyscall="./mksyscall.pl -l32"
145 mksysnum="curl -s 'http://svn.freebsd.org/base/stable/10/sys/kern/syscalls.master' | ./mksysnum_freebsd.pl"
146 mktypes="GOARCH=$GOARCH go tool cgo -godefs"
147 ;;
148 freebsd_amd64)
149 mkerrors="$mkerrors -m64"
150 mksysnum="curl -s 'http://svn.freebsd.org/base/stable/10/sys/kern/syscalls.master' | ./mksysnum_freebsd.pl"
151 mktypes="GOARCH=$GOARCH go tool cgo -godefs"
152 ;;
153 freebsd_arm)
154 mkerrors="$mkerrors"
155 mksyscall="./mksyscall.pl -l32 -arm"
156 mksysnum="curl -s 'http://svn.freebsd.org/base/stable/10/sys/kern/syscalls.master' | ./mksysnum_freebsd.pl"
157 # Let the type of C char be signed to make the bare syscall
158 # API consistent between platforms.
159 mktypes="GOARCH=$GOARCH go tool cgo -godefs -- -fsigned-char"
160 ;;
161 freebsd_arm64)
162 mkerrors="$mkerrors"
163 mksysnum="curl -s 'http://svn.freebsd.org/base/stable/10/sys/kern/syscalls.master' | ./mksysnum_freebsd.pl"
164 # Let the type of C char be signed to make the bare syscall
165 # API consistent between platforms.
166 mktypes="GOARCH=$GOARCH go tool cgo -godefs -- -fsigned-char"
167 ;;
168 linux_386)
169 mkerrors="$mkerrors -m32"
170 mksyscall="./mksyscall.pl -l32"
171 mksysnum="./mksysnum_linux.pl /usr/include/asm/unistd_32.h"
172 mktypes="GOARCH=$GOARCH go tool cgo -godefs"
173 ;;
174 linux_amd64)
175 unistd_h=$(ls -1 /usr/include/asm/unistd_64.h /usr/include/x86_64-linux-gnu/asm/unistd_64.h 2>/dev/null | head -1)
176 if [ "$unistd_h" = "" ]; then
177 echo >&2 cannot find unistd_64.h
178 exit 1
179 fi
180 mkerrors="$mkerrors -m64"
181 mksysnum="./mksysnum_linux.pl $unistd_h"
182 mktypes="GOARCH=$GOARCH go tool cgo -godefs"
183 ;;
184 linux_arm)
185 mkerrors="$mkerrors"
186 mksyscall="./mksyscall.pl -l32 -arm"
187 mksysnum="curl -s 'http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/plain/arch/arm/include/uapi/asm/unistd.h' | ./mksysnum_linux.pl -"
188 mktypes="GOARCH=$GOARCH go tool cgo -godefs"
189 ;;
190 linux_arm64)
191 unistd_h=$(ls -1 /usr/include/asm/unistd.h /usr/include/asm-generic/unistd.h 2>/dev/null | head -1)
192 if [ "$unistd_h" = "" ]; then
193 echo >&2 cannot find unistd_64.h
194 exit 1
195 fi
196 mksysnum="./mksysnum_linux.pl $unistd_h"
197 # Let the type of C char be signed to make the bare syscall
198 # API consistent between platforms.
199 mktypes="GOARCH=$GOARCH go tool cgo -godefs -- -fsigned-char"
200 ;;
201 linux_mips)
202 GOOSARCH_in=syscall_linux_mipsx.go
203 unistd_h=/usr/include/asm/unistd.h
204 mksyscall="./mksyscall.pl -b32 -arm"
205 mkerrors="$mkerrors"
206 mksysnum="./mksysnum_linux.pl $unistd_h"
207 mktypes="GOARCH=$GOARCH go tool cgo -godefs"
208 ;;
209 linux_mipsle)
210 GOOSARCH_in=syscall_linux_mipsx.go
211 unistd_h=/usr/include/asm/unistd.h
212 mksyscall="./mksyscall.pl -l32 -arm"
213 mkerrors="$mkerrors"
214 mksysnum="./mksysnum_linux.pl $unistd_h"
215 mktypes="GOARCH=$GOARCH go tool cgo -godefs"
216 ;;
217 linux_mips64)
218 GOOSARCH_in=syscall_linux_mips64x.go
219 unistd_h=/usr/include/asm/unistd.h
220 mkerrors="$mkerrors -m64"
221 mksysnum="./mksysnum_linux.pl $unistd_h"
222 mktypes="GOARCH=$GOARCH go tool cgo -godefs"
223 ;;
224 linux_mips64le)
225 GOOSARCH_in=syscall_linux_mips64x.go
226 unistd_h=/usr/include/asm/unistd.h
227 mkerrors="$mkerrors -m64"
228 mksysnum="./mksysnum_linux.pl $unistd_h"
229 mktypes="GOARCH=$GOARCH go tool cgo -godefs"
230 ;;
231 linux_ppc64)
232 GOOSARCH_in=syscall_linux_ppc64x.go
233 unistd_h=/usr/include/asm/unistd.h
234 mkerrors="$mkerrors -m64"
235 mksysnum="./mksysnum_linux.pl $unistd_h"
236 mktypes="GOARCH=$GOARCH go tool cgo -godefs"
237 ;;
238 linux_ppc64le)
239 GOOSARCH_in=syscall_linux_ppc64x.go
240 unistd_h=/usr/include/powerpc64le-linux-gnu/asm/unistd.h
241 mkerrors="$mkerrors -m64"
242 mksysnum="./mksysnum_linux.pl $unistd_h"
243 mktypes="GOARCH=$GOARCH go tool cgo -godefs"
244 ;;
245 linux_riscv64)
246 unistd_h=$(ls -1 /usr/include/asm/unistd.h /usr/include/asm-generic/unistd.h 2>/dev/null | head -1)
247 if [ "$unistd_h" = "" ]; then
248 echo >&2 cannot find unistd_64.h
249 exit 1
250 fi
251 mksysnum="./mksysnum_linux.pl $unistd_h"
252 mktypes="GOARCH=$GOARCH go tool cgo -godefs"
253 ;;
254 linux_s390x)
255 GOOSARCH_in=syscall_linux_s390x.go
256 unistd_h=/usr/include/asm/unistd.h
257 mkerrors="$mkerrors -m64"
258 mksysnum="./mksysnum_linux.pl $unistd_h"
259 mktypes="GOARCH=$GOARCH go tool cgo -godefs"
260 ;;
261 netbsd_386)
262 mkerrors="$mkerrors -m32"
263 mksyscall="./mksyscall.pl -l32 -netbsd"
264 mksysnum="curl -s 'http://cvsweb.netbsd.org/bsdweb.cgi/~checkout~/src/sys/kern/syscalls.master' | ./mksysnum_netbsd.pl"
265 mktypes="GOARCH=$GOARCH go tool cgo -godefs"
266 ;;
267 netbsd_amd64)
268 mkerrors="$mkerrors -m64"
269 mksyscall="./mksyscall.pl -netbsd"
270 mksysnum="curl -s 'http://cvsweb.netbsd.org/bsdweb.cgi/~checkout~/src/sys/kern/syscalls.master' | ./mksysnum_netbsd.pl"
271 mktypes="GOARCH=$GOARCH go tool cgo -godefs"
272 ;;
273 netbsd_arm)
274 mkerrors="$mkerrors -m32"
275 mksyscall="./mksyscall.pl -l32 -netbsd -arm"
276 mksysnum="curl -s 'http://cvsweb.netbsd.org/bsdweb.cgi/~checkout~/src/sys/kern/syscalls.master' | ./mksysnum_netbsd.pl"
277 mktypes="GOARCH=$GOARCH go tool cgo -godefs"
278 ;;
279 netbsd_arm64)
280 mkerrors="$mkerrors -m64"
281 mksyscall="./mksyscall.pl -netbsd"
282 mksysnum="curl -s 'http://cvsweb.netbsd.org/bsdweb.cgi/~checkout~/src/sys/kern/syscalls.master' | ./mksysnum_netbsd.pl"
283 mktypes="GOARCH=$GOARCH go tool cgo -godefs"
284 ;;
285 openbsd_386)
286 GOOSARCH_in="syscall_openbsd1.go syscall_openbsd_$GOARCH.go"
287 mkerrors="$mkerrors -m32"
288 mksyscall="./mksyscall.pl -l32 -openbsd -libc"
289 mksysctl="./mksysctl_openbsd.pl"
290 zsysctl="zsysctl_openbsd.go"
291 mksysnum="curl -s 'http://cvsweb.openbsd.org/cgi-bin/cvsweb/~checkout~/src/sys/kern/syscalls.master' | ./mksysnum_openbsd.pl"
292 mktypes="GOARCH=$GOARCH go tool cgo -godefs"
293 mkasm="go run mkasm.go"
294 ;;
295 openbsd_amd64)
296 GOOSARCH_in="syscall_openbsd_libc.go syscall_openbsd_$GOARCH.go"
297 mkerrors="$mkerrors -m64"
298 mksyscall="./mksyscall.pl -openbsd -libc"
299 mksysctl="./mksysctl_openbsd.pl"
300 zsysctl="zsysctl_openbsd.go"
301 mksysnum="curl -s 'http://cvsweb.openbsd.org/cgi-bin/cvsweb/~checkout~/src/sys/kern/syscalls.master' | ./mksysnum_openbsd.pl"
302 mktypes="GOARCH=$GOARCH go tool cgo -godefs"
303 mkasm="go run mkasm.go"
304 ;;
305 openbsd_arm)
306 GOOSARCH_in="syscall_openbsd_libc.go syscall_openbsd_$GOARCH.go"
307 mkerrors="$mkerrors"
308 mksyscall="./mksyscall.pl -l32 -openbsd -arm -libc"
309 mksysctl="./mksysctl_openbsd.pl"
310 zsysctl="zsysctl_openbsd.go"
311 mksysnum="curl -s 'http://cvsweb.openbsd.org/cgi-bin/cvsweb/~checkout~/src/sys/kern/syscalls.master' | ./mksysnum_openbsd.pl"
312 # Let the type of C char be signed to make the bare syscall
313 # API consistent between platforms.
314 mktypes="GOARCH=$GOARCH go tool cgo -godefs -- -fsigned-char"
315 mkasm="go run mkasm.go"
316 ;;
317 openbsd_arm64)
318 GOOSARCH_in="syscall_openbsd_libc.go syscall_openbsd_$GOARCH.go"
319 mkerrors="$mkerrors -m64"
320 mksyscall="./mksyscall.pl -openbsd -libc"
321 mksysctl="./mksysctl_openbsd.pl"
322 zsysctl="zsysctl_openbsd.go"
323 mksysnum="curl -s 'http://cvsweb.openbsd.org/cgi-bin/cvsweb/~checkout~/src/sys/kern/syscalls.master' | ./mksysnum_openbsd.pl"
324 # Let the type of C char be signed to make the bare syscall
325 # API consistent between platforms.
326 mktypes="GOARCH=$GOARCH go tool cgo -godefs -- -fsigned-char"
327 mkasm="go run mkasm.go"
328 ;;
329 openbsd_mips64)
330 GOOSARCH_in="syscall_openbsd1.go syscall_openbsd_$GOARCH.go"
331 mkerrors="$mkerrors -m64"
332 mksyscall="./mksyscall.pl -openbsd"
333 mksysctl="./mksysctl_openbsd.pl"
334 zsysctl="zsysctl_openbsd.go"
335 mksysnum="curl -s 'http://cvsweb.openbsd.org/cgi-bin/cvsweb/~checkout~/src/sys/kern/syscalls.master' | ./mksysnum_openbsd.pl"
336 # Let the type of C char be signed to make the bare syscall
337 # API consistent between platforms.
338 mktypes="GOARCH=$GOARCH go tool cgo -godefs -- -fsigned-char"
339 ;;
340 plan9_386)
341 mkerrors=
342 mksyscall="./mksyscall.pl -l32 -plan9"
343 mksysnum="./mksysnum_plan9.sh /n/sources/plan9/sys/src/libc/9syscall/sys.h"
344 mktypes="XXX"
345 ;;
346 solaris_amd64)
347 mksyscall="./mksyscall_libc.pl -solaris"
348 mkerrors="$mkerrors -m64"
349 mksysnum=
350 mktypes="GOARCH=$GOARCH go tool cgo -godefs"
351 ;;
352 windows_*)
353 echo 'run "go generate" instead' 1>&2
354 exit 1
355 ;;
356 *)
357 echo 'unrecognized $GOOS_$GOARCH: ' "$GOOSARCH" 1>&2
358 exit 1
359 ;;
360 esac
361
362 (
363 if [ -n "$mkerrors" ]; then echo "$mkerrors |gofmt >$zerrors"; fi
364 syscall_goos="syscall_$GOOS.go"
365 case "$GOOS" in
366 darwin | dragonfly | freebsd | netbsd | openbsd)
367 syscall_goos="syscall_bsd.go $syscall_goos"
368 ;;
369 esac
370 if [ -n "$mksyscall" ]; then echo "$mksyscall -tags $GOOS,$GOARCH $syscall_goos $GOOSARCH_in |gofmt >zsyscall_$GOOSARCH.go"; fi
371 if [ -n "$mksysctl" ]; then echo "$mksysctl |gofmt >$zsysctl"; fi
372 if [ -n "$mksysnum" ]; then echo "$mksysnum |gofmt >zsysnum_$GOOSARCH.go"; fi
373 if [ -n "$mktypes" ]; then
374 # ztypes_$GOOSARCH.go could be erased before "go run mkpost.go" is called.
375 # Therefore, "go run" tries to recompile syscall package but ztypes is empty and it fails.
376 echo "$mktypes types_$GOOS.go |go run mkpost.go >ztypes_$GOOSARCH.go.NEW && mv ztypes_$GOOSARCH.go.NEW ztypes_$GOOSARCH.go";
377 fi
378 if [ -n "$mkasm" ]; then echo "$mkasm $GOOS $GOARCH"; fi
379 ) | $run
380
View as plain text