E-ACSL-GCC.SH(1)

💖 E-ACSL-GCC.SH(1) 💖

okay bestie, pull up a chair 🪑 because this one is a whole vibe. this is a page from the General Commands Manual, and it's about a little tool called e-acsl-gcc that will absolutely change your C-programming life. no cap.

---

✨ NAME ✨

e-acsl-gcc — instrument and compile C files with E-ACSL 🧚

---

🌸 SYNOPSIS 🌸

e-acsl-gcc [ options ] files

like. that's it. that's the whole thing. you give it options, you give it files, it does the rest 💅

---

🦋 DESCRIPTION 🦋

so e-acsl-gcc is a convenience wrapper — yes, a wrapper, we love a wrapper — for instrumenting C programs using the E-ACSL Frama-C plugin, and then compiling the results with the GNU compiler collection (GCC).

translation: it instruments your C code, then hands it to GCC to actually build. two jobs, one icon 👑

---

🎀 OPTIONS 🎀

okay this is the long part, stay with me, i promise it's giving useful.

• -h, --help — show a help page. the classic. the "wait what was that flag again" button 🙈
• -c, --compile — compile the generated and the original (supplied) sources. this one is enabled by default bestie, so if you want it off, use -n or --no-compile.
• -n, --no-compile — disable compilation of the generated and the original (supplied) sources. just. no compiling today 💀
• -D, --rt-debug — enable runtime debug features, i.e., compile an unoptimized executable with assertions and extra checks. messy but honest ✨
• --no-trace — disable stack trace reporting in debug mode.
• -V, --rt-verbose — output extra messages when executing generated code. it talks. a lot. we love a chatty king 🗣️
• -X, --instrumented-only — do not compile original code. heads up: this only has an effect in the presence of the -c flag.
• -C, --compile-only — compile the input files as if they were generated by E-ACSL.
• -d, --debug=<N> — pass a value to the Frama-C -debug option. by default the -debug flag is unused. (unused! sitting there! untouched! we respect that 😌)
• -v, --verbose=<N> — pass a value to the Frama-C -verbose option. by default the -verbose flag is unused.
• --check — check integrity of the generated AST. mostly useful for developers 🧑💻
• -o, --ocode=<FILE> — output the E-ACSL instrumented code to <FILE>. defaults to a.out.frama.c.
• -O, --oexec=<FILE> — output the code compiled from the uninstrumented sources to <FILE>. the executable compiled from the files generated by E-ACSL is appended the .e.acsl suffix. unless specified, the names of the executables generated from the original and the modified programs are a.out and a.out.e-acsl respectively.
• --oexec-e-acsl=<FILE> — name of the executable file generated from the E-ACSL-instrumented file. unless specified, the executable is named as indicated by the --oexec option.
• -f, --frama-c-only — run input source files through Frama-C without E-ACSL instrumentations. Frama-C, but make it plain 🫶
• -E, --extra-cpp-args=<FLAGS> — pass additional arguments to the Frama-C preprocessor.
• -L, --frama-c-stdlib — use the Frama-C standard library instead of a system-wide one.
• -M, --full-mtracking — maximize memory-related instrumentation. maximize. everything. memory.
• --concurrency — enable concurrency support.
• --temporal — enable checking for temporal memory errors in \valid and \valid_read predicates.
• --weak-validity — enable notion of weak validity. by default expression (p+i), where p is a pointer and i is an integer offset, is deemed valid if both addresses p and (p+i) belong to the same allocated block. with weak validity (p+i) is valid if the memory location which address is given by expression (p+i) is allocated.
• --validate-format-strings — enable built-in detection of format-string vulnerabilities. security girlies rise 🛡️
• --libc-replacements — replace some of the unsafe LIBC functions (e.g., strcpy, memcpy) with RTL alternatives that include internal runtime error checking.
• -g, --gmp — always use GMP integers instead of C integral types. by default the GMP integers are used on an as-needed basis.
• --mbits=<BITS> — architecture to compile to. valid arguments are 16, 32 or 64. defaults to the architecture of the current environment. this option is used to select the machdep when calling Frama-C, and to pass the corresponding -m16, -m32 or -m64 flag to the compiler.
• -l, --ld-flags=<FLAGS> — pass the specified flags to the linker.
• -e, --cpp-flags=<FLAGS> — pass the specified flags to the preprocessor at compile-time. for instrumentation-time preprocessor flags see the --extra-cpp-args option. only takes effect in case compilation has not been disabled (--no-compile).
• -q, --quiet — suppress any output except for errors and warnings. the strong silent type 🤫
• -s, --logfile=<FILE> — redirect all output to a given file.
• --no-constfold — do not supply the -constfold flag to Frama-C.
• -F, --frama-c-extra=<FLAGS> — pass an extra option to a Frama-C invocation.
• -a, --rte=<OPTSTRING> — annotate a source program with assertions using a run of an RTE plugin prior to E-ACSL. OPTSTRING is a comma-separated string that specifies the types of generated assertions. valid arguments are:
  • signed-overflow — signed integer overflows.
  • unsigned-overflow — unsigned integer overflows.
  • signed-downcast — signed downcast exceeding destination range.
  • unsigned-downcast — unsigned downcast exceeding destination range.
  • mem — pointer or array accesses.
  • float-to-int — casts from floating-point to integer.
  • div — division by zero.
  • shift — left and right shifts by a value out of bounds.
  • pointer-call — annotate functions calls through pointers.
  • all — all of the above. (yes, all of them. the whole buffet 🍓)
