The type of access used to open the file must be declared for all file open requests. If you have opened files using the open() C function, you are probably familiar with using predefined constants such as O_RDNONLY or O_RDWR. Unfortunately, these constants are not defined for you within your assembly language program. You must use the numeric values they represent or define the constants yourself. The numeric values for these constants are usually represented as octal values. The numeric values of the constants are shown in the following table.

The file access types can be combined to enable multiple access features. For example, if you want to create a file and open it for both read and write access, you would use the following instruction:

movl $0102, %ecx

This combines the O_CREATE value of 0100 with the O_RDWR value of 02. The leading zero in the constant value is important. This signifies that the value is in octal format. If you used the constant $102, you would get the wrong results, as the assembler would use the decimal value of 102.

If you want to append new data to an existing file, you would use this instruction:

movl $02002, %ecx

This combines the O_APPEND value of 02000 with the O_RDWR value of 02, and does not set the O_CREAT value. If the file does not exist, it will not be created.

Setting the UNIX permissions can often lead to complicated situations. Care must be taken to ensure that the proper permissions are set for the file access. The standard UNIX permissions are set for three categories of users:

Each of the three categories is assigned specific permissions for the file. Three bits are used to indicate the access for each category:

The three bits are aligned to form a three-bit value for each category, as shown in Figure 16-2.

Figure 16.2. Figure 16-2

As shown in Figure 16-2, the three bits can also be represented by an octal value, indicating which bits are set. The values can be combined to produce various access levels, shown in the following table.

The file mode properties are combined to form a single three-digit octal number, representing the owner, group, and everyone privileges. This three-digit octal number is what is defined in the open system call, along with a leading zero to make it an octal value.

The instruction

movl $0644, %edx

assigns the octal value 644 to the EDX register. The 6 digit indicates that the file will have read/write privileges for the owner. The middle 4 digit indicates that the file will have read-only privileges for the file's assigned group, and the second 4 digit indicates that the file will have read-only privileges for everyone else on the system.

Note one caveat to this: The Linux system assigns an umask value for every user that logs into the system. The umask value masks the default privileges assigned to files created by that user. The final privileges for the created file would be as follows:

file privs = privs & ~umask

The umask is inverted, and AND'd with the requested privileges in the open system call. You can see the umask value assigned to your user account by using the umask command:

$ umask
022
$

The umask assigned to this account is the octal value 022. If an open system call is performed requesting the creation of a file with 0666 privileges (read/write for everyone), the final privileges assigned to the created file will be as follows:

final privileges = privs & ~umask
                 = 666 & ~022
                 = 666 & 755
                 = 644

The requested privileges for the owner are not modified, but the requested write privileges for the group and for everyone else are denied by the umask value. This is a commonly used umask value for systems. It prevents unintentionally granting write privileges to files.

If you really intended to grant write privileges to everyone for the file, you must either change your umask value, or use the chmod command to manually change the privileges of the file.

The last piece of the system call is to declare the filename to open. If no path is used, the filename is assumed to be located in the same directory from which the executable program was run.

The filename must be declared as a null-terminated string. This can be done using the .asciz declaration:

.section .data
filename:
   .asciz "output.txt"
.
.
.section .text
.
.
   movl $filename, %ebx

Because the EBX register contains the memory address for the location of the string, you must use the dollar sign with the variable name to get the memory address location of the string.

Another method that is commonly used is to allow the filename to be declared as a command-line parameter for the program. Chapter 11, "Using Functions," showed how to access command-line parameters from the program stack. The location 8(%ebp) contains a pointer to the memory location containing the first command-line parameter. This is exactly what we need for the filename; thus, you can use the instructions

movl %esp, %ebp
.
.
movl 8(%ebp), %ebx

to move the filename listed as the first command-line parameter into the open system call function call. This is shown in more detail in the examples later in this chapter.

Putting all of the pieces together, you can open a file with a simple code snippet such as this:

