25 lines
16 KiB
HTML
25 lines
16 KiB
HTML
<!DOCTYPE html>
|
||
<html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>printf() and stdio in the Julia runtime · The Julia Language</title><script>(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
|
||
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
|
||
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
|
||
})(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
|
||
|
||
ga('create', 'UA-28835595-6', 'auto');
|
||
ga('send', 'pageview');
|
||
</script><link href="https://cdnjs.cloudflare.com/ajax/libs/normalize/4.2.0/normalize.min.css" rel="stylesheet" type="text/css"/><link href="https://fonts.googleapis.com/css?family=Lato|Roboto+Mono" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.6.3/css/font-awesome.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/default.min.css" rel="stylesheet" type="text/css"/><script>documenterBaseURL=".."</script><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.2.0/require.min.js" data-main="../assets/documenter.js"></script><script src="../siteinfo.js"></script><script src="../../versions.js"></script><link href="../assets/documenter.css" rel="stylesheet" type="text/css"/><link href="../assets/julia-manual.css" rel="stylesheet" type="text/css"/></head><body><nav class="toc"><a href="../index.html"><img class="logo" src="../assets/logo.png" alt="The Julia Language logo"/></a><h1>The Julia Language</h1><select id="version-selector" onChange="window.location.href=this.value" style="visibility: hidden"></select><form class="search" id="search-form" action="../search.html"><input id="search-query" name="q" type="text" placeholder="Search docs"/></form><ul><li><a class="toctext" href="../index.html">Home</a></li><li><span class="toctext">Manual</span><ul><li><a class="toctext" href="../manual/introduction.html">Introduction</a></li><li><a class="toctext" href="../manual/getting-started.html">Getting Started</a></li><li><a class="toctext" href="../manual/variables.html">Variables</a></li><li><a class="toctext" href="../manual/integers-and-floating-point-numbers.html">Integers and Floating-Point Numbers</a></li><li><a class="toctext" href="../manual/mathematical-operations.html">Mathematical Operations and Elementary Functions</a></li><li><a class="toctext" href="../manual/complex-and-rational-numbers.html">Complex and Rational Numbers</a></li><li><a class="toctext" href="../manual/strings.html">Strings</a></li><li><a class="toctext" href="../manual/functions.html">Functions</a></li><li><a class="toctext" href="../manual/control-flow.html">Control Flow</a></li><li><a class="toctext" href="../manual/variables-and-scoping.html">Scope of Variables</a></li><li><a class="toctext" href="../manual/types.html">Types</a></li><li><a class="toctext" href="../manual/methods.html">Methods</a></li><li><a class="toctext" href="../manual/constructors.html">Constructors</a></li><li><a class="toctext" href="../manual/conversion-and-promotion.html">Conversion and Promotion</a></li><li><a class="toctext" href="../manual/interfaces.html">Interfaces</a></li><li><a class="toctext" href="../manual/modules.html">Modules</a></li><li><a class="toctext" href="../manual/documentation.html">Documentation</a></li><li><a class="toctext" href="../manual/metaprogramming.html">Metaprogramming</a></li><li><a class="toctext" href="../manual/arrays.html">Multi-dimensional Arrays</a></li><li><a class="toctext" href="../manual/linear-algebra.html">Linear algebra</a></li><li><a class="toctext" href="../manual/networking-and-streams.html">Networking and Streams</a></li><li><a class="toctext" href="../manual/parallel-computing.html">Parallel Computing</a></li><li><a class="toctext" href="../manual/dates.html">Date and DateTime</a></li><li><a class="toctext" href="../manual/interacting-with-julia.html">Interacting With Julia</a></li><li><a class="toctext" href="../manual/running-external-programs.html">Running External Programs</a></li><li><a class="toctext" href="../manual/calling-c-and-fortran-code.html">Calling C and Fortran Code</a></li><li><a class="toctext" href="../manual/handling-operating-system-variation.html">Handling Operating System Variation</a></li><li><a class="toctext" href="../manual/environment-variables.html">Environment Variables</a></li><li><a class="toctext" href="../manual/embedding.html">Embedding Julia</a></li><li><a class="toctext" href="../manual/packages.html">Packages</a></li><li><a class="toctext" href="../manual/profile.html">Profiling</a></li><li><a class="toctext" href="../manual/stacktraces.html">Stack Traces</a></li><li><a class="toctext" href="../manual/performance-tips.html">Performance Tips</a></li><li><a class="toctext" href="../manual/workflow-tips.html">Workflow Tips</a></li><li><a class="toctext" href="../manual/style-guide.html">Style Guide</a></li><li><a class="toctext" href="../manual/faq.html">Frequently Asked Questions</a></li><li><a class="toctext" href="../manual/noteworthy-differences.html">Noteworthy Differences from other Languages</a></li><li><a class="toctext" href="../manual/unicode-input.html">Unicode Input</a></li></ul></li><li><span class="toctext">Standard Library</span><ul><li><a class="toctext" href="../stdlib/base.html">Essentials</a></li><li><a class="toctext" href="../stdlib/collections.html">Collections and Data Structures</a></li><li><a class="toctext" href="../stdlib/math.html">Mathematics</a></li><li><a class="toctext" href="../stdlib/numbers.html">Numbers</a></li><li><a class="toctext" href="../stdlib/strings.html">Strings</a></li><li><a class="toctext" href="../stdlib/arrays.html">Arrays</a></li><li><a class="toctext" href="../stdlib/parallel.html">Tasks and Parallel Computing</a></li><li><a class="toctext" href="../stdlib/linalg.html">Linear Algebra</a></li><li><a class="toctext" href="../stdlib/constants.html">Constants</a></li><li><a class="toctext" href="../stdlib/file.html">Filesystem</a></li><li><a class="toctext" href="../stdlib/io-network.html">I/O and Network</a></li><li><a class="toctext" href="../stdlib/punctuation.html">Punctuation</a></li><li><a class="toctext" href="../stdlib/sort.html">Sorting and Related Functions</a></li><li><a class="toctext" href="../stdlib/pkg.html">Package Manager Functions</a></li><li><a class="toctext" href="../stdlib/dates.html">Dates and Time</a></li><li><a class="toctext" href="../stdlib/iterators.html">Iteration utilities</a></li><li><a class="toctext" href="../stdlib/test.html">Unit Testing</a></li><li><a class="toctext" href="../stdlib/c.html">C Interface</a></li><li><a class="toctext" href="../stdlib/libc.html">C Standard Library</a></li><li><a class="toctext" href="../stdlib/libdl.html">Dynamic Linker</a></li><li><a class="toctext" href="../stdlib/profile.html">Profiling</a></li><li><a class="toctext" href="../stdlib/stacktraces.html">StackTraces</a></li><li><a class="toctext" href="../stdlib/simd-types.html">SIMD Support</a></li></ul></li><li><span class="toctext">Developer Documentation</span><ul><li><a class="toctext" href="reflection.html">Reflection and introspection</a></li><li><span class="toctext">Documentation of Julia's Internals</span><ul><li><a class="toctext" href="init.html">Initialization of the Julia runtime</a></li><li><a class="toctext" href="ast.html">Julia ASTs</a></li><li><a class="toctext" href="types.html">More about types</a></li><li><a class="toctext" href="object.html">Memory layout of Julia Objects</a></li><li><a class="toctext" href="eval.html">Eval of Julia code</a></li><li><a class="toctext" href="callconv.html">Calling Conventions</a></li><li><a class="toctext" href="compiler.html">High-level Overview of the Native-Code Generation Process</a></li><li><a class="toctext" href="functions.html">Julia Functions</a></li><li><a class="toctext" href="cartesian.html">Base.Cartesian</a></li><li><a class="toctext" href="meta.html">Talking to the compiler (the <code>:meta</code> mechanism)</a></li><li><a class="toctext" href="subarrays.html">SubArrays</a></li><li><a class="toctext" href="sysimg.html">System Image Building</a></li><li><a class="toctext" href="llvm.html">Working with LLVM</a></li><li class="current"><a class="toctext" href="stdio.html">printf() and stdio in the Julia runtime</a><ul class="internal"><li><a class="toctext" href="#Libuv-wrappers-for-stdio-1">Libuv wrappers for stdio</a></li><li><a class="toctext" href="#Interface-between-JL_STD*-and-Julia-code-1">Interface between JL_STD* and Julia code</a></li><li><a class="toctext" href="#printf()-during-initialization-1">printf() during initialization</a></li><li><a class="toctext" href="#Legacy-ios.c-library-1">Legacy <code>ios.c</code> library</a></li></ul></li><li><a class="toctext" href="boundscheck.html">Bounds checking</a></li><li><a class="toctext" href="locks.html">Proper maintenance and care of multi-threading locks</a></li><li><a class="toctext" href="offset-arrays.html">Arrays with custom indices</a></li><li><a class="toctext" href="libgit2.html">Base.LibGit2</a></li><li><a class="toctext" href="require.html">Module loading</a></li></ul></li><li><span class="toctext">Developing/debugging Julia's C code</span><ul><li><a class="toctext" href="backtraces.html">Reporting and analyzing crashes (segfaults)</a></li><li><a class="toctext" href="debuggingtips.html">gdb debugging tips</a></li><li><a class="toctext" href="valgrind.html">Using Valgrind with Julia</a></li><li><a class="toctext" href="sanitizers.html">Sanitizer support</a></li></ul></li></ul></li></ul></nav><article id="docs"><header><nav><ul><li>Developer Documentation</li><li>Documentation of Julia's Internals</li><li><a href="stdio.html">printf() and stdio in the Julia runtime</a></li></ul><a class="edit-page" href="https://github.com/JuliaLang/julia/blob/master/doc/src/devdocs/stdio.md"><span class="fa"></span> Edit on GitHub</a></nav><hr/><div id="topbar"><span>printf() and stdio in the Julia runtime</span><a class="fa fa-bars" href="#"></a></div></header><h1><a class="nav-anchor" id="printf()-and-stdio-in-the-Julia-runtime-1" href="#printf()-and-stdio-in-the-Julia-runtime-1">printf() and stdio in the Julia runtime</a></h1><h2><a class="nav-anchor" id="Libuv-wrappers-for-stdio-1" href="#Libuv-wrappers-for-stdio-1">Libuv wrappers for stdio</a></h2><p><code>julia.h</code> defines <a href="http://docs.libuv.org">libuv</a> wrappers for the <code>stdio.h</code> streams:</p><pre><code class="language-c">uv_stream_t *JL_STDIN;
|
||
uv_stream_t *JL_STDOUT;
|
||
uv_stream_t *JL_STDERR;</code></pre><p>... and corresponding output functions:</p><pre><code class="language-c">int jl_printf(uv_stream_t *s, const char *format, ...);
|
||
int jl_vprintf(uv_stream_t *s, const char *format, va_list args);</code></pre><p>These <code>printf</code> functions are used by the <code>.c</code> files in the <code>src/</code> and <code>ui/</code> directories wherever stdio is needed to ensure that output buffering is handled in a unified way.</p><p>In special cases, like signal handlers, where the full libuv infrastructure is too heavy, <code>jl_safe_printf()</code> can be used to <a href="../stdlib/io-network.html#Base.write"><code>write(2)</code></a> directly to <code>STDERR_FILENO</code>:</p><pre><code class="language-c">void jl_safe_printf(const char *str, ...);</code></pre><h2><a class="nav-anchor" id="Interface-between-JL_STD*-and-Julia-code-1" href="#Interface-between-JL_STD*-and-Julia-code-1">Interface between JL_STD* and Julia code</a></h2><p><a href="../stdlib/io-network.html#Base.STDIN"><code>Base.STDIN</code></a>, <a href="../stdlib/io-network.html#Base.STDOUT"><code>Base.STDOUT</code></a> and <a href="../stdlib/io-network.html#Base.STDERR"><code>Base.STDERR</code></a> are bound to the <code>JL_STD*</code> libuv streams defined in the runtime.</p><p>Julia's <code>__init__()</code> function (in <code>base/sysimg.jl</code>) calls <code>reinit_stdio()</code> (in <code>base/stream.jl</code>) to create Julia objects for <a href="../stdlib/io-network.html#Base.STDIN"><code>Base.STDIN</code></a>, <a href="../stdlib/io-network.html#Base.STDOUT"><code>Base.STDOUT</code></a> and <a href="../stdlib/io-network.html#Base.STDERR"><code>Base.STDERR</code></a>.</p><p><code>reinit_stdio()</code> uses <a href="../stdlib/c.html#ccall"><code>ccall</code></a> to retrieve pointers to <code>JL_STD*</code> and calls <code>jl_uv_handle_type()</code> to inspect the type of each stream. It then creates a Julia <code>Base.IOStream</code>, <code>Base.TTY</code> or <code>Base.PipeEndpoint</code> object to represent each stream, e.g.:</p><pre><code class="language-none">$ julia -e 'println(typeof((STDIN, STDOUT, STDERR)))'
|
||
Tuple{Base.TTY,Base.TTY,Base.TTY}
|
||
|
||
$ julia -e 'println(typeof((STDIN, STDOUT, STDERR)))' < /dev/null 2>/dev/null
|
||
Tuple{IOStream,Base.TTY,IOStream}
|
||
|
||
$ echo hello | julia -e 'println(typeof((STDIN, STDOUT, STDERR)))' | cat
|
||
Tuple{Base.PipeEndpoint,Base.PipeEndpoint,Base.TTY}</code></pre><p>The <a href="../stdlib/io-network.html#Base.read"><code>Base.read()</code></a> and <a href="../stdlib/io-network.html#Base.write"><code>Base.write()</code></a> methods for these streams use <a href="../stdlib/c.html#ccall"><code>ccall</code></a> to call libuv wrappers in <code>src/jl_uv.c</code>, e.g.:</p><pre><code class="language-none">stream.jl: function write(s::IO, p::Ptr, nb::Integer)
|
||
-> ccall(:jl_uv_write, ...)
|
||
jl_uv.c: -> int jl_uv_write(uv_stream_t *stream, ...)
|
||
-> uv_write(uvw, stream, buf, ...)</code></pre><h2><a class="nav-anchor" id="printf()-during-initialization-1" href="#printf()-during-initialization-1">printf() during initialization</a></h2><p>The libuv streams relied upon by <code>jl_printf()</code> etc., are not available until midway through initialization of the runtime (see <code>init.c</code>, <code>init_stdio()</code>). Error messages or warnings that need to be printed before this are routed to the standard C library <code>fwrite()</code> function by the following mechanism:</p><p>In <code>sys.c</code>, the <code>JL_STD*</code> stream pointers are statically initialized to integer constants: <code>STD*_FILENO (0, 1 and 2)</code>. In <code>jl_uv.c</code> the <code>jl_uv_puts()</code> function checks its <code>uv_stream_t* stream</code> argument and calls <code>fwrite()</code> if stream is set to <code>STDOUT_FILENO</code> or <code>STDERR_FILENO</code>.</p><p>This allows for uniform use of <code>jl_printf()</code> throughout the runtime regardless of whether or not any particular piece of code is reachable before initialization is complete.</p><h2><a class="nav-anchor" id="Legacy-ios.c-library-1" href="#Legacy-ios.c-library-1">Legacy <code>ios.c</code> library</a></h2><p>The <code>src/support/ios.c</code> library is inherited from <a href="https://github.com/JeffBezanson/femtolisp">femtolisp</a>. It provides cross-platform buffered file IO and in-memory temporary buffers.</p><p><code>ios.c</code> is still used by:</p><ul><li><p><code>src/flisp/*.c</code></p></li><li><p><code>src/dump.c</code> – for serialization file IO and for memory buffers.</p></li><li><p><code>base/iostream.jl</code> – for file IO (see <code>base/fs.jl</code> for libuv equivalent).</p></li></ul><p>Use of <code>ios.c</code> in these modules is mostly self-contained and separated from the libuv I/O system. However, there is <a href="https://github.com/JuliaLang/julia/blob/master/src/flisp/print.c#L654">one place</a> where femtolisp calls through to <code>jl_printf()</code> with a legacy <code>ios_t</code> stream.</p><p>There is a hack in <code>ios.h</code> that makes the <code>ios_t.bm</code> field line up with the <code>uv_stream_t.type</code> and ensures that the values used for <code>ios_t.bm</code> to not overlap with valid <code>UV_HANDLE_TYPE</code> values. This allows <code>uv_stream_t</code> pointers to point to <code>ios_t</code> streams.</p><p>This is needed because <code>jl_printf()</code> caller <code>jl_static_show()</code> is passed an <code>ios_t</code> stream by femtolisp's <code>fl_print()</code> function. Julia's <code>jl_uv_puts()</code> function has special handling for this:</p><pre><code class="language-c">if (stream->type > UV_HANDLE_TYPE_MAX) {
|
||
return ios_write((ios_t*)stream, str, n);
|
||
}</code></pre><footer><hr/><a class="previous" href="llvm.html"><span class="direction">Previous</span><span class="title">Working with LLVM</span></a><a class="next" href="boundscheck.html"><span class="direction">Next</span><span class="title">Bounds checking</span></a></footer></article></body></html>
|