|                                                                                                        |
© Copyright (C) h-peter recktenwald, berlin, 2001, free for related work and non-commercial distribution.
tested w. 'Amaya', 'Konqueror', 'Motzilla', 'w3m' and other graphic or text browsers which all interpret the HTML differently and, with Lynx which was the single one of those browsers which could be used to displaying as well as printing the tables orderly arranged and, 'readable'. Line width set to 110 chars/line.
=> lynx

         
   Takvorian hannoveraner abends stuten flehmen nicht...? futtern!  classical dressage  
 
 adw-reiten  vbb fahrplan  FS-Programm  FN Fora  Landesverband Pferdesport BB  Soko Pferd  pflanzen  allbreedpedigree  pferdeversicherung

Reference to Linux 2.{2,4,6} System Calls for Assembly Level Access

version

Wer die Erklärungen lieber in deutscher Sprache hätte, Fehler darin findet, oder irgendwelche Vorschläge dazu hat, schreibe mir bitte. Habe zwar keine deutschsprachigen Texte vorbereitet - was mich insbes. auch der Sorge um pseudo-englisches Idiotsprech oder peinlich deutsches Neuschreib enthebt, helfe bei Fragen zum Assemblern im Linux - mit "as", "fasm", auch "nasm" oder Forth, nicht "C" oder das 'inline'-Zeug des GCC - aber gerne weiter, und wenn es um die "syscalls" generell geht (soweit ich sie denn selber durchschaue..).

Die zickigen Formulierungen gängiger Darstellungen zum Copyright sind mir sowohl zuwider als auch ziemlich unklar. Die(se) Linux-Dokumentation ist zur freien Verwendung für jedermann gedacht, der jenes System mit ihrer Hilfe und durch eigene Beiträge zu fördern rsp. sich an dessen Weiterentwicklung insbes. auch in Gestalt freier und offengelegter Programme zu beteiligen beabsichtigt, sie ist nur kostenlos weiterzugeben und in genanntem Sinne niemandem vorzuenthalten - insbes., und das richtet sich vor allem an u.s.amerikanische Weltherr(schaft)lichkeitsphantasten, erkenne ich keinerlei Embargo an, das nicht für mich rechtsverbindlich innerhalb der EU unbestritten anerkannte Gültigkeit hat! Ich erwarte, daß man diese meine Intention respektiert und ersetze damit allen Lizenzenkram, der sonst hierauf anzuwenden wäre - wobei, aktuellen Bestrebungen begegnend, ich mir ausdrücklich jegliche patentrechtliche Verwertung vorbehalte.
Wer sich hieran nicht hält, aus welchem Grunde auch immer - allein die Tatsache zählt, ist bedingungslos von dieser Nutzungserlaubnis ausgenommen!

"Verbraucherbewußtsein" hat hier keinen Platz: Dies ist ein Ort für Leute, die selber denken! Alles vom Autor dieser Seiten Angebotene ist experimenteller und in den Quellen oft auch undokumentierten Änderungen unterworfener Natur, weshalb er auf keine dessen Eigenschaften eine wie auch immer geartete Gewähr gibt. Eigene Verifikation ist erste und unerlässliche Praemisse!

2.4.19 & .22 scheinen in Ordnung - was den Kern betrifft, nicht z.B. das ausgesprochen gefährlich vermurkste 'mount', dessen reguläre Eigenheiten von ahnungslosen Somnambulen zusammengehäkelt scheinen, und auch nicht das ext3-Filesystem, dessen 'Sicherheit' bis dato vorwiegend in Gestalt der sehr sicheren Selbstzerstörung im Fehlerfalle auffiel. Abbild allzu unbedarften Aktionismus' naiver Kernel-Entwickler ist u.a. auch kurzlebiges Zeug wie etwa die "hugepages", dem natürlich gleich erst mal die eigenen und ein paar Kernel-Versionen später schon wieder nutzlosen syscalls zugewiesen werden mussten...

Ganz klar:
Ich habe die Linux-Assemblerprogrammierung aufgegeben, nichts dazu wird man von mir jemals wieder zu erwarten haben. Ursprünglich der grenzenlosen Borniertheit wegen, die mir in diesem Zusammenhang seitens der Linux-Kernel-Entwickler begegnete. Es führt inzwischen auch kein Weg zurück, denn ich habe endlich wieder zu den Pferden gefunden, einem Ort, neben dem der gesamte Computerkram mir nur blanken Stumpfsinn und endlose Langeweile zu vermitteln imstande ist.
Mein Interesse ist nunmehr ganz auf Ausbildung und Training von Reitern und Pferden gerichtet.
 

 


 