• -A, --rte-select=<OPTSTRING> — restrict annotations to a given list of functions. OPTSTRING is a comma-separated string comprising function names.
• --zone-sizes=<NAME1:SIZE1,...,NAMEN:SIZEN> — set the size (in MB) of the given zones.

valid zone names are:

• stack — stack shadow space
• heap — heap shadow space
• tls — TLS shadow space
• thread-stack — thread stack shadow space

• -k, --keep-going — continue execution after an assertion failure. resilience era 🌈
• --free-valid-address — trigger failure if a NULL-pointer is used as an input to free function.
• --fail-with-code=<NUMBER> — on assertion failure exit with the given integer code instead of raising an abort signal.
• --assert-print-data — print data contributing to the failed assertion along with the runtime error message.
• --no-assert-print-data — do not print data contributing to the failed assertion along with the runtime error message.
• --external-assert=<FILE> — the filename that contains your own implementation of __e_acsl_assert.
• --external-print-value=<FILE> — the filename that contains your own implementation of __e_acsl_print_value.
• -m, --memory-model=<model> — memory model (i.e., a runtime library for checking memory related annotations) to be linked against the instrumented file.

valid arguments are:

• bittree — memory modelling using a Patricia trie.
• segment — shadow based segment model.

by default the Patricia trie memory model is used.

• --print-mmodels — print the names of the supported memory models.
• -I, --frama-c=<FILE> — the name of the Frama-C executable. by default the first frama-c executable found in the system path is used.
• --e-acsl-share=<DIR> — the name of the E-ACSL share directory. if not provided, it is computed from your setting.
• -G, --gcc=<FILE> — the name of the GCC executable. by default the first gcc executable found in the system path is used.
• --then — separate with a -then the first Frama-C options from the actual launch of the E-ACSL plugin.
• --then-last — separate with a -then-last the first Frama-C options from the actual launch of the E-ACSL plugin.
• --e-acsl-extra=<OPTS> — add <OPTS> to the list of options that will be given to the E-ACSL analysis. only useful when --then is in use, in which case <OPTS> will be placed after the -then on Frama-C's command-line. otherwise, equivalent to --frama-c-extra.
• --ar=<FILE> — the name of the AR executable. only relevant with --dlmalloc-from-sources. by default the first ar executable found in the system path is used.
• --ranlib=<FILE> — the name of the RANLIB executable. only relevant with --dlmalloc-from-sources. by default the first ranlib executable found in the system path is used.
• --with-dlmalloc=<FILE> — use <FILE> instead of distributed dlmalloc library.
• --dlmalloc-from-sources — compile and use dlmalloc library from sources instead of using the distributed library. incompatible with --with-dlmalloc.
• --dlmalloc-compile-only — do not instrument or compile code, only compile dlmalloc library from sources. implies --dlmalloc-from-sources and incompatible with --with-dlmalloc.
• --dlmalloc-compile-flags=<FLAGS> — compile dlmalloc library with <FLAGS> compile flags. default to -O2 -g3. unused if --dlmalloc-from-sources or --dlmalloc-compile-only isn't used.
• --odlmalloc=<FILE> — output compiled dlmalloc library to <FILE>. unused if --dlmalloc-from-sources or --dlmalloc-compile-only isn't used.

---

⭐ EXIT STATUS ⭐

• 0 — successful execution 🎉 slay, it worked.
• 1 — invalid user input 🙈 that one's on you bestie.
• Frama-C or GCC error code — instrumentation- or compile-time error 💀 not your fault, the tools are just going through it.

---

🔥 EXAMPLES 🔥

because reading is one thing and doing is another, here's the whole thing in action:

e-acsl-gcc foo.c

instrument foo.c and output the instrumented code to a.out.frama.c. ✨

e-acsl-gcc -c -ogen_foo.c -Ofoo foo.c

instrument foo.c, output the instrumented code to gen_foo.c and compile foo.c into foo and gen_foo.c into foo.e-acsl. two for the price of one, iconic 👑

e-acsl-gcc --memory-model=bittree -C gen_foo.c

assume gen_foo.c has been instrumented by E-ACSL and compile it into a.out.e-acsl using bittree memory model.

---

🌈 SEE ALSO 🌈

gcc(1), cpp(1), ld(1), frama-c(1)

(the whole friend group 💜)

---

and that's the page!! this one's from 2016-02-02 — yeah, it's been around a minute, but it still ate — and it lives in the E-ACSL-GCC.SH(1) section of the manual. go forth and instrument, bestie 🫶💅✨