movl $5, %eax
movl $filename, %ebx
movl $0102, %ecx
movl $0644, %edx
int $0x80
test %eax, %eax
js badfile

This code snippet opens a file (declared by the filename data variable) with O_CREAT and O_WRONLY access, using UNIX permissions 0644 (read/write access for the owner, and read access for anyone else).

When the system call returns, the EAX register contains a signed integer value. This value will be either non-negative, which is the file handle for the open file, or negative, which is an error code indicating why the file could not be opened. Because the error code is a negative value, you can test for it by checking the sign bit using the JS conditional branch instruction.

Usually, you will want to store the file handle to the open file somewhere for use later in the program. Because the file handle is a simple 32-bit signed integer value, it can be kept anywhere you would store any other integer value:

If the open system call does return an error code, you can compare it to the errno values defined in the errno.h header file on the system (the assembly language errorno.h file is usually located in the /usr/include/asm directory on the system). The following table describes some of the more common error codes that may be returned.

When you are finished using a file, the proper thing to do is to close it; otherwise, file corruption is possible. The close system call uses a single input parameter, the file handle of the opened file to close. The parameter is placed in the EBX register:

movl filehandle, %ebx
movl $6, %eax
int $0x80

The close system call returns an error code in the EAX register, using the errno.h error codes. If the file was successfully closed, the EAX register will contain a zero.

A simple assembly language program that writes to a file is demonstrated in the following cpuidfile.s program:

# cpuidfile.s - An example of writing data to a file
.section .data

filename:
   .asciz "cpuid.txt"
output:
   .asciz "The processor Vendor ID is 'xxxxxxxxxxxx'
"
.section .bss
   .lcomm filehandle, 4
.section .text
.globl _start
_start:
   movl $0, %eax
   cpuid
   movl $output, %edi
   movl %ebx, 28(%edi)
   movl %edx, 32(%edi)
   movl %ecx, 36(%edi)

   movl $5, %eax
   movl $filename, %ebx
   movl $01101, %ecx
   movl $0644, %edx
   int $0x80

test %eax, %eax
   js badfile
   movl %eax, filehandle

   movl $4, %eax
   movl filehandle, %ebx
   movl $output, %ecx
   movl $42, %edx
   int $0x80
   test %eax, %eax
   js badfile

   movl $6, %eax
   movl filehandle, %ebx
   int $0x80

badfile:
   movl %eax, %ebx
   movl $1, %eax
   int $0x80

The cpuidfile.s program takes the original cpuid.s program from Chapter 4, "A Sample Assembly Language Program," and modifies it to place the output in a text file. It uses the O_TRUNC, O_CREAT, and O_WRONLY file access modes to open (or create) the cpuid.txt file for writing. If the file already exists, it is truncated (erased), as the O_APPEND access mode was not included. The UNIX permissions were set to 0644 to allow the user to read and write to the file, but only allow read access for others on the system. After the open system call is made, the return value is checked to ensure that it does not contain an error code. If it is a valid file handle, it is stored in the memory location labeled filehandle.

The file handle is then loaded into the EBX register and used with the write system call to write the output value stored from the CPUID instruction to the file.

You can test this program by simply assembling, linking, and running the program:

$ as -o cpuidfile.o cpuidfile.s
$ ld -o cpuidfile cpuidfile.o
$ ./cpuidfile
$ ls -al cpuid.txt
-rw-r--r--    1 rich     rich           42 Oct  6 09:18 cpuid.txt
[rich@test2 chap16]$ cat cpuid.txt
The processor Vendor ID is 'GenuineIntel'
$

The program successfully created the file and placed the output string into it as expected. You can test the file access settings by rerunning the program again and examining the output file:

$ ./cpuidfile
$ ls -al cpuid.txt
-rw-r--r--    1 rich     rich           42 Oct  6 09:20 cpuid.txt
$ cat cpuid.txt
The processor Vendor ID is 'GenuineIntel'
$

