--- name: "stxxl_tool" section: "1" platform: "linux" package: "libstxxl1-bin" version: "1.4.1-4.1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/stxxl_tool" --- # stxxl\_tool(1) STXXL scratch file administration, and performance testing tool ## NAME stxxl\_tool - STXXL scratch file administration, and performance testing tool ## SYNOPSIS **stxxl\_tool *\* ...** ## DESCRIPTION The stxxl\_tool is an umbrella program that houses several sub-tools for STXXL relating to (e.g.) scratch file manipulation and benchmarking. The behaviour of each sub-tool is given below. Size arguments will accept a string like "343KB" or "44 GiB" as their input. ### Subtools - info Print out information about the build system and which optional modules where compiled into STXXL. - create\_files \ \ Pre-create large files to keep file system allocation time out to measurements. - benchmark\_disks \[options\] \ \[r\|w\] \[alloc\] Benchmark the disks configured by the standard .stxxl disk configuration files mechanism. Blocks of 8 MiB are written and/or read in sequence using the block manager. The batch size describes how many blocks are written/read in one batch. The are taken from block\_manager using given the specified allocation strategy. If size == 0, then writing/reading operation are done until an error occurs. - Parameters:\ size Amount of data to write/read from disks (e.g. 10GiB)\ r\|w Only read or write blocks (default: both write and read)\ alloc Block allocation strategy: RC, SR, FR, striping. (default: RC) Options:\ \-b, --batch Number of blocks written/read in one batch (default: D \* 8MiB) - benchmark\_files \[options\] \ \ Open a file using one of STXXL's file abstractions and perform write/read/verify tests on the file. Block sizes and batch size can be adjusted via command line. If length == 0 , then operation will continue till end of space (please ignore the write error). Memory consumption: block\_size \* batch\_size \* num\_files - Parameters:\ length Length to write in file.\ filename File path to run benchmark on. Options:\ \-o, --offset Starting offset to write in file.\ \--no-direct open files without O\_DIRECT\ \--sync open files with O\_SYNC\|O\_DSYNC\|O\_RSYNC\ \--resize resize the file size after opening, needed e.g. for \ creating mmap files\ \--block\_size block size for operations (default 8 MiB)\ \--batch\_size increase (default 1) to submit several I/Os at once and \ report average rate\ \-f, --file-type Method to open file (syscall\|mmap\|wincall\|boostfd\|...) \ default: syscall\ \-p, --operations \[w\]rite pattern, \[r\]ead without verification, read and \ \[v\]erify pattern (default: 'wv')\ \--pattern 32-bit pattern to write (default: block index) - Benchmark different file access methods, e.g. syscall or mmap\_files. - benchmark\_sort \[options\] \ Run benchmark tests of different sorting methods in STXXL. size is the amount of data to sort, in GiB - Valid options are:\ \-M, --ram : amount of ram to use when sorting, default 256 MiB - benchmark\_disks\_random \ \[block\_size\] \[size\] \[i\|r\|w\] \[alloc\] Benchmark \_random\_ block access on the disks configured by the standard .stxxl disk configuration files mechanism. Available block sizes are power of two from 4 KiB to 128 MiB. A set of three operations can be performed: sequential initialization, random reading and random writing. Parameters:\ span Span of external memory to write/read to (e.g. 10GiB).\ block\_size Size of blocks to randomly write/read (default: 8MiB).\ size Amount of data to operate on (e.g. 2GiB), default: whole span.\ i\|r\|w Operations: \[i\]nitialize, \[r\]ead, and/or \[w\]rite (default: all).\ alloc Block allocation strategy: RC, SR, FR, striping (default: RC). - benchmark\_pqueue \[options\] \[size\] Benchmark the priority queue implementation using a sequence of operations. The PQ contains pairs of 32- or 64-bit integers, or a 24 byte struct. The operation sequence is either a simple fill/delete cycle or fill/intermixed inserts/deletes. Because the memory parameters of the PQ must be set a compile-time, the benchmark provides only three PQ sizes: for 256 MiB, 1 GiB and 8 GiB of RAM, with the maximum number of items set accordingly. - Parameters:\ size Amount of data to insert (e.g. 1GiB) Options:\ \-t, --type Value type of tested priority queue:\ 1 = pair of uint32,\ 2 = pair of uint64 (default),\ 3 = 24 byte struct\ 0 = all of the above\ \-p, --pq Priority queue configuration to test:\ 1 = small (256 MiB RAM, 4 GiB elements)\ 2 = medium (1 GiB RAM, 16 GiB elements) (default)\ 3 = big (8 GiB RAM, 64 GiB elements)\ 0 = all of the above\ \-o, --opseq Operation sequence to perform:\ 1 = insert all, delete all (default)\ 2 = insert all, intermixed insert/delete\ 0 = all of the above - mlock \ Allocate some memory and mlock() it to consume physical memory. Needs to run as root to block more than 64 KiB in default settings. - mallinfo Show mallinfo statistics. ## AUTHOR stxxl is written by many authors, and can be found in the AUTHORS section of the documentation package, or on the homepage ## HOMEPAGE libstxxl Project Home : http://stxxl.sourceforge.net This manual page was written by D Haley \, for the Debian project (and may be used by others).