ADJSTACK(2) Linux Programmer's Manual ADJSTACK(2) NNAAMMEE adjstack - shrink stack segment for a process SSYYNNOOPPSSIISS iinntt aaddjjssttaacckk ((vvooiidd **sspp,, ssiizzee__tt mmaaxx__uunnuusseedd)) DDEESSCCRRIIPPTTIIOONN The aaddjjssttaacckk function is used to notify the kernel about how much of a stack segment is used in order to possibly release part of the unused stack according to mmaaxx__uunnuusseedd argument. The operating system is not able to determine how much of the stack segment is in use. Moreover the operating system knows nothing about how a process will reuse its stack. As a result the OS will only eexxppaanndd tthhee ssttaacckk of a process (automatically on page faults). The argument sspp is the address of the stack pointer. mmaaxx__uunnuusseedd is the size of the unused stack we are willing to keep. Having unused stack is not a bad thing, please see the section UUSSAAGGEE on how to use this call. When aaddjjss­­ ttaacckk is called, the kernel will search the virtual memory areas for the one which includes sspp in its range and it is a stack (VM_GROWSDOWN). The unused stack is the distance of sspp and the start of this virtual memory area. If the unused stack is greater than mmaaxx__uunnuusseedd part of the unused stack will be released. NNOOTTEESS The stack segment of a process is automatically expanded with automatic variables and aallllooccaa function. Consider the following sample code: int foo () { int tmp [10000]; /* ... */ } int compute () { if (Condition ()) foo (); /* ... */ } int main_loop () { /* ... */ sleep_input (); compute (); } The first time foo() is called the stack will be expanded to fit the tmp[] array (we assume automatic variables are 100% used, if not our code should be broken to more Linux 2.2.16 14 Jun 2000 1 ADJSTACK(2) Linux Programmer's Manual ADJSTACK(2) functions probably). This will take some time but since the kernel does not shrink the stack, the next calls to foo will be very fast. In this case the unused stack is a ``good thing''. Our case of interest is when Condition() is mostly false and foo() is called very rarely. The function sleep_input() in the sample code is there to show that it is not just calling foo() rare but our program may also spend most of its time sleeping. In this scenario, without aaddjjssttaacckk it would be wiser to use mmaalllloocc and ffrreeee instead the automatic array for tmp[]. Such a case is rare in programs but if you decide to use aallllooccaa for temporary data, the stack usage will probably come closer to the above scenario. The man page of aallllooccaa mentions ``the temporary space is automatically freed on return'', but that means ``it can be reused for future stack requirements but it won't be really returned to the OS''. In linux kernels above 2.4.0 aaddjjssttaacckk will use mmaaddvviissee to mark the pages MADV_DONTNEED and the pages won't be freed until the kernel finds another use for them. UUSSAAGGEE In order to use aaddjjssttaacckk the address of the stack pointer must be known. In x86 architecture the procedure will be something like: { unsigned long _ptr; __asm__ ("mov %%esp, %0"::"m"(_ptr)); adjstack (_ptr, 8*PAGE_SIZE); } The value of mmaaxx__uunnuusseedd is most important since a bad value will slow down the program. There are two opposite cases: a) No stack shrinking which is the default behaviour. We have the fastest performance at the - possible - price of unused stack. b) No unused stack at all if we call aaddjjssttaacckk with mmaaxx__uunnuusseedd set to zero. We have no unused stack at the price of worst performance. The best approach is to be closer to (a) and use mmaaxx__uunnuusseedd only to fix extreme stack usage situations. It is advisable not to worry about the stack until the pro­ gram development is finished; then make an estimation of the standard/expected stack usage and set mmaaxx__uunnuusseedd to two or three times the estimated value. If not sure whether to use aaddjjssttaacckk its better not to use Linux 2.2.16 14 Jun 2000 2 ADJSTACK(2) Linux Programmer's Manual ADJSTACK(2) it! RREETTUURRNN VVAALLUUEE On success, 0 is returned and on error -1. An error can occur for a bad value of sspp (no stack segment found including sspp in its range), but failure of aaddjjssttaacckk will not cause any problems to the program and can be ignored. AAUUTTHHOORRSS Contact Stelios Xanthakis (axanth@tee.gr) for man page feedback or questions. SSEEEE AALLSSOO aallllooccaa((33)),, mmaaddvviissee((22)) Linux 2.2.16 14 Jun 2000 3