The output from the second run erased the original data, writing the new data into the existing file starting at the beginning of the file. This caused the new data to replace the data contained in the existing file (of course, you can't see that because it used the same data). You can test this by using an editor to add other lines to the cpuid.txt output file, and then rerun the cpuidfile program.

The new file generated by the program replaced the data in the existing file. If you want to append the new data to the existing data in the file, you can change the file access mode values. Just replace the open system call lines with the following:

movl $5, %eax
movl $filename, %ebx
movl $02101, %ecx
movl $0644, %edx
int $0x80
test %eax, %eax
js badfile
movl %eax, filehandle

Note that the only change was to the value set in the ECX register, which now adds the O_APPEND access mode value, along with the O_CREAT and O_WRONLY values. After reassembling and linking the new code, you can test it out:

$ ./cpuidfile2
$ ls -al cpuid.txt
-rw-r--r--    1 rich     rich           84 Oct  6 09:26 cpuid.txt
$ cat cpuid.txt
The processor Vendor ID is 'GenuineIntel'
The processor Vendor ID is 'GenuineIntel'
$

As expected, the new version of the program appended the output test string to the existing contents of the cpuid.txt file.

In Linux, there are many reasons why a file access attempt can fail. Other processes can lock files, users can accidentally delete files, or even novice system administrators can assign the wrong permissions to the file. You must ensure that your assembly language code is prepared to deal with failure.

As shown in the cpuidfile.s example, it is best to test the return code from the file access system calls. This example doesn't do anything other than use it as the return code for the exit system call, but in a production program you would want to display some type of error message related to the specific error code encountered.

A simple way to test the error code handling is to force an error condition. For this example, I will change the output file to a read-only file and run the program again:

$ chmod 444 cpuid.txt
$ ls -al cpuid.txt
-r--r--r--    1 rich     rich           84 Oct  6 09:46 cpuid.txt
$ ./cpuidfile
$ echo $?
243
$

The UNIX file mode of the cpuid.txt output file was set to 444, indicating read-only access for the owner of the file, as well as everyone else on the system. When the cpuidfile program was run and the return code checked, an error code was returned.

Because UNIX program return codes are unsigned integers, the return code value is interpreted as a positive value. You can determine the true error code value by subtracting this value from 256, which results in 13. From the errno.h file, you can determine that error code 13 is the EACCES error, which indicates that you do not have permission to write to the file.

The readtest1.s program demonstrates reading data from the cpuid.txt file created by the cpuidfile.s program shown earlier:

# readtest1.s - An example of reading data from a file
.section .bss
   .lcomm buffer, 42
   .lcomm filehandle, 4
.section .text
.globl _start
_start:
   nop
   movl %esp, %ebp
   movl $5, %eax
   movl 8(%ebp), %ebx
   movl $00, %ecx
   movl $0444, %edx
   int $0x80
   test %eax, %eax
   js badfile
   movl %eax, filehandle

   movl $3, %eax
   movl filehandle, %ebx
   movl $buffer, %ecx
   movl $42, %edx
   int $0x80
   test %eax, %eax
   js badfile

   movl $4, %eax
   movl $1, %ebx
   movl $buffer, %ecx
   movl $42, %edx
   int $0x80
   test %eax, %eax
   js badfile

   movl $6, %eax
   movl filehandle, %ebx
   int $0x80

badfile:
   movl %eax, %ebx
   movl $1, %eax
   int $0x80

The readtest1.s program opens the filename specified in the first command-line parameter from the program (located at 8(%ebp)). Because the program just reads the data, the file is opened in O_RDONLY mode. Next, the read system call is performed, pointing to the buffer area specified by the buffer label in the .bss section. The read system call is instructed to read 42 bytes of data (the output from the cpuidfile.s program, including the newline character).

The next section uses the write system call and the STDOUT file handle to display the data stored in the buffer area (again, specifying 42 bytes of data). Finally, the file handle pointing to the cpuid.txt file is closed using the close system call, and the exit system call is used to exit the program.

When you run the program, remember to include the cpuid.txt file name on the command line, as that is where the program will get the filename to open:

$ ./readtest1 cpuid.txt
The processor Vendor ID is 'GenuineIntel'
$

The program behaved as expected. If you forget to include the filename on the command line, nothing is displayed, and error code will result. You can view the error code using the $? shell value:

$ ./readtest1
$ echo $?
242
$

This equates to error code 256 – 242 = 14, or the EFAULT error, showing that no filename address is specified at the 8(%ebp) location.

The readtest1.s program was somewhat of an unrealistic example. It specified exactly the amount of data that needed to be read from the file. More often, you will not know exactly how much data you need to read. Instead, you must loop through the entire file until you reach the end.

This method can be used because of the way the read system call works. Each time the read system call is used, a file pointer is used within the open file to indicate the last byte of data read from the file. If another read system call is used, it starts at the byte immediately following the file pointer location. When it is done reading, it moves the file pointer to the last byte read. This continues until the end of the file is reached.

The way you know the read system call is at the end of the file is that it returns a zero value from the read. You must check the return value at each iteration for either an error or a zero value. If the value is zero, you know that the end of the file has been reached.

The readtest2.s program demonstrates this technique:

# readtest2.s - A more complicated example of reading data from a file
.section .bss
   .lcomm buffer, 10
   .lcomm filehandle, 4

.section .text
.globl _start
_start:
   nop
   movl %esp, %ebp
   movl $5, %eax
   movl 8(%ebp), %ebx
   movl $00, %ecx
   movl $0444, %edx
   int $0x80
   test %eax, %eax
   js badfile
   movl %eax, filehandle

read_loop:
   movl $3, %eax
   movl filehandle, %ebx
   movl $buffer, %ecx
   movl $10, %edx
   int $0x80
   test %eax, %eax
   jz done
   js done
   movl %eax, %edx
   movl $4, %eax
   movl $1, %ebx
   movl $buffer, %ecx
   int $0x80
   test %eax, %eax
   js badfile
   jmp read_loop

done:
   movl $6, %eax
   movl filehandle, %ebx
   int $0x80

badfile:
   movl %eax, %ebx
   movl $1, %eax
   int $0x80

The readtest2.s program again gets the filename to open from the first command-line parameter. The file is opened, and a loop is started to read 10-byte blocks of data from the file, placing them into the buffer location. The buffer location is then written to the display using the write system call. When the read system call returns a zero value, we know we have reached the end of the file, and the file handle can be closed.

Now the readtest2.s program can be used to display a file of any size:

$ ./readtest2 cpuid.txt
The processor Vendor ID is 'GenuineIntel'
The processor Vendor ID is 'GenuineIntel'
$

The readtest2 program displayed the entire cpuid.txt file. You can test it out on any text file, including its own source code file:

$ ./readtest2 readtest2.s
# readtest2.s - A more complicated example of reading data from a file
.section .bss
   .lcomm buffer, 10
   .lcomm filehandle, 4
   .lcomm size, 4
.section .text
.
.
.
badfile:
   movl %eax, %ebx
   movl $1, %eax
   int $0x80
$

The entire source code file was displayed, and the readtest2 program properly stopped when it reached the end of the file.

Memory-mapped files use the mmap system call to map parts of a file into memory on the system. Once the file (or part of the file) is placed in memory, programs can access the memory locations using standard memory-access instructions, and modify them if necessary. The memory locations can be shared by multiple processes, enabling multiple programs to update the same file simultaneously. This is shown in Figure 16-3.

After the file is loaded into memory, the operating system controls who has what type of access to the memory area. The contents of the memory-mapped file can be written back to the original file, replacing the contents of the file with the contents from the memory-mapped file. This is a quick and easy way to update files of almost any size (up to the virtual memory limits of the system).

Figure 16.3. Figure 16-3

The mmap system call is provided to create memory-mapped files. The format of the mmap system call is as follows:

void *mmap(void *start, size_t length, int prot, int flags, int fd, off_t offset);

Here are the input values:

The start value can be set to 0 to enable the system to choose where to place the memory-mapped file in memory. If the offset value is set to 0 and the length value is set to the size of the file, the entire file is mapped to memory. The mmap function is heavily dependent on the system memory page size. If the length value does not fill an entire page (or fills multiple pages with a non-full page left over) the remainder of the page is zero-filled. If an offset value is used, it must be a multiple of the system page size.

The prot value contains settings to determine the access privileges allowed to the memory-mapped file (similar to the access privileges used in the open system call). The available values to use are shown in the following table.

The flag's value defines how the operating system controls the memory-mapped file. Many different flags can be used, but the two most common are shown in the following table.

There is also one other huge difference between these two modes. The MAP_SHARE flag instructs the operating system to write any changes made to the memory-mapped file to the original file. The MAP_PRIVATE flag disregards any changes made to the memory-mapped file when it is closed. While this may seem odd, it actually comes in handy if you need to create a temporary file that requires quick access.

The changes are not written to the original file at the time they are made to the memory-mapped file. This is an important point to remember. Two system calls are used to ensure that the data in the memory-mapped file is written to the original file:

If you are planning to keep the memory-mapped file in memory for a long period of time after any changes are made, it is a good idea to use the msync system call to ensure that the changes have been written to the file. If the program or operating system should crash before either the msync or munmap system calls are made, any changes made to the memory-mapped file will not be made to the original file.

The msync and munmap system calls have similar formats:

int msync(const void *start, size_t length, int flags);
int munmap(void *start, size_t length);

The start input value is the starting point in memory where the memory-mapped file is located. This value is returned by the mmap system call. The length input value is the number of bytes to write to the original file. The msync flags input value enables you to define how the updates are made to the original file:

Using the mmap system call in assembly language requires that you use the format shown in Chapter 12, "Using Linux System Calls." You must know the system call values found in the unistd.h file to place in the EAX register before performing the Linux system call. The system call values for the mmap system calls are shown in the following table.

However, there is one problem with using the standard Linux system call format as shown in Chapter 12 and the mmap system call. While most system calls use the general-purpose registers for input values, system calls that have more than five input values cannot (there are not enough registers to use).

Instead, system calls that have more than five input values (such as mmap) read input values from a structure defined in memory. Each of the input values is placed in memory in order, starting at a specific memory location. The starting point of the memory structure is placed in the EBX register before the system call is made. This is shown in Figure 16-4.

The input values can either be placed in a separately defined memory location or pushed onto the normal program stack before the function call. If the values are pushed onto the stack, remember to place them in opposite order (from right to left) on the stack. You must also remember to remove them from the stack (move the ESP pointer back) when the system call returns.

Figure 16.4. Figure 16-4

The template to use for the mmap system call looks something like this:

pushl $0    # offset of 0
pushl filehandle   # the file handle of the open file
pushl $1     # MAP_SHARED flag set to write changed data back to file
pushl $3     # PROT_READ and PROT_WRITE permissions
pushl size   # the size of the entire file
pushl $0     # Allow the system to select the location in memory to start
movl %esp, %ebx   # copy the parameters location to EBX
movl $90, %eax    # set the system call value
int $0x80
addl $24, %esp
movl %eax, mappedfile   # store the memory location of the memory mapped file

This example creates the memory-mapped file containing the entire file, enabling the process to both read and write data to it, and enabling all updates to be stored in the original file. The return value from the system call is in the EAX register and points to the memory location for the start of the memory-mapped file. This value can be stored and then used as any other memory location, such as the buffer location used in the readtest programs.

To unmap the file from memory, the format for the unmap system call is as follows:

movl $91, %eax
movl mappedfile, %ebx
movl size, %ecx
int $0x80

Because the munmap system call only uses two input values, they can be placed in the EBX and ECX registers before the system call is made. The munmap system call will return a value of zero if it successfully writes the data back to the file. If not, it will return a value of −1.

This section demonstrates how to use the mmap system call to map an entire file into memory, modify the data in the memory-mapped file, and write the data back to the original file.

int_llseek(unsigned int fd, unsigned long offset_high, unsigned long offset_low,
            loff_t *result, unsigned int whence);

# sizefunc.s - Find the size of a file
.section .text
.globl sizefunc
.type sizefunc, @function
sizefunc:
   pushl %ebp
   movl %esp, %ebp
   subl $8, %esp
   pushl %edi
   pushl %esi
   pushl %ebx

movl $140, %eax
   movl 8(%ebp), %ebx
   movl $0, %ecx
   movl $0, %edx
   leal −8(%ebp), %esi
   movl $2, %edi
   int $0x80
   movl −8(%ebp), %eax

   popl %ebx
   popl %esi
   popl %edi
   movl %ebp, %esp
   popl %ebp
   ret

# convert.s - A function to convert lower case letters to upper case
.section .text
.type convert, @function
.globl convert
convert:
   pushl %ebp
   movl %esp, %ebp
   pushl %esi
   pushl %edi

   movl 12(%ebp), %esi
   movl %esi, %edi
   movl 8(%ebp), %ecx

convert_loop:
   lodsb
   cmpb $0x61, %al
   jl skip
   cmpb $0x7a, %al
   jg skip
   subb $0x20, %al
skip:
   stosb
   loop convert_loop

pop %edi
   pop %esi
   movl %ebp, %esp
   popl %ebp
   ret

# fileconvert.s - Memory map a file and convert it
.section .bss
   .lcomm filehandle, 4
   .lcomm size, 4
   .lcomm mappedfile, 4
.section .text
.globl _start
_start:
   # get the file name and open it in read/write mode
   movl %esp, %ebp
   movl $5, %eax
   movl 8(%ebp), %ebx
   movl $0102, %ecx
   movl $0644, %edx
   int $0x80
   test %eax, %eax
   js badfile
   movl %eax, filehandle

   # find the size of the file
   pushl filehandle
   call sizefunc
   movl %eax, size
   addl $4, %esp

   # map file to memory
   pushl $0
   pushl filehandle
   pushl $1     # MAP_SHARED
   pushl $3     # PROT_READ | PROT_WRITE
   pushl size   # file size
   pushl $0     # NULL
   movl %esp, %ebx
   movl $90, %eax
   int $0x80   test %eax, %eax
   js badfile
   movl %eax, mappedfile
   addl $24, %esp

# convert the memory mapped file to all uppers
   pushl mappedfile
   pushl size
   call convert
   addl $8, %esp

   # use munmap to send the changes to the file
   movl $91, %eax
   movl mappedfile, %ebx
   movl size, %ecx
   int $0x80
   test %eax, %eax
   jnz badfile

  # close the open file handle
   movl $6, %eax
   movl filehandle, %ebx
   int $0x80

badfile:
   movl %eax, %ebx
   movl $1, %eax
   int $0x80

$ as -o sizefunc.o sizefunc.s
$ as -o convert.o convert.s
$ as -o fileconvert.o fileconvert.s
$ ld -o fileconvert fileconvert.o sizefunc.o convert.o
$ cat cpuid.txt
The processor Vendor ID is 'GenuineIntel'
The processor Vendor ID is 'GenuineIntel'
$ ./fileconvert cpuid.txt
$ cat cpuid.txt
THE PROCESSOR VENDOR ID IS 'GENUINEINTEL'
THE PROCESSOR VENDOR ID IS 'GENUINEINTEL'
$

$ strace ./fileconvert test.txt
execve("./fileconvert", ["./fileconvert", "test.txt"], [/* 38 vars */]) = 0
open("test.txt", O_RDWR|O_CREAT, 0644)  = 3
_llseek(3, 0, [1419], SEEK_END)         = 0
old_mmap(NULL, 1419, PROT_READ|PROT_WRITE, MAP_SHARED, 3, 0) = 0x40000000
munmap(0x40000000, 1419)                = 0
close(3)                                = 0
_exit(0)                                = ?
$