Tribblix: manual page: lfcompile.7

LFCOMPILE(7) Standards, Environments, and Macros LFCOMPILE(7)

NAME

lfcompile - large file compilation environment for 32-bit
applications

DESCRIPTION

All 64-bit applications can manipulate large files by default. The
methods described on this page allow 32-bit applications to
manipulate large files.

In the large file compilation environment, source interfaces are
bound to appropriate 64-bit functions, structures, and types.
Compiling in this environment allows 32-bit applications to access
files whose size is greater than or equal to 2 Gbyte ( 2^31 bytes).

Each interface named xxx() that needs to access 64-bit entities to
access large files maps to a xxx64() call in the resulting binary.
All relevant data types are defined to be of correct size (for
example, off_t has a typedef definition for a 64-bit entity).

An application compiled in this environment is able to use the xxx()
source interfaces to access both large and small files, rather than
having to explicitly utilize the transitional xxx64() interface calls
to access large files. See the lfcompile64(7) manual page for
information regarding the transitional compilation environment.

Applications can be compiled in the large file compilation
environment by using the following methods:

o Use the getconf(1) utility with one or more of the
arguments listed in the table below. This method is
recommended for portable applications.

+--------------+----------------------------+
| argument | purpose |
+--------------+----------------------------+
|LFS_CFLAGS | obtain compilation flags |
| | necessary to enable the |
| | large file compilation |
| | environment |
|LFS_LDFLAGS | obtain link editor options |
|LFS_LIBS | obtain link library names |
|LFS_LINTFLAGS | obtain lint options |
+--------------+----------------------------+

o Set the compile-time flag _FILE_OFFSET_BITS to 64 before
including any headers. Applications may combine objects
produced in the large file compilation environment with
objects produced in the transitional compilation
environment, but must be careful with respect to
interoperability between those objects. Applications
should not declare global variables of types whose sizes
change between compilation environments.

Access to Additional Large File Interfaces

The fseek() and ftell() functions do not map to functions named
fseek64() and ftell64(); rather, the large file additions fseeko()
and ftello(), have functionality identical to fseek() and ftell() and
do map to the 64-bit functions fseeko64() and ftello64().
Applications wishing to access large files should use fseeko() and
ftello() in place of fseek() and ftell(). See the fseek(3C) and
ftell(3C) manual pages for information about fseeko() and ftello().

Applications wishing to access fseeko() and ftello() as well as the
POSIX and X/Open specification-conforming interfaces should define
the macro _LARGEFILE_SOURCE to be 1 and set whichever feature test
macros are appropriate to obtain the desired environment (see
standards(7)).

EXAMPLES

In the following examples, the large file compilation environment is
accessed by invoking the getconf utility with one of the arguments
listed in the table above. The additional large file interfaces are
accessed by specifying -D_LARGEFILE_SOURCE.

The examples that use the form of command substitution specifying the
command within parentheses preceded by a dollar sign can be executed
only in a POSIX-conforming shell such as the Korn Shell (see ksh(1)).
In a shell that is not POSIX-conforming, such as the Bourne Shell
(see sh(1)) and the C Shell (see csh(1)), the getconf calls must be
enclosed within grave accent marks, as shown in the second example.

Example 1: Compile a program with a "large" off_t that uses fseeko(),

ftello(), and yacc.

The following example compiles a program with a "large" off_t and
uses fseeko(), ftello(), and yacc(1).

$ c89 -D_LARGEFILE_SOURCE \
-D_FILE_OFFSET_BITS=64 -o foo \
$(getconf LFS_CFLAGS) y.tab.c b.o \
$(getconf LFS_LDFLAGS) \
-ly $(getconf LFS_LIBS)

Example 2: Compile a program with a "large" off_t that does not use

fseeko() and ftello() and has no application specific libraries.

% c89 -D_FILE_OFFSET_BITS=64 \
`getconf LFS_CFLAGS` a.c \
`getconf LFS_LDFLAGS` \
`getconf LFS_LIBS` \

Example 3: Compile a program with a "default" off_t that uses fseeko()

and ftello().

$ c89 -D_LARGEFILE_SOURCE a.c

NOTES

Certain system-specific or non-portable interfaces are not usable in
the large file compilation environment. Known cases are:

o Kernel data structures read from /dev/kmem.

o Interfaces in the kernel virtual memory library, -lkvm.

o Interfaces in the ELF access library, -lelf.

o Interfaces to /proc defined in <procfs.h>.

o The ustat(2) system call.

Programs that use these interfaces should not be compiled in the
large file compilation environment. As a partial safeguard against
making this mistake, including either of the <libelf.h> or
<sys/procfs.h> header files will induce a compilation error when the
large file compilation environment is enabled.

In general, caution should be exercised when using any separately-
compiled library whose interfaces include data items of type off_t or
the other redefined types either directly or indirectly, such as with
'struct stat'. (The redefined types are off_t, rlim_t, ino_t,
blkcnt_t, fsblkcnt_t, and fsfilcnt_t.) For the large file compilation
environment to work correctly with such a library, the library
interfaces must include the appropriate xxx64() binary entry points
and must have them mapped to the corresponding primary functions when
_FILE_OFFSET_BITS is set to 64.

Care should be exercised using any of the printf() or scanf()
routines on variables of the types mentioned above. In the large
file compilation environment, these variables should be printed or
scanned using long long formats.

BUGS

Symbolic formats analogous to those found in <sys/int_fmtio.h> do not
exist for printing or scanning variables of the types that are
redefined in the large file compilation environment.

August 24, 2009 LFCOMPILE(7)