© COPYRIGHT 2004 Berlin by H-Peter Recktenwald:
This documentation is made to be freely used for those who intend to supporting or contributing to the Linux environment, it may cost-free, only, and freely be distributed to anyone who is willing to supporting Open Source software and the Linux development, without restriction. Pse, take this instead of the common 'Licensing Terms' and, kindly behave accordingly. Wrt legal issues the german text applies!

From the 'linux device drivers' text:

"As far as the kernel is concerned, the even-numbered kernel versions (i.e., 2.2.x and 2.4.x) are the stable ones that are intended for general distribution. The odd versions (such as 2.3.x), on the contrary, are development snapshots and are quite ephemeral; the latest of them represents the current status of development, but becomes obsolete in a few days or so.
which does not apply to the 2.4 kernel series! Actually, the kernel 'development' looks like some confused collection of programming accidents which just by probability, due to it's huge mass fairly often might deliver a working program.

 



Pse, note that because I have no access to other hardware,
CPU specific documentation & examples refer to IA-32, w. i386 cpu type, tests based on k6-2.

Archived html syscalls pages, version (3/2004); updated html man 2 & 3p pages (2.2/4/6, v1.66, 260K+)
[intro] [a:index by names] [s:index by topic] [#:index by numbers]
[1..64] [65..128] [129..192] [193..256] [257..] [ref] [struc] [fcntl] [ioctl] [pguide]
[back] [links] [main] [bot] [top] [man2] [examples]
 

Current state per Linux 2.4.19 (in progress).

  [#:index] Syscalls index, ordered by Numbers   
  [a:index] Syscalls index, ordered by Names   
  [s:index] Syscalls index, ordered by Subjects   
  [1..64] Functional Reference, I   
  [65..128] Functional Reference, II   
  [129..192] Functional Reference, III   
  [193..256] Functional Reference, IV (lx 2.4, 2.5)  
  [257..] Functional Reference, V (lx 2.5+)  
  [ref] Reference to Syscall Kernel Sources   
  [struc] Data-Type and -Arrays Definitions   
  [fcntl] <fcntl> Operations  (from "glibc" docs, not yet thorougly editted) 
  [ioctl] <ioctl> Codes   
  [pguide] System Calls Portability,  common syscalls and substitutes
  <man 2> Supplemental Reference,  html-version section 2 man-pages archive
  examples for syscalls access,  assembler ("nasm" & "AS") code.
       
       
  AS ix86 specific docs extract from AMD-64/32bit binutils w/ the minimal, required information...
 

 Abbreviations:      
  c const... data item may reside in non-alterable memory
  ch  char  a single char (8-bit byte) of a string
  *ch  *char  pointer to string,
<nul>-terminated ("asciz") if no length specified
  short  16-bit word
  int  32-bit dword
  long  32-bit dword
  pointer  an address pointing to memory which may..
  *p  pointer    ..be altered by syscall, unless "const".
  struct  a named data field
  *s  *struct  pointer to a named data field
  u...  unsigned  with the exception of C-ish 'signed char' (by movsx or, movzx)
'signedness' does not apply to raw data but, to data evaluation!
  ul  unsigned long  32-bit dword
  void  unspecified return-value(s), call returns reg eax := -ve ernum
  *v( ... * void( ... re above but, the rsp. reg pointing to the parameter list in memory.
 
 note lazy assumptions about 'signedness' apparently are a frequent source of faults in "C" programs!
and thus should probably be the 1st to check when transposing a "C"-ish program to assembly.
       

 addressing modes:      
   "C"   Assembler
  int name = 33   %define int_name 33
name: dd int_name
  signed char *c ...   movsx eax,byte[c]
  unsigned char *c ...   movzx eax,byte[c]
  return *name;   mov eax,[name]
  return &name;   lea eax,[name]
  or
mov eax,name
       

 syscall (IA-32/i386):      
  eax   syscall number
  ebx, ecx, edx, esi, edi   arguments
  ebp   kernel 2.4.+ 6th argument
  eax   single reg return value, no other regs changed
  eax   0xfffff000 < eax <= 0xffffffff may be an error code.
re glibc2, sysdeps/unix/sysv/linux/i386/sysdep.h

 




 

Prerequisites

Before beginning with Linux assembly you might consider reading the "lki" description and, getting quite familiar with at least the kernel sources, funny (G)AS-ish assembler syntax and preferrably the libc sources also - youl'd be quite lost, otherwise. Plus, GNU/FSF-style 'no docs better than a man page' being plain annoyance and, some contributors emanating nonsense like

Though Linux docs could certainly not be that static as, for instance, those rather antique *DOS-ish things were, that strange point of view is apparently quite common. But, even serious developement might result in frequent changes, too, and thus no assumption can be made about kernel access, i.e. the system calls and associated data, unless verified wrt the versions concerned.
I didn't encounter any major problems due to incompatible calling conventions w. 2.2 and (early!) 2.4 kernel syscalls but, I can not over-emphasize that "verify", simply because many man-pages aren't system call descriptions but, relate to some "libc" code and might thus provide entirely false or misleading "information". The many, inconsistent 2.4/2.6 kernel variants bear some considerably un-certain parts due to newly introduced, different calling conventions and modified syscall names, which were introduced, once, and removed, later, w.o. any reliable documentation others were differently implemented w.o. notice - or, even worse, with a false notice (e.g. "sys_mount").

This attempt is not intended to be just another compilation of un-complete references, but a reference to the many references I found, as some means of information to start with. Obviously, these pages can just (try to) guide you through the huge amount of sources of information, which very often can be quite misleading, but not provide any ultimate advice of how to explicitely do the particular programming. There simply is no other reliable reference than the particular sources - almost all of which are quite badly or (mostly) not at all commented in a useable manner.

Primary source of information - re "intro" - were

No 2.x.x related 'official' system calls documentation exists, at all, thus my rsp pages note what I managed to extract or deduce from source comments and, from analyzing the kernel (and libc) compilation assembly output. Many "GNU"-info documents are neither up-to-date nor complete or even correct; often just a badly structured, almost un-readable collection of links w/ a few lines of text per page, verbosely explaining as little as possible, more or less accidentally relating to some 'topic'.

A valuable source of information, even specifying the parameter to registers assignation when calling "C functions", etc. is the "System V" documentation, available at www.sco.com, covering about everything of a Unix-style system.

To finding out about actual kernel and syscalls access compile the particular sources with

which leaves the intermediately generated (gas-)assembly files un-deleted ("-save-temps") and, generates an assembly listing of the final program ("-Wa,-al") - re AS documentation, 'dvi' or 'ps' versions, the 'info' files are about un-readable.

With plenty of hd space (e.g. ca 150M for libc) the listing could be stored, en bloc:

and "LOG.m" filtered (or directly piped) for the actual assembly output w.
		#! /bin/sh
		f=${1};[ -z "${f}" ]&&f=./LOG.m
		o=./LOG.s.gz
		while read "n" "i"
		do
		    [ -z "${i}" ]&&continue
		    [ "${n}" = "${n#.debug_str:*}" ]||continue
		    [ "${n}" = "${n#[0-9]*}" ]&&continue
		    [ "$(($n))" -gt "$((0))" -o "${i}" != "${i#\.text*}" -o "${i:0:1}" = "\."  ]&&echo -e "${n}\t${i}"
		done<$f |gzip -c9 >${o}
Probably faster: with the last line of the above script modified to

Alternatively, generating single listing files per sourcefile, ea:

the "m" option is for macroes expansion (not "#define" &c, which are not "macroes" but, "text substitution"), "=" gives the listing filename, with "\$$@" from the actual object file at the rsp. compiler run. Depending on the rsp. shell, "\$$@" probably got to be passed in another style such, that it would be inserted to "Makfile" as '-Wa,-acdlms=$@.lis'.

A little script, which can be used to find the i386 syscalls sources:


		#!/bin/sh
		for i in \
		$(find . -depth ! -type d -iname "*.[chs]" -exec egrep -il '\<asmlinkage\>' \{\} \;|\
		egrep -v "arm\>\|ppc\>\|sparc\|m68k\|AS\|mips\|alpha\|s390\>")
		do
		    v=$(grep -il "\<sys_" ${i})
		    [ -z "${v}" ]||{
			echo ${v}
			{ grep asmlinkage "${v}"|egrep '\)'||grep -A1 asmlinkage "${v}"; }
		    }
		done

The shell script unistd-na - (G)AS conformant if executed as (linked to) "unistd-as" - from the "lib4th" package can be used to generating a set of include-files w/ the syscall numbers, a list of name strings wrt the rsp. numbers and, the constants used for sys_fcntl.

Supplementary references are the corresponding header files of the kernel sources. As there is no sense in just copying dozens of Linux source files to these pages many links rely on a standard user readable (chmod -R a+rX /usr/src/linux) linux kernel sources and man-pages installation, at the users site,

/usr/src/linux/ (2.2.19, 2.4.18...)
/usr/src/glibc/ (2.1.3, 2.2.5)
/usr/include/ (libc &c, ref's)
/usr/man/html/man2/all2.2.html manual pages.
For further reference e.g, by "lib4th", I'd suggest installation of the syscalls docs at
/usr/share/doc/linux/syscalls/
The links to the source files (*.c, *.h, *.S) were made to help fiddling through those endless levels of consecutive inter-dependent files in the local source tree.
Re file "syscalls-in-f8" for a list of system calls used in 'lib4th', and where. The relatively small F4 fig-Forth-style implementation the binary of which can be compiled w. (G)CC, GASP (or MASP) and AS, also provides several examples (mmap, read/write, etc) and, direct access by names to all at compile-time present system calls of the rsp. Linux kernel.

Definitions and applications of many system calls in the Linux kernel sources can be found searching for the text segment "asmlinkage" which is just a sequence of otherwise useless #define-s to controlling the C compiler, defined in linkage.h.

Several indexing programs can greatly help browsing through kernel or libc sources - the latter of which is another good place to looking for the linux interna. Like "doxygen" or, the very valuable "Global" group of programs, which take a lot of space (35M+ for the Linux kernel) but give the most comprehensive reference and generate the whole tree browsable with any html reader, like Lynx, etc.

 


 

System

Most syscalls refer to <unistd.h>, <linux/types.h>, <asm/posix_types.h>, and <linux/kernel.h> for data structures, which will not be repeated. The syscall interface is defined in linux/arch/i386/kernel/entry.S.

 

x86-Linux applications are running in unsegmented, "flat" virtual memory 32-bit (64bit) protected mode, level 3; kernel modules and syscalls are level 0. The only one orderly - w.r.t. Linux/ELF code - system access from outside the kernel is via <int 0x80>, the system call software interrupt. Access to other Linux-ish systems may be different! re "asmutils".

Syscalls Access is fairly simple:


        The int 128 syscall number is expected in 
		eax,
        arguments - as in man(2) descriptions - left to right in 
		ebx, ecx, edx, esi, edi (,ebp).
	Often, arguments are passed by memory reference (by address
	of a data structure - "pointer", re man 2) which, if more 
	than five ones required (6 w. Linux 2.4.+) becomes mandatory.

	No return values - nor even changed registers -  other than 
		eax
	with result as specified in the below ref'd tables or,
	the error code
	Signed range of -4096 < eax < 0 is an error code, anything 
	else may be an orderly return value, thus - where it applies - don't 
	falsely interpret a presumably "-ve" figure as an error message, w/o 
	further testing. In fact, there is no 'signedness' inherent to any 
	system call data, it's just a lazy (stupid?) interpretation...

	NOTE:
	direct, kernel system calls always save all registers, w. segments 
	and eflags. what manual pages explain, again, does not apply to the 
	system calls on assembly level but, to some obscure library wrappers!
	
	For instance, while accessing the system calls via "libc"
		ebx, esi, edi, ebp (and esp)
	registers remain unchanged, 
		ebp
	used for 6-arguments-calls with Linux 2.4.xx kernels, 
		ecx, edx
	can return w. un-predeterminable values.
		eax and, edx w. certain calls
	contain the return value(s), eax set to -1 if an error occurred and some 
	global(!) variable <ernum> (or so...) has the actual error code.

Not related to the kernel system calls but, for reference w. the linux 'man'ual pages (most of) which do not describe the system calls but, the rsp. entry routines provided with 'libc' C-ish 'functions':
C functions expect the arguments in left to right order on the return-stack, 1st argument at lowest address (x86 implements the 'little endian' bytes order), i.e. last argument in the C functionarguments list pushed 1st, 1st C-arg pushed last, at top of stack before calling. The return-stack should be restored to it's address on entry, afterwards, if the rsp function itself was called as a subroutine.

		------		ESP, t.o.s. on entry into caller code
		  |
		  v
		------		EBP := ESP
		(locals)	callee local data-space ('automatic variables')
		------
		(args)		args to the C routine
		------		ESP
		call ...	locals by -disp(ebp), args by +disp(esp)
		------
		  		r-stack cleanup e.g. ESP := EBP
		------		ESP restored to address on entry
The above structure is also a widely used calling convention but, it is not the single one. Clever system-designers wont't ever get tired to makeing things 'unique', according to their superior insight and thus, won't stop getting on our nerves by ever so often providing new and truely revolutionary new conventions. Therefore, watch it...

Syscalls Useage may not be that simple, though:

Most of currently (2.6 kernels) 257 system call numbers are defined and explained in the latest (1.66+) man pages, sections 2 and 3p ('p'osix) for "C" programming, only - or not at all. The glibc sources could be used to finding out about those which aren't listed in the manuals (syscalls in libc sources appear prepended with "__" 2 understrokes, calls to kernel wrapped by some other code, with macro "INLINE_SYSCALL").
Another very helpful source is the libASM package, with a much clearer listing of what arguments those calls expect and several applications of the system calls: Due to specific drawbacks of the "C"-ish programming approach many syscalls appear wrapped into some other code, to hiding what really takes place. Thus, even if the corresponding man 2 pages seem providing some related information they may be badly mis-leading w.r.t. at least, the calling arguments. Further, those arguments lists neither are documented properly, themselves, nor are they always straightforwardly translatable into clear structures and may deviate considerably!

There is not much explanation w.r.t. the int 0x80 system routines in the Linux sources documentation and, nothing relates to assembly programming. Even worse, some mindless man(2)-pages authors obviously overestimate themselves, claiming superior knowledge, for instance in "readdir" man-page:

	This is  not the function you are interested in. Look at
	readdir(3) for the POSIX conforming C library interface.
Don't get discouraged by that sort of stupid comments! Anyway, at least for a beginning we got to rely on "the sources" and, on third party texts (re the links page) and on those sparse, still, "C"-ish documentations (re below).

 


 

up

From the section 2 "intro" manpage:

                        ...
       [man 2 intro] describes the Linux system calls. For a list
       of the 164 syscalls present in Linux 2.0, see syscalls(2).
                             ...

   Synopsis
       #include <linux/unistd.h> /* for _syscallX macros/related stuff */

       A _syscall macro

       desired system call


   Setup
       The  important  thing  to  know about a system call is its
       prototype.  You need to know  how  many  arguments,  their
       types, and the function return type.  There are six macros
       that make the actual call into the  system  easier.   They
       have the form:

              _syscallX(type,name,type1,arg1,type,arg2,...)

                     where
                     X     is 0-5, the number of arguments taken 
                           by the system call
                     type  is the return type of the system call
                     name  is the name of the system call
                     typeN is the Nth argument's type
                     argN  is the name of the Nth argument

       These macros create a function called name with the  argu-
       ments  you  specify.   Once  you include the _syscall() in
       your source file, you call the system call by name.

EXAMPLE
       #include <stdio.h>
       #include <linux/unistd.h> /* for _syscallX macros/related stuff */
       #include <linux/kernel.h> /* for struct sysinfo */

       _syscall1(int, sysinfo, struct sysinfo *, info);

       int main(void)
       {
            struct sysinfo s_info;
            int error;

            error = sysinfo(&s_info);
            printf("code error = %d\n", error);
               printf("Uptime = %ds\nLoad: 1 min %d / 5 min %d / 15 min %d\n"
                       "RAM: total %d / free %d / shared %d\n"
                       "Memory in buffers = %d\nSwap: total %d / free %d\n"
                       "Number of processes = %d\n",
                 s_info.uptime, s_info.loads[0],
                 s_info.loads[1], s_info.loads[2],
                 s_info.totalram, s_info.freeram,
                 s_info.sharedram, s_info.bufferram,
                 s_info.totalswap, s_info.freeswap,
                 s_info.procs);
            return(0);
       }

   Sample Output
       code error = 0
       uptime = 502034s
       Load: 1 min 13376 / 5 min 5504 / 15 min 1152
       RAM: total 15343616 / free 827392 / shared 8237056
       Memory in buffers = 5066752
       Swap: total 27881472 / free 24698880
       Number of processes = 40

NOTES
                        ...
       Some system calls, such as mmap, require  more  than  five
       arguments.   These are handled by pushing the arguments on
       the stack and passing a pointer to the block of arguments.
                        ...
up

 


 

[top] [linux] [main]
[a:index] [#:index] [ref] [intro] [1..64] [65..128] [129..192] [193..256] [257..] [pguide] [ioctl] [fcntl] [struc]

 



© H.-Peter Recktenwald, Berlin, 18.Feb.2000 = .hpr.l0 = : 1804-13807