FreeBSD Developers' Handbook
Prev	Chapter 29 x86 Assembly Language Programming	Next

29.10 Unix Environment

An important Unix concept is the environment, which is defined by environment variables. Some are set by the system, others by you, yet others by the shell, or any program that loads another program.

29.10.1 How to Find Environment Variables

I said earlier that when a program starts executing, the stack contains argc followed by the NULL-terminated argv array, followed by something else. The "something else" is the environment, or, to be more precise, a NULL-terminated array of pointers to environment variables. This is often referred to as env.

The structure of env is the same as that of argv, a list of memory addresses followed by a NULL (0). In this case, there is no "envc"--we figure out where the array ends by searching for the final NULL.

The variables usually come in the name=value format, but sometimes the =value part may be missing. We need to account for that possibility.

29.10.2 webvars

I could just show you some code that prints the environment the same way the Unix env command does. But I thought it would be more interesting to write a simple assembly language CGI utility.

29.10.2.1 CGI: A Quick Overview

I have a detailed CGI tutorial on my web site, but here is a very quick overview of CGI:

The web server communicates with the CGI program by setting environment variables.
The CGI program sends its output to stdout. The web server reads it from there.
It must start with an HTTP header followed by two blank lines.
It then prints the HTML code, or whatever other type of data it is producing.

Note: While certain environment variables use standard names, others vary, depending on the web server. That makes webvars quite a useful diagnostic tool.

29.10.2.2 The Code

Our webvars program, then, must send out the HTTP header followed by some HTML mark-up. It then must read the environment variables one by one and send them out as part of the HTML page.

The code follows. I placed comments and explanations right inside the code:

    ;;;;;;; webvars.asm ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
    ;
    ; Copyright (c) 2000 G. Adam Stanislav
    ; All rights reserved.
    ;
    ; Redistribution and use in source and binary forms, with or without
    ; modification, are permitted provided that the following conditions
    ; are met:
    ; 1. Redistributions of source code must retain the above copyright
    ;    notice, this list of conditions and the following disclaimer.
    ; 2. Redistributions in binary form must reproduce the above copyright
    ;    notice, this list of conditions and the following disclaimer in the
    ;    documentation and/or other materials provided with the distribution.
    ;
    ; THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
    ; ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
    ; IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
    ; ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
    ; FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
    ; DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
    ; OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
    ; HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
    ; LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
    ; OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
    ; SUCH DAMAGE.
    ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
    ;
    ; Version 1.0
    ;
    ; Started:   8-Dec-2000
    ; Updated:   8-Dec-2000
    ;
    ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
    %include    'system.inc'
    
    section .data
    http    db  'Content-type: text/html', 0Ah, 0Ah
        db  '<?xml version="1.0" encoding="UTF-8"?>', 0Ah
        db  '<!DOCTYPE html PUBLIC "-//W3C/DTD XHTML Strict//EN" '
        db  '"DTD/xhtml1-strict.dtd">', 0Ah
        db  '<html xmlns="http://www.w3.org/1999/xhtml" '
        db  'xml.lang="en" lang="en">', 0Ah
        db  '<head>', 0Ah
        db  '<title>Web Environment</title>', 0Ah
        db  '<meta name="author" content="G. Adam Stanislav" />', 0Ah
        db  '</head>', 0Ah, 0Ah
        db  '<body bgcolor="#ffffff" text="#000000" link="#0000ff" '
        db  'vlink="#840084" alink="#0000ff">', 0Ah
        db  '<div class="webvars">', 0Ah
        db  '<h1>Web Environment</h1>', 0Ah
        db  '<p>The following <b>environment variables</b> are defined '
        db  'on this web server:</p>', 0Ah, 0Ah
        db  '<table align="center" width="80" border="0" cellpadding="10" '
        db  'cellspacing="0" class="webvars">', 0Ah
    httplen equ $-http
    left    db  '<tr>', 0Ah
        db  '<td class="name"><tt>'
    leftlen equ $-left
    middle  db  '</tt></td>', 0Ah
        db  '<td class="value"><tt><b>'
    midlen  equ $-middle
    undef   db  '<i>(undefined)</i>'
    undeflen    equ $-undef
    right   db  '</b></tt></td>', 0Ah
        db  '</tr>', 0Ah
    rightlen    equ $-right
    wrap    db  '</table>', 0Ah
        db  '</div>', 0Ah
        db  '</body>', 0Ah
        db  '</html>', 0Ah, 0Ah
    wraplen equ $-wrap
    
    section .text
    global  _start
    _start:
        ; First, send out all the http and xhtml stuff that is
        ; needed before we start showing the environment
        push    dword httplen
        push    dword http
        push    dword stdout
        sys.write
    
        ; Now find how far on the stack the environment pointers
        ; are. We have 12 bytes we have pushed before "argc"
        mov eax, [esp+12]
    
        ; We need to remove the following from the stack:
        ;
        ;   The 12 bytes we pushed for sys.write
        ;   The  4 bytes of argc
        ;   The EAX*4 bytes of argv
        ;   The  4 bytes of the NULL after argv
        ;
        ; Total:
        ;   20 + eax * 4
        ;
        ; Because stack grows down, we need to ADD that many bytes
        ; to ESP.
        lea esp, [esp+20+eax*4]
        cld     ; This should already be the case, but let's be sure.
    
        ; Loop through the environment, printing it out
    .loop:
        pop edi
        or  edi, edi    ; Done yet?
        je  near .wrap
    
        ; Print the left part of HTML
        push    dword leftlen
        push    dword left
        push    dword stdout
        sys.write
    
        ; It may be tempting to search for the '=' in the env string next.
        ; But it is possible there is no '=', so we search for the
        ; terminating NUL first.
        mov esi, edi    ; Save start of string
        sub ecx, ecx
        not ecx     ; ECX = FFFFFFFF
        sub eax, eax
    repne   scasb
        not ecx     ; ECX = string length + 1
        mov ebx, ecx    ; Save it in EBX
    
        ; Now is the time to find '='
        mov edi, esi    ; Start of string
        mov al, '='
    repne   scasb
        not ecx
        add ecx, ebx    ; Length of name
    
        push    ecx
        push    esi
        push    dword stdout
        sys.write
    
        ; Print the middle part of HTML table code
        push    dword midlen
        push    dword middle
        push    dword stdout
        sys.write
    
        ; Find the length of the value
        not ecx
        lea ebx, [ebx+ecx-1]
    
        ; Print "undefined" if 0
        or  ebx, ebx
        jne .value
    
        mov ebx, undeflen
        mov edi, undef
    
    .value:
        push    ebx
        push    edi
        push    dword stdout
        sys.write
    
        ; Print the right part of the table row
        push    dword rightlen
        push    dword right
        push    dword stdout
        sys.write
    
        ; Get rid of the 60 bytes we have pushed
        add esp, byte 60
    
        ; Get the next variable
        jmp .loop
    
    .wrap:
        ; Print the rest of HTML
        push    dword wraplen
        push    dword wrap
        push    dword stdout
        sys.write
    
        ; Return success
        push    dword 0
        sys.exit

This code produces a 1,396-byte executable. Most of it is data, i.e., the HTML mark-up we need to send out.

Assemble and link it as usual:

    % nasm -f elf webvars.asm
    % ld -s -o webvars webvars.o

To use it, you need to upload webvars to your web server. Depending on how your web server is set up, you may have to store it in a special cgi-bin directory, or perhaps rename it with a .cgi extension.

Then you need to use your browser to view its output. To see its output on my web server, please go to http://www.int80h.org/webvars/. If curious about the additional environment variables present in a password protected web directory, go to http://www.int80h.org/private/, using the name asm and password programmer.

Prev	Home	Next
Command Line Arguments	Up	Working with Files