<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Calling C and Fortran Code — Julia Language 0.3.4 documentation</title>
<link href='https://fonts.googleapis.com/css?family=Lato:400,700|Roboto+Slab:400,700|Inconsolata:400,700' rel='stylesheet' type='text/css'>
<link rel="stylesheet" href="../_static/julia.css" type="text/css" />
<link rel="stylesheet" href="../_static/julia.css" type="text/css" />
<link rel="top" title="Julia Language 0.3.4 documentation" href="../index.html"/>
<link rel="next" title="Interacting With Julia" href="interacting-with-julia.html"/>
<link rel="prev" title="Running External Programs" href="running-external-programs.html"/>
<script src="https://cdnjs.cloudflare.com/ajax/libs/modernizr/2.6.2/modernizr.min.js"></script>
</head>
<body class="wy-body-for-nav" role="document">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-nav-search">
<a href="http://julialang.org/"><img src="../_static/julia-logo.svg" class="logo"></a>
<!--
<a href="../index.html" class="fa fa-home"> Julia Language</a>
-->
<div role="search">
<form id ="rtd-search-form" class="wy-form" action="../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="introduction.html">Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="getting-started.html">Getting Started</a><ul>
<li class="toctree-l2"><a class="reference internal" href="getting-started.html#resources">Resources</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="variables.html">Variables</a><ul>
<li class="toctree-l2"><a class="reference internal" href="variables.html#allowed-variable-names">Allowed Variable Names</a></li>
<li class="toctree-l2"><a class="reference internal" href="variables.html#stylistic-conventions">Stylistic Conventions</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="integers-and-floating-point-numbers.html">Integers and Floating-Point Numbers</a><ul>
<li class="toctree-l2"><a class="reference internal" href="integers-and-floating-point-numbers.html#integers">Integers</a></li>
<li class="toctree-l2"><a class="reference internal" href="integers-and-floating-point-numbers.html#floating-point-numbers">Floating-Point Numbers</a></li>
<li class="toctree-l2"><a class="reference internal" href="integers-and-floating-point-numbers.html#arbitrary-precision-arithmetic">Arbitrary Precision Arithmetic</a></li>
<li class="toctree-l2"><a class="reference internal" href="integers-and-floating-point-numbers.html#numeric-literal-coefficients">Numeric Literal Coefficients</a></li>
<li class="toctree-l2"><a class="reference internal" href="integers-and-floating-point-numbers.html#literal-zero-and-one">Literal zero and one</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="mathematical-operations.html">Mathematical Operations and Elementary Functions</a><ul>
<li class="toctree-l2"><a class="reference internal" href="mathematical-operations.html#arithmetic-operators">Arithmetic Operators</a></li>
<li class="toctree-l2"><a class="reference internal" href="mathematical-operations.html#bitwise-operators">Bitwise Operators</a></li>
<li class="toctree-l2"><a class="reference internal" href="mathematical-operations.html#updating-operators">Updating operators</a></li>
<li class="toctree-l2"><a class="reference internal" href="mathematical-operations.html#numeric-comparisons">Numeric Comparisons</a></li>
<li class="toctree-l2"><a class="reference internal" href="mathematical-operations.html#elementary-functions">Elementary Functions</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="complex-and-rational-numbers.html">Complex and Rational Numbers</a><ul>
<li class="toctree-l2"><a class="reference internal" href="complex-and-rational-numbers.html#complex-numbers">Complex Numbers</a></li>
<li class="toctree-l2"><a class="reference internal" href="complex-and-rational-numbers.html#rational-numbers">Rational Numbers</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="strings.html">Strings</a><ul>
<li class="toctree-l2"><a class="reference internal" href="strings.html#characters">Characters</a></li>
<li class="toctree-l2"><a class="reference internal" href="strings.html#string-basics">String Basics</a></li>
<li class="toctree-l2"><a class="reference internal" href="strings.html#unicode-and-utf-8">Unicode and UTF-8</a></li>
<li class="toctree-l2"><a class="reference internal" href="strings.html#interpolation">Interpolation</a></li>
<li class="toctree-l2"><a class="reference internal" href="strings.html#common-operations">Common Operations</a></li>
<li class="toctree-l2"><a class="reference internal" href="strings.html#non-standard-string-literals">Non-Standard String Literals</a></li>
<li class="toctree-l2"><a class="reference internal" href="strings.html#regular-expressions">Regular Expressions</a></li>
<li class="toctree-l2"><a class="reference internal" href="strings.html#id3">Byte Array Literals</a></li>
<li class="toctree-l2"><a class="reference internal" href="strings.html#version-number-literals">Version Number Literals</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="functions.html">Functions</a><ul>
<li class="toctree-l2"><a class="reference internal" href="functions.html#argument-passing-behavior">Argument Passing Behavior</a></li>
<li class="toctree-l2"><a class="reference internal" href="functions.html#the-return-keyword">The <tt class="docutils literal"><span class="pre">return</span></tt> Keyword</a></li>
<li class="toctree-l2"><a class="reference internal" href="functions.html#id1">Operators Are Functions</a></li>
<li class="toctree-l2"><a class="reference internal" href="functions.html#operators-with-special-names">Operators With Special Names</a></li>
<li class="toctree-l2"><a class="reference internal" href="functions.html#anonymous-functions">Anonymous Functions</a></li>
<li class="toctree-l2"><a class="reference internal" href="functions.html#multiple-return-values">Multiple Return Values</a></li>
<li class="toctree-l2"><a class="reference internal" href="functions.html#varargs-functions">Varargs Functions</a></li>
<li class="toctree-l2"><a class="reference internal" href="functions.html#optional-arguments">Optional Arguments</a></li>
<li class="toctree-l2"><a class="reference internal" href="functions.html#keyword-arguments">Keyword Arguments</a></li>
<li class="toctree-l2"><a class="reference internal" href="functions.html#evaluation-scope-of-default-values">Evaluation Scope of Default Values</a></li>
<li class="toctree-l2"><a class="reference internal" href="functions.html#block-syntax-for-function-arguments">Block Syntax for Function Arguments</a></li>
<li class="toctree-l2"><a class="reference internal" href="functions.html#further-reading">Further Reading</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="control-flow.html">Control Flow</a><ul>
<li class="toctree-l2"><a class="reference internal" href="control-flow.html#compound-expressions">Compound Expressions</a></li>
<li class="toctree-l2"><a class="reference internal" href="control-flow.html#conditional-evaluation">Conditional Evaluation</a></li>
<li class="toctree-l2"><a class="reference internal" href="control-flow.html#short-circuit-evaluation">Short-Circuit Evaluation</a></li>
<li class="toctree-l2"><a class="reference internal" href="control-flow.html#repeated-evaluation-loops">Repeated Evaluation: Loops</a></li>
<li class="toctree-l2"><a class="reference internal" href="control-flow.html#exception-handling">Exception Handling</a></li>
<li class="toctree-l2"><a class="reference internal" href="control-flow.html#tasks-aka-coroutines">Tasks (aka Coroutines)</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="variables-and-scoping.html">Scope of Variables</a><ul>
<li class="toctree-l2"><a class="reference internal" href="variables-and-scoping.html#for-loops-and-comprehensions">For Loops and Comprehensions</a></li>
<li class="toctree-l2"><a class="reference internal" href="variables-and-scoping.html#constants">Constants</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="types.html">Types</a><ul>
<li class="toctree-l2"><a class="reference internal" href="types.html#type-declarations">Type Declarations</a></li>
<li class="toctree-l2"><a class="reference internal" href="types.html#abstract-types">Abstract Types</a></li>
<li class="toctree-l2"><a class="reference internal" href="types.html#bits-types">Bits Types</a></li>
<li class="toctree-l2"><a class="reference internal" href="types.html#composite-types">Composite Types</a></li>
<li class="toctree-l2"><a class="reference internal" href="types.html#immutable-composite-types">Immutable Composite Types</a></li>
<li class="toctree-l2"><a class="reference internal" href="types.html#declared-types">Declared Types</a></li>
<li class="toctree-l2"><a class="reference internal" href="types.html#tuple-types">Tuple Types</a></li>
<li class="toctree-l2"><a class="reference internal" href="types.html#type-unions">Type Unions</a></li>
<li class="toctree-l2"><a class="reference internal" href="types.html#man-parametric-types">Parametric Types</a></li>
<li class="toctree-l2"><a class="reference internal" href="types.html#type-aliases">Type Aliases</a></li>
<li class="toctree-l2"><a class="reference internal" href="types.html#operations-on-types">Operations on Types</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="methods.html">Methods</a><ul>
<li class="toctree-l2"><a class="reference internal" href="methods.html#defining-methods">Defining Methods</a></li>
<li class="toctree-l2"><a class="reference internal" href="methods.html#method-ambiguities">Method Ambiguities</a></li>
<li class="toctree-l2"><a class="reference internal" href="methods.html#parametric-methods">Parametric Methods</a></li>
<li class="toctree-l2"><a class="reference internal" href="methods.html#note-on-optional-and-keyword-arguments">Note on Optional and keyword Arguments</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="constructors.html">Constructors</a><ul>
<li class="toctree-l2"><a class="reference internal" href="constructors.html#outer-constructor-methods">Outer Constructor Methods</a></li>
<li class="toctree-l2"><a class="reference internal" href="constructors.html#inner-constructor-methods">Inner Constructor Methods</a></li>
<li class="toctree-l2"><a class="reference internal" href="constructors.html#incomplete-initialization">Incomplete Initialization</a></li>
<li class="toctree-l2"><a class="reference internal" href="constructors.html#parametric-constructors">Parametric Constructors</a></li>
<li class="toctree-l2"><a class="reference internal" href="constructors.html#case-study-rational">Case Study: Rational</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="conversion-and-promotion.html">Conversion and Promotion</a><ul>
<li class="toctree-l2"><a class="reference internal" href="conversion-and-promotion.html#conversion">Conversion</a></li>
<li class="toctree-l2"><a class="reference internal" href="conversion-and-promotion.html#promotion">Promotion</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="modules.html">Modules</a><ul>
<li class="toctree-l2"><a class="reference internal" href="modules.html#summary-of-module-usage">Summary of module usage</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="metaprogramming.html">Metaprogramming</a><ul>
<li class="toctree-l2"><a class="reference internal" href="metaprogramming.html#expressions-and-eval">Expressions and Eval</a></li>
<li class="toctree-l2"><a class="reference internal" href="metaprogramming.html#macros">Macros</a></li>
<li class="toctree-l2"><a class="reference internal" href="metaprogramming.html#reflection">Reflection</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="arrays.html">Multi-dimensional Arrays</a><ul>
<li class="toctree-l2"><a class="reference internal" href="arrays.html#arrays">Arrays</a></li>
<li class="toctree-l2"><a class="reference internal" href="arrays.html#sparse-matrices">Sparse Matrices</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="linear-algebra.html">Linear algebra</a><ul>
<li class="toctree-l2"><a class="reference internal" href="linear-algebra.html#matrix-factorizations">Matrix factorizations</a></li>
<li class="toctree-l2"><a class="reference internal" href="linear-algebra.html#special-matrices">Special matrices</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="networking-and-streams.html">Networking and Streams</a><ul>
<li class="toctree-l2"><a class="reference internal" href="networking-and-streams.html#basic-stream-i-o">Basic Stream I/O</a></li>
<li class="toctree-l2"><a class="reference internal" href="networking-and-streams.html#text-i-o">Text I/O</a></li>
<li class="toctree-l2"><a class="reference internal" href="networking-and-streams.html#working-with-files">Working with Files</a></li>
<li class="toctree-l2"><a class="reference internal" href="networking-and-streams.html#a-simple-tcp-example">A simple TCP example</a></li>
<li class="toctree-l2"><a class="reference internal" href="networking-and-streams.html#resolving-ip-addresses">Resolving IP Addresses</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="parallel-computing.html">Parallel Computing</a><ul>
<li class="toctree-l2"><a class="reference internal" href="parallel-computing.html#data-movement">Data Movement</a></li>
<li class="toctree-l2"><a class="reference internal" href="parallel-computing.html#parallel-map-and-loops">Parallel Map and Loops</a></li>
<li class="toctree-l2"><a class="reference internal" href="parallel-computing.html#synchronization-with-remote-references">Synchronization With Remote References</a></li>
<li class="toctree-l2"><a class="reference internal" href="parallel-computing.html#scheduling">Scheduling</a></li>
<li class="toctree-l2"><a class="reference internal" href="parallel-computing.html#distributed-arrays">Distributed Arrays</a></li>
<li class="toctree-l2"><a class="reference internal" href="parallel-computing.html#constructing-distributed-arrays">Constructing Distributed Arrays</a></li>
<li class="toctree-l2"><a class="reference internal" href="parallel-computing.html#distributed-array-operations">Distributed Array Operations</a></li>
<li class="toctree-l2"><a class="reference internal" href="parallel-computing.html#shared-arrays-experimental">Shared Arrays (Experimental)</a></li>
<li class="toctree-l2"><a class="reference internal" href="parallel-computing.html#clustermanagers">ClusterManagers</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="running-external-programs.html">Running External Programs</a><ul>
<li class="toctree-l2"><a class="reference internal" href="running-external-programs.html#interpolation">Interpolation</a></li>
<li class="toctree-l2"><a class="reference internal" href="running-external-programs.html#quoting">Quoting</a></li>
<li class="toctree-l2"><a class="reference internal" href="running-external-programs.html#pipelines">Pipelines</a></li>
</ul>
</li>
<li class="toctree-l1 current"><a class="current reference internal" href="">Calling C and Fortran Code</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#mapping-c-types-to-julia">Mapping C Types to Julia</a></li>
<li class="toctree-l2"><a class="reference internal" href="#accessing-data-through-a-pointer">Accessing Data through a Pointer</a></li>
<li class="toctree-l2"><a class="reference internal" href="#passing-pointers-for-modifying-inputs">Passing Pointers for Modifying Inputs</a></li>
<li class="toctree-l2"><a class="reference internal" href="#garbage-collection-safety">Garbage Collection Safety</a></li>
<li class="toctree-l2"><a class="reference internal" href="#non-constant-function-specifications">Non-constant Function Specifications</a></li>
<li class="toctree-l2"><a class="reference internal" href="#indirect-calls">Indirect Calls</a></li>
<li class="toctree-l2"><a class="reference internal" href="#calling-convention">Calling Convention</a></li>
<li class="toctree-l2"><a class="reference internal" href="#accessing-global-variables">Accessing Global Variables</a></li>
<li class="toctree-l2"><a class="reference internal" href="#passing-julia-callback-functions-to-c">Passing Julia Callback Functions to C</a></li>
<li class="toctree-l2"><a class="reference internal" href="#c">C++</a></li>
<li class="toctree-l2"><a class="reference internal" href="#handling-platform-variations">Handling Platform Variations</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="interacting-with-julia.html">Interacting With Julia</a><ul>
<li class="toctree-l2"><a class="reference internal" href="interacting-with-julia.html#the-different-prompt-modes">The different prompt modes</a></li>
<li class="toctree-l2"><a class="reference internal" href="interacting-with-julia.html#key-bindings">Key bindings</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="embedding.html">Embedding Julia</a><ul>
<li class="toctree-l2"><a class="reference internal" href="embedding.html#high-level-embedding">High-Level Embedding</a></li>
<li class="toctree-l2"><a class="reference internal" href="embedding.html#converting-types">Converting Types</a></li>
<li class="toctree-l2"><a class="reference internal" href="embedding.html#calling-julia-functions">Calling Julia Functions</a></li>
<li class="toctree-l2"><a class="reference internal" href="embedding.html#memory-management">Memory Management</a></li>
<li class="toctree-l2"><a class="reference internal" href="embedding.html#working-with-arrays">Working with Arrays</a></li>
<li class="toctree-l2"><a class="reference internal" href="embedding.html#exceptions">Exceptions</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="packages.html">Packages</a><ul>
<li class="toctree-l2"><a class="reference internal" href="packages.html#package-status">Package Status</a></li>
<li class="toctree-l2"><a class="reference internal" href="packages.html#adding-and-removing-packages">Adding and Removing Packages</a></li>
<li class="toctree-l2"><a class="reference internal" href="packages.html#installing-unregistered-packages">Installing Unregistered Packages</a></li>
<li class="toctree-l2"><a class="reference internal" href="packages.html#updating-packages">Updating Packages</a></li>
<li class="toctree-l2"><a class="reference internal" href="packages.html#checkout-pin-and-free">Checkout, Pin and Free</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="packages.html#package-development">Package Development</a><ul>
<li class="toctree-l2"><a class="reference internal" href="packages.html#initial-setup">Initial Setup</a></li>
<li class="toctree-l2"><a class="reference internal" href="packages.html#generating-a-new-package">Generating a New Package</a></li>
<li class="toctree-l2"><a class="reference internal" href="packages.html#making-your-package-available">Making Your Package Available</a></li>
<li class="toctree-l2"><a class="reference internal" href="packages.html#publishing-your-package">Publishing Your Package</a></li>
<li class="toctree-l2"><a class="reference internal" href="packages.html#tagging-package-versions">Tagging Package Versions</a></li>
<li class="toctree-l2"><a class="reference internal" href="packages.html#fixing-package-requirements">Fixing Package Requirements</a></li>
<li class="toctree-l2"><a class="reference internal" href="packages.html#man-package-requirements">Requirements Specification</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="performance-tips.html">Performance Tips</a><ul>
<li class="toctree-l2"><a class="reference internal" href="performance-tips.html#avoid-global-variables">Avoid global variables</a></li>
<li class="toctree-l2"><a class="reference internal" href="performance-tips.html#measure-performance-with-time-and-pay-attention-to-memory-allocation">Measure performance with <tt class="docutils literal"><span class="pre">@time</span></tt> and pay attention to memory allocation</a></li>
<li class="toctree-l2"><a class="reference internal" href="performance-tips.html#tools">Tools</a></li>
<li class="toctree-l2"><a class="reference internal" href="performance-tips.html#avoid-containers-with-abstract-type-parameters">Avoid containers with abstract type parameters</a></li>
<li class="toctree-l2"><a class="reference internal" href="performance-tips.html#type-declarations">Type declarations</a></li>
<li class="toctree-l2"><a class="reference internal" href="performance-tips.html#break-functions-into-multiple-definitions">Break functions into multiple definitions</a></li>
<li class="toctree-l2"><a class="reference internal" href="performance-tips.html#write-type-stable-functions">Write “type-stable” functions</a></li>
<li class="toctree-l2"><a class="reference internal" href="performance-tips.html#avoid-changing-the-type-of-a-variable">Avoid changing the type of a variable</a></li>
<li class="toctree-l2"><a class="reference internal" href="performance-tips.html#separate-kernel-functions">Separate kernel functions</a></li>
<li class="toctree-l2"><a class="reference internal" href="performance-tips.html#access-arrays-in-memory-order-along-columns">Access arrays in memory order, along columns</a></li>
<li class="toctree-l2"><a class="reference internal" href="performance-tips.html#pre-allocating-outputs">Pre-allocating outputs</a></li>
<li class="toctree-l2"><a class="reference internal" href="performance-tips.html#avoid-string-interpolation-for-i-o">Avoid string interpolation for I/O</a></li>
<li class="toctree-l2"><a class="reference internal" href="performance-tips.html#fix-deprecation-warnings">Fix deprecation warnings</a></li>
<li class="toctree-l2"><a class="reference internal" href="performance-tips.html#tweaks">Tweaks</a></li>
<li class="toctree-l2"><a class="reference internal" href="performance-tips.html#performance-annotations">Performance Annotations</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="style-guide.html">Style Guide</a><ul>
<li class="toctree-l2"><a class="reference internal" href="style-guide.html#write-functions-not-just-scripts">Write functions, not just scripts</a></li>
<li class="toctree-l2"><a class="reference internal" href="style-guide.html#avoid-writing-overly-specific-types">Avoid writing overly-specific types</a></li>
<li class="toctree-l2"><a class="reference internal" href="style-guide.html#handle-excess-argument-diversity-in-the-caller">Handle excess argument diversity in the caller</a></li>
<li class="toctree-l2"><a class="reference internal" href="style-guide.html#append-to-names-of-functions-that-modify-their-arguments">Append <cite>!</cite> to names of functions that modify their arguments</a></li>
<li class="toctree-l2"><a class="reference internal" href="style-guide.html#avoid-strange-type-unions">Avoid strange type Unions</a></li>
<li class="toctree-l2"><a class="reference internal" href="style-guide.html#try-to-avoid-nullable-fields">Try to avoid nullable fields</a></li>
<li class="toctree-l2"><a class="reference internal" href="style-guide.html#avoid-elaborate-container-types">Avoid elaborate container types</a></li>
<li class="toctree-l2"><a class="reference internal" href="style-guide.html#avoid-underscores-in-names">Avoid underscores in names</a></li>
<li class="toctree-l2"><a class="reference internal" href="style-guide.html#don-t-overuse-try-catch">Don’t overuse try-catch</a></li>
<li class="toctree-l2"><a class="reference internal" href="style-guide.html#don-t-parenthesize-conditions">Don’t parenthesize conditions</a></li>
<li class="toctree-l2"><a class="reference internal" href="style-guide.html#don-t-overuse">Don’t overuse ...</a></li>
<li class="toctree-l2"><a class="reference internal" href="style-guide.html#don-t-use-unnecessary-static-parameters">Don’t use unnecessary static parameters</a></li>
<li class="toctree-l2"><a class="reference internal" href="style-guide.html#avoid-confusion-about-whether-something-is-an-instance-or-a-type">Avoid confusion about whether something is an instance or a type</a></li>
<li class="toctree-l2"><a class="reference internal" href="style-guide.html#don-t-overuse-macros">Don’t overuse macros</a></li>
<li class="toctree-l2"><a class="reference internal" href="style-guide.html#don-t-expose-unsafe-operations-at-the-interface-level">Don’t expose unsafe operations at the interface level</a></li>
<li class="toctree-l2"><a class="reference internal" href="style-guide.html#don-t-overload-methods-of-base-container-types">Don’t overload methods of base container types</a></li>
<li class="toctree-l2"><a class="reference internal" href="style-guide.html#be-careful-with-type-equality">Be careful with type equality</a></li>
<li class="toctree-l2"><a class="reference internal" href="style-guide.html#do-not-write-x-f-x">Do not write <tt class="docutils literal"><span class="pre">x->f(x)</span></tt></a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="faq.html">Frequently Asked Questions</a><ul>
<li class="toctree-l2"><a class="reference internal" href="faq.html#sessions-and-the-repl">Sessions and the REPL</a></li>
<li class="toctree-l2"><a class="reference internal" href="faq.html#functions">Functions</a></li>
<li class="toctree-l2"><a class="reference internal" href="faq.html#types-type-declarations-and-constructors">Types, type declarations, and constructors</a></li>
<li class="toctree-l2"><a class="reference internal" href="faq.html#nothingness-and-missing-values">Nothingness and missing values</a></li>
<li class="toctree-l2"><a class="reference internal" href="faq.html#julia-releases">Julia Releases</a></li>
<li class="toctree-l2"><a class="reference internal" href="faq.html#developing-julia">Developing Julia</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="noteworthy-differences.html">Noteworthy Differences from other Languages</a><ul>
<li class="toctree-l2"><a class="reference internal" href="noteworthy-differences.html#noteworthy-differences-from-matlab">Noteworthy differences from MATLAB</a></li>
<li class="toctree-l2"><a class="reference internal" href="noteworthy-differences.html#noteworthy-differences-from-r">Noteworthy differences from R</a></li>
<li class="toctree-l2"><a class="reference internal" href="noteworthy-differences.html#noteworthy-differences-from-python">Noteworthy differences from Python</a></li>
</ul>
</li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../stdlib/base.html">The Standard Library</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#introduction">Introduction</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#getting-around">Getting Around</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#all-objects">All Objects</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#types">Types</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#generic-functions">Generic Functions</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#syntax">Syntax</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#iteration">Iteration</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#general-collections">General Collections</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#iterable-collections">Iterable Collections</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#indexable-collections">Indexable Collections</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#associative-collections">Associative Collections</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#set-like-collections">Set-Like Collections</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#dequeues">Dequeues</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#strings">Strings</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#i-o">I/O</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#network-i-o">Network I/O</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#text-i-o">Text I/O</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#multimedia-i-o">Multimedia I/O</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#memory-mapped-i-o">Memory-mapped I/O</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#standard-numeric-types">Standard Numeric Types</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#mathematical-operators">Mathematical Operators</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#mathematical-functions">Mathematical Functions</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#data-formats">Data Formats</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#numbers">Numbers</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#bigfloats">BigFloats</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#random-numbers">Random Numbers</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#arrays">Arrays</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#combinatorics">Combinatorics</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#statistics">Statistics</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#signal-processing">Signal Processing</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#numerical-integration">Numerical Integration</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#parallel-computing">Parallel Computing</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#distributed-arrays">Distributed Arrays</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#shared-arrays-experimental-unix-only-feature">Shared Arrays (Experimental, UNIX-only feature)</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#system">System</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#c-interface">C Interface</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#errors">Errors</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#tasks">Tasks</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#events">Events</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#reflection">Reflection</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#internals">Internals</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../stdlib/sparse.html">Sparse Matrices</a></li>
<li class="toctree-l1"><a class="reference internal" href="../stdlib/linalg.html">Linear Algebra</a></li>
<li class="toctree-l1"><a class="reference internal" href="../stdlib/linalg.html#module-Base.LinAlg.BLAS">BLAS Functions</a></li>
<li class="toctree-l1"><a class="reference internal" href="../stdlib/constants.html">Constants</a></li>
<li class="toctree-l1"><a class="reference internal" href="../stdlib/file.html">Filesystem</a></li>
<li class="toctree-l1"><a class="reference internal" href="../stdlib/punctuation.html">Punctuation</a></li>
<li class="toctree-l1"><a class="reference internal" href="../stdlib/sort.html">Sorting and Related Functions</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/sort.html#sorting-functions">Sorting Functions</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/sort.html#order-related-functions">Order-Related Functions</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/sort.html#sorting-algorithms">Sorting Algorithms</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../stdlib/pkg.html">Package Manager Functions</a></li>
<li class="toctree-l1"><a class="reference internal" href="../stdlib/collections.html">Collections and Data Structures</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/collections.html#priorityqueue">PriorityQueue</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/collections.html#heap-functions">Heap Functions</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../stdlib/graphics.html">Graphics</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/graphics.html#geometry">Geometry</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../stdlib/test.html">Unit and Functional Testing</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/test.html#overview">Overview</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/test.html#handlers">Handlers</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/test.html#macros">Macros</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/test.html#functions">Functions</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../stdlib/test.html#testing-base-julia">Testing Base Julia</a></li>
<li class="toctree-l1"><a class="reference internal" href="../stdlib/profile.html">Profiling</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/profile.html#basic-usage">Basic usage</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/profile.html#accumulation-and-clearing">Accumulation and clearing</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/profile.html#options-for-controlling-the-display-of-profile-results">Options for controlling the display of profile results</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/profile.html#configuration">Configuration</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/profile.html#function-reference">Function reference</a></li>
</ul>
</li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../devdocs/julia.html">Documentation of Julia’s Internals</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../devdocs/cartesian.html">Base.Cartesian</a></li>
<li class="toctree-l2"><a class="reference internal" href="../devdocs/sysimg.html">System Image Building</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../devdocs/C.html">Developing/debugging Julia’s C code</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../devdocs/backtraces.html">Reporting and analyzing crashes (segfaults)</a></li>
<li class="toctree-l2"><a class="reference internal" href="../devdocs/debuggingtips.html">gdb debugging tips</a></li>
</ul>
</li>
</ul>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../index.html">Julia Language</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="../index.html">Docs</a> »</li>
<li>Calling C and Fortran Code</li>
<li class="wy-breadcrumbs-aside">
<a href="../_sources/manual/calling-c-and-fortran-code.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document">
<div class="section" id="calling-c-and-fortran-code">
<span id="man-calling-c-and-fortran-code"></span><h1>Calling C and Fortran Code<a class="headerlink" href="#calling-c-and-fortran-code" title="Permalink to this headline">¶</a></h1>
<p>Though most code can be written in Julia, there are many high-quality,
mature libraries for numerical computing already written in C and
Fortran. To allow easy use of this existing code, Julia makes it simple
and efficient to call C and Fortran functions. Julia has a “no
boilerplate” philosophy: functions can be called directly from Julia
without any “glue” code, code generation, or compilation — even from the
interactive prompt. This is accomplished just by making an appropriate call
with <tt class="docutils literal"><span class="pre">ccall</span></tt> syntax, which looks like an ordinary function call.</p>
<p>The code to be called must be available as a shared library. Most C and
Fortran libraries ship compiled as shared libraries already, but if you
are compiling the code yourself using GCC (or Clang), you will need to
use the <tt class="docutils literal"><span class="pre">-shared</span></tt> and <tt class="docutils literal"><span class="pre">-fPIC</span></tt> options. The machine instructions
generated by Julia’s JIT are the same as a native C call would be, so
the resulting overhead is the same as calling a library function from C
code. (Non-library function calls in both C and Julia can be inlined and
thus may have even less overhead than calls to shared library functions.
When both libraries and executables are generated by LLVM, it is
possible to perform whole-program optimizations that can even optimize
across this boundary, but Julia does not yet support that. In the
future, however, it may do so, yielding even greater performance gains.)</p>
<p>Shared libraries and functions are referenced by a tuple of the
form <tt class="docutils literal"><span class="pre">(:function,</span> <span class="pre">"library")</span></tt> or <tt class="docutils literal"><span class="pre">("function",</span> <span class="pre">"library")</span></tt> where <tt class="docutils literal"><span class="pre">function</span></tt>
is the C-exported function name. <tt class="docutils literal"><span class="pre">library</span></tt> refers to the shared library
name: shared libraries available in the (platform-specific) load path
will be resolved by name, and if necessary a direct path may be specified.</p>
<p>A function name may be used alone in place of the tuple (just
<tt class="docutils literal"><span class="pre">:function</span></tt> or <tt class="docutils literal"><span class="pre">"function"</span></tt>). In this case the name is resolved within
the current process. This form can be used to call C library functions,
functions in the Julia runtime, or functions in an application linked to
Julia.</p>
<p>By default, Fortran compilers <a class="reference external" href="http://en.wikipedia.org/wiki/Name_mangling#Name_mangling_in_Fortran">generate mangled names</a>
(for example, converting function names to lowercase or uppercase,
often appending an underscore), and so to call a Fortran function via
<tt class="docutils literal"><span class="pre">ccall</span></tt> you must pass the mangled identifier corresponding to the rule
followed by your Fortran compiler. Also, when calling a Fortran
function, all inputs must be passed by reference.</p>
<p>Finally, you can use <tt class="docutils literal"><span class="pre">ccall</span></tt> to actually generate a call to the
library function. Arguments to <tt class="docutils literal"><span class="pre">ccall</span></tt> are as follows:</p>
<ol class="arabic simple">
<li>(:function, “library”) pair (must be a constant, but see below).</li>
<li>Return type, which may be any bits type, including <tt class="docutils literal"><span class="pre">Int32</span></tt>,
<tt class="docutils literal"><span class="pre">Int64</span></tt>, <tt class="docutils literal"><span class="pre">Float64</span></tt>, or <tt class="docutils literal"><span class="pre">Ptr{T}</span></tt> for any type parameter <tt class="docutils literal"><span class="pre">T</span></tt>,
indicating a pointer to values of type <tt class="docutils literal"><span class="pre">T</span></tt>, or <tt class="docutils literal"><span class="pre">Ptr{Void}</span></tt> for
<tt class="docutils literal"><span class="pre">void*</span></tt> “untyped pointer” values.</li>
<li>A tuple of input types, like those allowed for the return type.
The input types must be written as a literal tuple, not a tuple-valued
variable or expression.</li>
<li>The following arguments, if any, are the actual argument values
passed to the function.</li>
</ol>
<p>As a complete but simple example, the following calls the <tt class="docutils literal"><span class="pre">clock</span></tt>
function from the standard C library:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="n">julia</span><span class="o">></span> <span class="n">t</span> <span class="o">=</span> <span class="k">ccall</span><span class="p">(</span> <span class="p">(:</span><span class="n">clock</span><span class="p">,</span> <span class="s">"libc"</span><span class="p">),</span> <span class="kt">Int32</span><span class="p">,</span> <span class="p">())</span>
<span class="mi">2292761</span>
<span class="n">julia</span><span class="o">></span> <span class="n">t</span>
<span class="mi">2292761</span>
<span class="n">julia</span><span class="o">></span> <span class="nb">typeof</span><span class="p">(</span><span class="n">ans</span><span class="p">)</span>
<span class="kt">Int32</span>
</pre></div>
</div>
<p><tt class="docutils literal"><span class="pre">clock</span></tt> takes no arguments and returns an <tt class="docutils literal"><span class="pre">Int32</span></tt>. One common gotcha
is that a 1-tuple must be written with a trailing comma. For
example, to call the <tt class="docutils literal"><span class="pre">getenv</span></tt> function to get a pointer to the value
of an environment variable, one makes a call like this:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="n">julia</span><span class="o">></span> <span class="n">path</span> <span class="o">=</span> <span class="k">ccall</span><span class="p">(</span> <span class="p">(:</span><span class="n">getenv</span><span class="p">,</span> <span class="s">"libc"</span><span class="p">),</span> <span class="n">Ptr</span><span class="p">{</span><span class="kt">Uint8</span><span class="p">},</span> <span class="p">(</span><span class="n">Ptr</span><span class="p">{</span><span class="kt">Uint8</span><span class="p">},),</span> <span class="s">"SHELL"</span><span class="p">)</span>
<span class="n">Ptr</span><span class="p">{</span><span class="kt">Uint8</span><span class="p">}</span> <span class="p">@</span><span class="mh">0x00007fff5fbffc45</span>
<span class="n">julia</span><span class="o">></span> <span class="n">bytestring</span><span class="p">(</span><span class="n">path</span><span class="p">)</span>
<span class="s">"/bin/bash"</span>
</pre></div>
</div>
<p>Note that the argument type tuple must be written as <tt class="docutils literal"><span class="pre">(Ptr{Uint8},)</span></tt>,
rather than <tt class="docutils literal"><span class="pre">(Ptr{Uint8})</span></tt>. This is because <tt class="docutils literal"><span class="pre">(Ptr{Uint8})</span></tt> is just
<tt class="docutils literal"><span class="pre">Ptr{Uint8}</span></tt>, rather than a 1-tuple containing <tt class="docutils literal"><span class="pre">Ptr{Uint8}</span></tt>:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="n">julia</span><span class="o">></span> <span class="p">(</span><span class="n">Ptr</span><span class="p">{</span><span class="kt">Uint8</span><span class="p">})</span>
<span class="n">Ptr</span><span class="p">{</span><span class="kt">Uint8</span><span class="p">}</span>
<span class="n">julia</span><span class="o">></span> <span class="p">(</span><span class="n">Ptr</span><span class="p">{</span><span class="kt">Uint8</span><span class="p">},)</span>
<span class="p">(</span><span class="n">Ptr</span><span class="p">{</span><span class="kt">Uint8</span><span class="p">},)</span>
</pre></div>
</div>
<p>In practice, especially when providing reusable functionality, one
generally wraps <tt class="docutils literal"><span class="pre">ccall</span></tt> uses in Julia functions that set up arguments
and then check for errors in whatever manner the C or Fortran function
indicates them, propagating to the Julia caller as exceptions. This is
especially important since C and Fortran APIs are notoriously
inconsistent about how they indicate error conditions. For example, the
<tt class="docutils literal"><span class="pre">getenv</span></tt> C library function is wrapped in the following Julia function
in
<a class="reference external" href="https://github.com/JuliaLang/julia/blob/master/base/env.jl">env.jl</a>:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="k">function</span><span class="nf"> getenv</span><span class="p">(</span><span class="n">var</span><span class="p">::</span><span class="n">String</span><span class="p">)</span>
<span class="n">val</span> <span class="o">=</span> <span class="k">ccall</span><span class="p">(</span> <span class="p">(:</span><span class="n">getenv</span><span class="p">,</span> <span class="s">"libc"</span><span class="p">),</span>
<span class="n">Ptr</span><span class="p">{</span><span class="kt">Uint8</span><span class="p">},</span> <span class="p">(</span><span class="n">Ptr</span><span class="p">{</span><span class="kt">Uint8</span><span class="p">},),</span> <span class="n">var</span><span class="p">)</span>
<span class="k">if</span> <span class="n">val</span> <span class="o">==</span> <span class="n">C_NULL</span>
<span class="nb">error</span><span class="p">(</span><span class="s">"getenv: undefined variable: "</span><span class="p">,</span> <span class="n">var</span><span class="p">)</span>
<span class="k">end</span>
<span class="n">bytestring</span><span class="p">(</span><span class="n">val</span><span class="p">)</span>
<span class="k">end</span>
</pre></div>
</div>
<p>The C <tt class="docutils literal"><span class="pre">getenv</span></tt> function indicates an error by returning <tt class="docutils literal"><span class="pre">NULL</span></tt>, but
other standard C functions indicate errors in various different ways,
including by returning -1, 0, 1 and other special values. This wrapper
throws an exception clearly indicating the problem if the caller tries
to get a non-existent environment variable:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="n">julia</span><span class="o">></span> <span class="n">getenv</span><span class="p">(</span><span class="s">"SHELL"</span><span class="p">)</span>
<span class="s">"/bin/bash"</span>
<span class="n">julia</span><span class="o">></span> <span class="n">getenv</span><span class="p">(</span><span class="s">"FOOBAR"</span><span class="p">)</span>
<span class="n">getenv</span><span class="p">:</span> <span class="n">undefined</span> <span class="n">variable</span><span class="p">:</span> <span class="n">FOOBAR</span>
</pre></div>
</div>
<p>Here is a slightly more complex example that discovers the local
machine’s hostname:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="k">function</span><span class="nf"> gethostname</span><span class="p">()</span>
<span class="n">hostname</span> <span class="o">=</span> <span class="n">Array</span><span class="p">(</span><span class="kt">Uint8</span><span class="p">,</span> <span class="mi">128</span><span class="p">)</span>
<span class="k">ccall</span><span class="p">(</span> <span class="p">(:</span><span class="n">gethostname</span><span class="p">,</span> <span class="s">"libc"</span><span class="p">),</span> <span class="kt">Int32</span><span class="p">,</span>
<span class="p">(</span><span class="n">Ptr</span><span class="p">{</span><span class="kt">Uint8</span><span class="p">},</span> <span class="kt">Uint</span><span class="p">),</span>
<span class="n">hostname</span><span class="p">,</span> <span class="n">length</span><span class="p">(</span><span class="n">hostname</span><span class="p">))</span>
<span class="k">return</span> <span class="n">bytestring</span><span class="p">(</span><span class="nb">convert</span><span class="p">(</span><span class="n">Ptr</span><span class="p">{</span><span class="kt">Uint8</span><span class="p">},</span> <span class="n">hostname</span><span class="p">))</span>
<span class="k">end</span>
</pre></div>
</div>
<p>This example first allocates an array of bytes, then calls the C library
function <tt class="docutils literal"><span class="pre">gethostname</span></tt> to fill the array in with the hostname, takes a
pointer to the hostname buffer, and converts the pointer to a Julia
string, assuming that it is a NUL-terminated C string. It is common for
C libraries to use this pattern of requiring the caller to allocate
memory to be passed to the callee and filled in. Allocation of memory
from Julia like this is generally accomplished by creating an
uninitialized array and passing a pointer to its data to the C function.</p>
<p>A prefix <tt class="docutils literal"><span class="pre">&</span></tt> is used to indicate that a pointer to a scalar argument
should be passed instead of the scalar value itself (required for all
Fortran function arguments, as noted above). The following
example computes a dot product using a BLAS function.</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="k">function</span><span class="nf"> compute_dot</span><span class="p">(</span><span class="n">DX</span><span class="p">::</span><span class="n">Vector</span><span class="p">{</span><span class="kt">Float64</span><span class="p">},</span> <span class="n">DY</span><span class="p">::</span><span class="n">Vector</span><span class="p">{</span><span class="kt">Float64</span><span class="p">})</span>
<span class="nb">assert</span><span class="p">(</span><span class="n">length</span><span class="p">(</span><span class="n">DX</span><span class="p">)</span> <span class="o">==</span> <span class="n">length</span><span class="p">(</span><span class="n">DY</span><span class="p">))</span>
<span class="n">n</span> <span class="o">=</span> <span class="n">length</span><span class="p">(</span><span class="n">DX</span><span class="p">)</span>
<span class="n">incx</span> <span class="o">=</span> <span class="n">incy</span> <span class="o">=</span> <span class="mi">1</span>
<span class="n">product</span> <span class="o">=</span> <span class="k">ccall</span><span class="p">(</span> <span class="p">(:</span><span class="n">ddot_</span><span class="p">,</span> <span class="s">"libLAPACK"</span><span class="p">),</span>
<span class="kt">Float64</span><span class="p">,</span>
<span class="p">(</span><span class="n">Ptr</span><span class="p">{</span><span class="kt">Int32</span><span class="p">},</span> <span class="n">Ptr</span><span class="p">{</span><span class="kt">Float64</span><span class="p">},</span> <span class="n">Ptr</span><span class="p">{</span><span class="kt">Int32</span><span class="p">},</span> <span class="n">Ptr</span><span class="p">{</span><span class="kt">Float64</span><span class="p">},</span> <span class="n">Ptr</span><span class="p">{</span><span class="kt">Int32</span><span class="p">}),</span>
<span class="o">&</span><span class="n">n</span><span class="p">,</span> <span class="n">DX</span><span class="p">,</span> <span class="o">&</span><span class="n">incx</span><span class="p">,</span> <span class="n">DY</span><span class="p">,</span> <span class="o">&</span><span class="n">incy</span><span class="p">)</span>
<span class="k">return</span> <span class="n">product</span>
<span class="k">end</span>
</pre></div>
</div>
<p>The meaning of prefix <tt class="docutils literal"><span class="pre">&</span></tt> is not quite the same as in C. In
particular, any changes to the referenced variables will not be visible
in Julia. However, it will
never cause any harm for called functions to attempt such modifications
(that is, writing through the passed pointers). Since this <tt class="docutils literal"><span class="pre">&</span></tt> is not
a real address operator, it may be used with any syntax, such as
<tt class="docutils literal"><span class="pre">&0</span></tt> or <tt class="docutils literal"><span class="pre">&f(x)</span></tt>.</p>
<p>Note that no C header files are used anywhere in the process. Currently,
it is not possible to pass structs and other non-primitive types from
Julia to C libraries. However, C functions that generate and use opaque
struct types by passing pointers to them can return such values
to Julia as <tt class="docutils literal"><span class="pre">Ptr{Void}</span></tt>, which can then be passed to other C functions
as <tt class="docutils literal"><span class="pre">Ptr{Void}</span></tt>. Memory allocation and deallocation of such objects
must be handled by calls to the appropriate cleanup routines in the
libraries being used, just like in any C program.</p>
<div class="section" id="mapping-c-types-to-julia">
<h2>Mapping C Types to Julia<a class="headerlink" href="#mapping-c-types-to-julia" title="Permalink to this headline">¶</a></h2>
<p>Julia automatically inserts calls to the <tt class="docutils literal"><span class="pre">convert</span></tt> function to convert
each argument to the specified type. For example, the following call:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="k">ccall</span><span class="p">(</span> <span class="p">(:</span><span class="n">foo</span><span class="p">,</span> <span class="s">"libfoo"</span><span class="p">),</span> <span class="n">Void</span><span class="p">,</span> <span class="p">(</span><span class="kt">Int32</span><span class="p">,</span> <span class="kt">Float64</span><span class="p">),</span>
<span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">)</span>
</pre></div>
</div>
<p>will behave as if the following were written:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="k">ccall</span><span class="p">(</span> <span class="p">(:</span><span class="n">foo</span><span class="p">,</span> <span class="s">"libfoo"</span><span class="p">),</span> <span class="n">Void</span><span class="p">,</span> <span class="p">(</span><span class="kt">Int32</span><span class="p">,</span> <span class="kt">Float64</span><span class="p">),</span>
<span class="nb">convert</span><span class="p">(</span><span class="kt">Int32</span><span class="p">,</span> <span class="n">x</span><span class="p">),</span> <span class="nb">convert</span><span class="p">(</span><span class="kt">Float64</span><span class="p">,</span> <span class="n">y</span><span class="p">))</span>
</pre></div>
</div>
<p>When a scalar value is passed with <tt class="docutils literal"><span class="pre">&</span></tt> as an argument of type
<tt class="docutils literal"><span class="pre">Ptr{T}</span></tt>, the value will first be converted to type <tt class="docutils literal"><span class="pre">T</span></tt>.</p>
<div class="section" id="array-conversions">
<h3>Array conversions<a class="headerlink" href="#array-conversions" title="Permalink to this headline">¶</a></h3>
<p>When an array is passed to C as a <tt class="docutils literal"><span class="pre">Ptr{T}</span></tt> argument, it is
never converted: Julia simply checks that the element type of the
array matches <tt class="docutils literal"><span class="pre">T</span></tt>, and the address of the first element is passed.
This is done in order to avoid copying arrays unnecessarily.</p>
<p>Therefore, if an <tt class="docutils literal"><span class="pre">Array</span></tt> contains data in the wrong format, it will
have to be explicitly converted using a call such as <tt class="docutils literal"><span class="pre">int32(a)</span></tt>.</p>
<p>To pass an array <tt class="docutils literal"><span class="pre">A</span></tt> as a pointer of a different type <em>without</em>
converting the data beforehand (for example, to pass a <tt class="docutils literal"><span class="pre">Float64</span></tt> array
to a function that operates on uninterpreted bytes), you can either
declare the argument as <tt class="docutils literal"><span class="pre">Ptr{Void}</span></tt> or you can explicitly call
<tt class="docutils literal"><span class="pre">convert(Ptr{T},</span> <span class="pre">pointer(A))</span></tt>.</p>
</div>
<div class="section" id="type-correspondences">
<h3>Type correspondences<a class="headerlink" href="#type-correspondences" title="Permalink to this headline">¶</a></h3>
<p>On all systems we currently support, basic C/C++ value types may be
translated to Julia types as follows. Every C type also has a corresponding
Julia type with the same name, prefixed by C. This can help for writing portable code (and remembering that an int in C is not the same as an Int in Julia).</p>
<p><strong>System-independent:</strong></p>
<table border="1" class="docutils">
<colgroup>
<col width="32%" />
<col width="25%" />
<col width="43%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">signed</span> <span class="pre">char</span></tt></td>
<td> </td>
<td><tt class="docutils literal"><span class="pre">Int8</span></tt></td>
</tr>
<tr class="row-even"><td><tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">char</span></tt></td>
<td><tt class="docutils literal"><span class="pre">Cuchar</span></tt></td>
<td><tt class="docutils literal"><span class="pre">Uint8</span></tt></td>
</tr>
<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">short</span></tt></td>
<td><tt class="docutils literal"><span class="pre">Cshort</span></tt></td>
<td><tt class="docutils literal"><span class="pre">Int16</span></tt></td>
</tr>
<tr class="row-even"><td><tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">short</span></tt></td>
<td><tt class="docutils literal"><span class="pre">Cushort</span></tt></td>
<td><tt class="docutils literal"><span class="pre">Uint16</span></tt></td>
</tr>
<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">int</span></tt></td>
<td><tt class="docutils literal"><span class="pre">Cint</span></tt></td>
<td><tt class="docutils literal"><span class="pre">Int32</span></tt></td>
</tr>
<tr class="row-even"><td><tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">int</span></tt></td>
<td><tt class="docutils literal"><span class="pre">Cuint</span></tt></td>
<td><tt class="docutils literal"><span class="pre">Uint32</span></tt></td>
</tr>
<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">long</span> <span class="pre">long</span></tt></td>
<td><tt class="docutils literal"><span class="pre">Clonglong</span></tt></td>
<td><tt class="docutils literal"><span class="pre">Int64</span></tt></td>
</tr>
<tr class="row-even"><td><tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">long</span> <span class="pre">long</span></tt></td>
<td><tt class="docutils literal"><span class="pre">Culonglong</span></tt></td>
<td><tt class="docutils literal"><span class="pre">Uint64</span></tt></td>
</tr>
<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">float</span></tt></td>
<td><tt class="docutils literal"><span class="pre">Cfloat</span></tt></td>
<td><tt class="docutils literal"><span class="pre">Float32</span></tt></td>
</tr>
<tr class="row-even"><td><tt class="docutils literal"><span class="pre">double</span></tt></td>
<td><tt class="docutils literal"><span class="pre">Cdouble</span></tt></td>
<td><tt class="docutils literal"><span class="pre">Float64</span></tt></td>
</tr>
<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">ptrdiff_t</span></tt></td>
<td><tt class="docutils literal"><span class="pre">Cptrdiff_t</span></tt></td>
<td><tt class="docutils literal"><span class="pre">Int</span></tt></td>
</tr>
<tr class="row-even"><td><tt class="docutils literal"><span class="pre">ssize_t</span></tt></td>
<td><tt class="docutils literal"><span class="pre">Cssize_t</span></tt></td>
<td><tt class="docutils literal"><span class="pre">Int</span></tt></td>
</tr>
<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">size_t</span></tt></td>
<td><tt class="docutils literal"><span class="pre">Csize_t</span></tt></td>
<td><tt class="docutils literal"><span class="pre">Uint</span></tt></td>
</tr>
<tr class="row-even"><td><tt class="docutils literal"><span class="pre">void</span></tt></td>
<td> </td>
<td><tt class="docutils literal"><span class="pre">Void</span></tt></td>
</tr>
<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">void*</span></tt></td>
<td> </td>
<td><tt class="docutils literal"><span class="pre">Ptr{Void}</span></tt></td>
</tr>
<tr class="row-even"><td colspan="2"><tt class="docutils literal"><span class="pre">char*</span></tt> (or <tt class="docutils literal"><span class="pre">char[]</span></tt>, e.g. a string)</td>
<td><tt class="docutils literal"><span class="pre">Ptr{Uint8}</span></tt></td>
</tr>
<tr class="row-odd"><td colspan="2"><tt class="docutils literal"><span class="pre">char**</span></tt> (or <tt class="docutils literal"><span class="pre">*char[]</span></tt>)</td>
<td><tt class="docutils literal"><span class="pre">Ptr{Ptr{Uint8}}</span></tt></td>
</tr>
<tr class="row-even"><td colspan="2"><tt class="docutils literal"><span class="pre">struct</span> <span class="pre">T*</span></tt> (where T represents an
appropriately defined bits type)</td>
<td><tt class="docutils literal"><span class="pre">Ptr{T}</span></tt> (call using
&variable_name in the
parameter list)</td>
</tr>
<tr class="row-odd"><td colspan="2"><tt class="docutils literal"><span class="pre">struct</span> <span class="pre">T</span></tt> (where T represents an
appropriately defined bits type)</td>
<td><tt class="docutils literal"><span class="pre">T</span></tt> (call using
&variable_name in the
parameter list)</td>
</tr>
<tr class="row-even"><td colspan="2"><tt class="docutils literal"><span class="pre">jl_value_t*</span></tt> (any Julia Type)</td>
<td><tt class="docutils literal"><span class="pre">Ptr{Any}</span></tt></td>
</tr>
</tbody>
</table>
<p>Julia’s <tt class="docutils literal"><span class="pre">Char</span></tt> type is 32 bits, which is not the same as the wide
character type (<tt class="docutils literal"><span class="pre">wchar_t</span></tt> or <tt class="docutils literal"><span class="pre">wint_t</span></tt>) on all platforms.</p>
<p>A C function declared to return <tt class="docutils literal"><span class="pre">void</span></tt> will give <tt class="docutils literal"><span class="pre">nothing</span></tt> in Julia.</p>
<p><strong>System-dependent:</strong></p>
<table border="1" class="docutils">
<colgroup>
<col width="37%" />
<col width="23%" />
<col width="40%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">char</span></tt></td>
<td><tt class="docutils literal"><span class="pre">Cchar</span></tt></td>
<td><p class="first"><tt class="docutils literal"><span class="pre">Int8</span></tt> (x86, x86_64)</p>
<p class="last"><tt class="docutils literal"><span class="pre">Uint8</span></tt> (powerpc, arm)</p>
</td>
</tr>
<tr class="row-even"><td><tt class="docutils literal"><span class="pre">long</span></tt></td>
<td><tt class="docutils literal"><span class="pre">Clong</span></tt></td>
<td><p class="first"><tt class="docutils literal"><span class="pre">Int</span></tt> (UNIX)</p>
<p class="last"><tt class="docutils literal"><span class="pre">Int32</span></tt> (Windows)</p>
</td>
</tr>
<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">long</span></tt></td>
<td><tt class="docutils literal"><span class="pre">Culong</span></tt></td>
<td><p class="first"><tt class="docutils literal"><span class="pre">Uint</span></tt> (UNIX)</p>
<p class="last"><tt class="docutils literal"><span class="pre">Uint32</span></tt> (Windows)</p>
</td>
</tr>
<tr class="row-even"><td><tt class="docutils literal"><span class="pre">wchar_t</span></tt></td>
<td><tt class="docutils literal"><span class="pre">Cwchar_t</span></tt></td>
<td><p class="first"><tt class="docutils literal"><span class="pre">Int32</span></tt> (UNIX)</p>
<p class="last"><tt class="docutils literal"><span class="pre">Uint16</span></tt> (Windows)</p>
</td>
</tr>
</tbody>
</table>
<p>For string arguments (<tt class="docutils literal"><span class="pre">char*</span></tt>) the Julia type should be <tt class="docutils literal"><span class="pre">Ptr{Uint8}</span></tt>,
not <tt class="docutils literal"><span class="pre">ASCIIString</span></tt>. C functions that take an argument of the type <tt class="docutils literal"><span class="pre">char**</span></tt>
can be called by using a <tt class="docutils literal"><span class="pre">Ptr{Ptr{Uint8}}</span></tt> type within Julia. For example,
C functions of the form:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="n">int</span> <span class="n">main</span><span class="p">(</span><span class="n">int</span> <span class="n">argc</span><span class="p">,</span> <span class="n">char</span> <span class="o">**</span><span class="n">argv</span><span class="p">);</span>
</pre></div>
</div>
<p>can be called via the following Julia code:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="n">argv</span> <span class="o">=</span> <span class="p">[</span> <span class="s">"a.out"</span><span class="p">,</span> <span class="s">"arg1"</span><span class="p">,</span> <span class="s">"arg2"</span> <span class="p">]</span>
<span class="k">ccall</span><span class="p">(:</span><span class="n">main</span><span class="p">,</span> <span class="kt">Int32</span><span class="p">,</span> <span class="p">(</span><span class="kt">Int32</span><span class="p">,</span> <span class="n">Ptr</span><span class="p">{</span><span class="n">Ptr</span><span class="p">{</span><span class="kt">Uint8</span><span class="p">}}),</span> <span class="n">length</span><span class="p">(</span><span class="n">argv</span><span class="p">),</span> <span class="n">argv</span><span class="p">)</span>
</pre></div>
</div>
<p>For <tt class="docutils literal"><span class="pre">wchar_t*</span></tt> arguments, the Julia type should be <tt class="docutils literal"><span class="pre">Ptr{Wchar_t}</span></tt>,
and data can be converted to/from ordinary Julia strings by the
<tt class="docutils literal"><span class="pre">wstring(s)</span></tt> function (equivalent to either <tt class="docutils literal"><span class="pre">utf16(s)</span></tt> or <tt class="docutils literal"><span class="pre">utf32(s)</span></tt>
depending upon the width of <tt class="docutils literal"><span class="pre">Cwchar_t</span></tt>. Note also that ASCII, UTF-8,
UTF-16, and UTF-32 string data in Julia is internally NUL-terminated, so
it can be passed to C functions expecting NUL-terminated data without making
a copy.</p>
</div>
</div>
<div class="section" id="accessing-data-through-a-pointer">
<h2>Accessing Data through a Pointer<a class="headerlink" href="#accessing-data-through-a-pointer" title="Permalink to this headline">¶</a></h2>
<p>The following methods are described as “unsafe” because they can cause Julia
to terminate abruptly or corrupt arbitrary process memory due to a bad pointer
or type declaration.</p>
<p>Given a <tt class="docutils literal"><span class="pre">Ptr{T}</span></tt>, the contents of type <tt class="docutils literal"><span class="pre">T</span></tt> can generally be copied from
the referenced memory into a Julia object using <tt class="docutils literal"><span class="pre">unsafe_load(ptr,</span> <span class="pre">[index])</span></tt>. The
index argument is optional (default is 1), and performs 1-based indexing. This
function is intentionally similar to the behavior of <tt class="docutils literal"><span class="pre">getindex()</span></tt> and <tt class="docutils literal"><span class="pre">setindex!()</span></tt>
(e.g. <tt class="docutils literal"><span class="pre">[]</span></tt> access syntax).</p>
<p>The return value will be a new object initialized
to contain a copy of the contents of the referenced memory. The referenced
memory can safely be freed or released.</p>
<p>If <tt class="docutils literal"><span class="pre">T</span></tt> is <tt class="docutils literal"><span class="pre">Any</span></tt>, then the memory is assumed to contain a reference to
a Julia object (a <tt class="docutils literal"><span class="pre">jl_value_t*</span></tt>), the result will be a reference to this object,
and the object will not be copied. You must be careful in this case to ensure
that the object was always visible to the garbage collector (pointers do not
count, but the new reference does) to ensure the memory is not prematurely freed.
Note that if the object was not originally allocated by Julia, the new object
will never be finalized by Julia’s garbage collector. If the <tt class="docutils literal"><span class="pre">Ptr</span></tt> itself
is actually a <tt class="docutils literal"><span class="pre">jl_value_t*</span></tt>, it can be converted back to a Julia object
reference by <tt class="docutils literal"><span class="pre">unsafe_pointer_to_objref(ptr)</span></tt>. (Julia values <tt class="docutils literal"><span class="pre">v</span></tt>
can be converted to <tt class="docutils literal"><span class="pre">jl_value_t*</span></tt> pointers, as <tt class="docutils literal"><span class="pre">Ptr{Void}</span></tt>, by calling
<tt class="docutils literal"><span class="pre">pointer_from_objref(v)</span></tt>.)</p>
<p>The reverse operation (writing data to a Ptr{T}), can be performed using
<tt class="docutils literal"><span class="pre">unsafe_store!(ptr,</span> <span class="pre">value,</span> <span class="pre">[index])</span></tt>. Currently, this is only supported
for bitstypes or other pointer-free (<tt class="docutils literal"><span class="pre">isbits</span></tt>) immutable types.</p>
<p>Any operation that throws an error is probably currently unimplemented
and should be posted as a bug so that it can be resolved.</p>
<p>If the pointer of interest is a plain-data array (bitstype or immutable), the
function <tt class="docutils literal"><span class="pre">pointer_to_array(ptr,dims,[own])</span></tt> may be more useful. The final
parameter should be true if Julia should “take ownership” of the underlying
buffer and call <tt class="docutils literal"><span class="pre">free(ptr)</span></tt> when the returned <tt class="docutils literal"><span class="pre">Array</span></tt> object is finalized.
If the <tt class="docutils literal"><span class="pre">own</span></tt> parameter is omitted or false, the caller must ensure the
buffer remains in existence until all access is complete.</p>
<p>Arithmetic on the <tt class="docutils literal"><span class="pre">Ptr</span></tt> type in Julia (e.g. using <tt class="docutils literal"><span class="pre">+</span></tt>) does not behave the
same as C’s pointer arithmetic. Adding an integer to a <tt class="docutils literal"><span class="pre">Ptr</span></tt> in Julia always
moves the pointer by some number of <em>bytes</em>, not elements. This way, the
address values obtained from pointer arithmetic do not depend on the
element types of pointers.</p>
</div>
<div class="section" id="passing-pointers-for-modifying-inputs">
<h2>Passing Pointers for Modifying Inputs<a class="headerlink" href="#passing-pointers-for-modifying-inputs" title="Permalink to this headline">¶</a></h2>
<p>Because C doesn’t support multiple return values, often C functions will take
pointers to data that the function will modify. To accomplish this within a
<tt class="docutils literal"><span class="pre">ccall</span></tt> you need to encapsulate the value inside an array of the appropriate
type. When you pass the array as an argument with a <tt class="docutils literal"><span class="pre">Ptr</span></tt> type, julia will
automatically pass a C pointer to the encapsulated data:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="n">width</span> <span class="o">=</span> <span class="n">Cint</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>
<span class="n">range</span> <span class="o">=</span> <span class="n">Cfloat</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>
<span class="k">ccall</span><span class="p">(:</span><span class="n">foo</span><span class="p">,</span> <span class="n">Void</span><span class="p">,</span> <span class="p">(</span><span class="n">Ptr</span><span class="p">{</span><span class="n">Cint</span><span class="p">},</span> <span class="n">Ptr</span><span class="p">{</span><span class="n">Cfloat</span><span class="p">}),</span> <span class="n">width</span><span class="p">,</span> <span class="n">range</span><span class="p">)</span>
</pre></div>
</div>
<p>This is used extensively in Julia’s LAPACK interface, where an integer <tt class="docutils literal"><span class="pre">info</span></tt>
is passed to LAPACK by reference, and on return, includes the success code.</p>
</div>
<div class="section" id="garbage-collection-safety">
<h2>Garbage Collection Safety<a class="headerlink" href="#garbage-collection-safety" title="Permalink to this headline">¶</a></h2>
<p>When passing data to a ccall, it is best to avoid using the <tt class="docutils literal"><span class="pre">pointer()</span></tt>
function. Instead define a convert method and pass the variables directly to
the ccall. ccall automatically arranges that all of its arguments will be
preserved from garbage collection until the call returns. If a C API will
store a reference to memory allocated by Julia, after the ccall returns, you
must arrange that the object remains visible to the garbage collector. The
suggested way to handle this is to make a global variable of type
<tt class="docutils literal"><span class="pre">Array{Any,1}</span></tt> to hold these values, until C interface notifies you that
it is finished with them.</p>
<p>Whenever you have created a pointer to Julia data, you must ensure the original data
exists until you are done with using the pointer. Many methods in Julia such as
<tt class="docutils literal"><span class="pre">unsafe_load()</span></tt> and <tt class="docutils literal"><span class="pre">bytestring()</span></tt> make copies of data instead of taking ownership
of the buffer, so that it is safe to free (or alter) the original data without
affecting Julia. A notable exception is <tt class="docutils literal"><span class="pre">pointer_to_array()</span></tt> which, for performance
reasons, shares (or can be told to take ownership of) the underlying buffer.</p>
<p>The garbage collector does not guarantee any order of finalization. That is, if <tt class="docutils literal"><span class="pre">a</span></tt>
contained a reference to <tt class="docutils literal"><span class="pre">b</span></tt> and both <tt class="docutils literal"><span class="pre">a</span></tt> and <tt class="docutils literal"><span class="pre">b</span></tt> are due for garbage
collection, there is no guarantee that <tt class="docutils literal"><span class="pre">b</span></tt> would be finalized after <tt class="docutils literal"><span class="pre">a</span></tt>. If
proper finalization of <tt class="docutils literal"><span class="pre">a</span></tt> depends on <tt class="docutils literal"><span class="pre">b</span></tt> being valid, it must be handled in
other ways.</p>
</div>
<div class="section" id="non-constant-function-specifications">
<h2>Non-constant Function Specifications<a class="headerlink" href="#non-constant-function-specifications" title="Permalink to this headline">¶</a></h2>
<p>A <tt class="docutils literal"><span class="pre">(name,</span> <span class="pre">library)</span></tt> function specification must be a constant expression.
However, it is possible to use computed values as function names by staging
through <tt class="docutils literal"><span class="pre">eval</span></tt> as follows:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="p">@</span><span class="n">eval</span> <span class="k">ccall</span><span class="p">((</span><span class="o">$</span><span class="p">(</span><span class="n">string</span><span class="p">(</span><span class="s">"a"</span><span class="p">,</span><span class="s">"b"</span><span class="p">)),</span><span class="s">"lib"</span><span class="p">),</span> <span class="o">...</span>
</pre></div>
</div>
<p>This expression constructs a name using <tt class="docutils literal"><span class="pre">string</span></tt>, then substitutes this
name into a new <tt class="docutils literal"><span class="pre">ccall</span></tt> expression, which is then evaluated. Keep in mind that
<tt class="docutils literal"><span class="pre">eval</span></tt> only operates at the top level, so within this expression local
variables will not be available (unless their values are substituted with
<tt class="docutils literal"><span class="pre">$</span></tt>). For this reason, <tt class="docutils literal"><span class="pre">eval</span></tt> is typically only used to form top-level
definitions, for example when wrapping libraries that contain many
similar functions.</p>
</div>
<div class="section" id="indirect-calls">
<h2>Indirect Calls<a class="headerlink" href="#indirect-calls" title="Permalink to this headline">¶</a></h2>
<p>The first argument to <tt class="docutils literal"><span class="pre">ccall</span></tt> can also be an expression evaluated at
run time. In this case, the expression must evaluate to a <tt class="docutils literal"><span class="pre">Ptr</span></tt>,
which will be used as the address of the native function to call. This
behavior occurs when the first <tt class="docutils literal"><span class="pre">ccall</span></tt> argument contains references
to non-constants, such as local variables or function arguments.</p>
</div>
<div class="section" id="calling-convention">
<h2>Calling Convention<a class="headerlink" href="#calling-convention" title="Permalink to this headline">¶</a></h2>
<p>The second argument to <tt class="docutils literal"><span class="pre">ccall</span></tt> can optionally be a calling convention
specifier (immediately preceding return type). Without any specifier,
the platform-default C calling convention is used. Other supported
conventions are: <tt class="docutils literal"><span class="pre">stdcall</span></tt>, <tt class="docutils literal"><span class="pre">cdecl</span></tt>, <tt class="docutils literal"><span class="pre">fastcall</span></tt>, and <tt class="docutils literal"><span class="pre">thiscall</span></tt>.
For example (from base/libc.jl):</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="n">hn</span> <span class="o">=</span> <span class="n">Array</span><span class="p">(</span><span class="kt">Uint8</span><span class="p">,</span> <span class="mi">256</span><span class="p">)</span>
<span class="n">err</span><span class="o">=</span><span class="k">ccall</span><span class="p">(:</span><span class="n">gethostname</span><span class="p">,</span> <span class="n">stdcall</span><span class="p">,</span> <span class="kt">Int32</span><span class="p">,</span> <span class="p">(</span><span class="n">Ptr</span><span class="p">{</span><span class="kt">Uint8</span><span class="p">},</span> <span class="kt">Uint32</span><span class="p">),</span> <span class="n">hn</span><span class="p">,</span> <span class="n">length</span><span class="p">(</span><span class="n">hn</span><span class="p">))</span>
</pre></div>
</div>
<p>For more information, please see the <a class="reference external" href="http://llvm.org/docs/LangRef.html#calling-conventions">LLVM Language Reference</a>.</p>
</div>
<div class="section" id="accessing-global-variables">
<h2>Accessing Global Variables<a class="headerlink" href="#accessing-global-variables" title="Permalink to this headline">¶</a></h2>
<p>Global variables exported by native libraries can be accessed by name using the
<tt class="docutils literal"><span class="pre">cglobal</span></tt> function. The arguments to <tt class="docutils literal"><span class="pre">cglobal</span></tt> are a symbol specification
identical to that used by <tt class="docutils literal"><span class="pre">ccall</span></tt>, and a type describing the value stored in
the variable:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="n">julia</span><span class="o">></span> <span class="n">cglobal</span><span class="p">((:</span><span class="n">errno</span><span class="p">,:</span><span class="n">libc</span><span class="p">),</span> <span class="kt">Int32</span><span class="p">)</span>
<span class="n">Ptr</span><span class="p">{</span><span class="kt">Int32</span><span class="p">}</span> <span class="p">@</span><span class="mh">0x00007f418d0816b8</span>
</pre></div>
</div>
<p>The result is a pointer giving the address of the value. The value can be
manipulated through this pointer using <tt class="docutils literal"><span class="pre">unsafe_load</span></tt> and <tt class="docutils literal"><span class="pre">unsafe_store</span></tt>.</p>
</div>
<div class="section" id="passing-julia-callback-functions-to-c">
<h2>Passing Julia Callback Functions to C<a class="headerlink" href="#passing-julia-callback-functions-to-c" title="Permalink to this headline">¶</a></h2>
<p>It is possible to pass Julia functions to native functions that accept function
pointer arguments. A classic example is the standard C library <tt class="docutils literal"><span class="pre">qsort</span></tt> function,
declared as:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="n">void</span> <span class="n">qsort</span><span class="p">(</span><span class="n">void</span> <span class="o">*</span><span class="n">base</span><span class="p">,</span> <span class="n">size_t</span> <span class="n">nmemb</span><span class="p">,</span> <span class="n">size_t</span> <span class="n">size</span><span class="p">,</span>
<span class="n">int</span><span class="p">(</span><span class="o">*</span><span class="n">compare</span><span class="p">)(</span><span class="kd">const</span> <span class="n">void</span> <span class="o">*</span><span class="n">a</span><span class="p">,</span> <span class="kd">const</span> <span class="n">void</span> <span class="o">*</span><span class="n">b</span><span class="p">));</span>
</pre></div>
</div>
<p>The <tt class="docutils literal"><span class="pre">base</span></tt> argument is a pointer to an array of length <tt class="docutils literal"><span class="pre">nmemb</span></tt>, with elements of
<tt class="docutils literal"><span class="pre">size</span></tt> bytes each. <tt class="docutils literal"><span class="pre">compare</span></tt> is a callback function which takes pointers to two
elements <tt class="docutils literal"><span class="pre">a</span></tt> and <tt class="docutils literal"><span class="pre">b</span></tt> and returns an integer less/greater than zero if <tt class="docutils literal"><span class="pre">a</span></tt> should
appear before/after <tt class="docutils literal"><span class="pre">b</span></tt> (or zero if any order is permitted). Now, suppose that we
have a 1d array <tt class="docutils literal"><span class="pre">A</span></tt> of values in Julia that we want to sort using the <tt class="docutils literal"><span class="pre">qsort</span></tt>
function (rather than Julia’s built-in sort function). Before we worry about calling
<tt class="docutils literal"><span class="pre">qsort</span></tt> and passing arguments, we need to write a comparison function that works for
some arbitrary type T:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="k">function</span><span class="nf"> mycompare</span><span class="p">{</span><span class="n">T</span><span class="p">}(</span><span class="n">a_</span><span class="p">::</span><span class="n">Ptr</span><span class="p">{</span><span class="n">T</span><span class="p">},</span> <span class="n">b_</span><span class="p">::</span><span class="n">Ptr</span><span class="p">{</span><span class="n">T</span><span class="p">})</span>
<span class="n">a</span> <span class="o">=</span> <span class="n">unsafe_load</span><span class="p">(</span><span class="n">a_</span><span class="p">)</span>
<span class="n">b</span> <span class="o">=</span> <span class="n">unsafe_load</span><span class="p">(</span><span class="n">b_</span><span class="p">)</span>
<span class="k">return</span> <span class="nb">convert</span><span class="p">(</span><span class="n">Cint</span><span class="p">,</span> <span class="n">a</span> <span class="o"><</span> <span class="n">b</span> <span class="o">?</span> <span class="o">-</span><span class="mi">1</span> <span class="p">:</span> <span class="n">a</span> <span class="o">></span> <span class="n">b</span> <span class="o">?</span> <span class="o">+</span><span class="mi">1</span> <span class="p">:</span> <span class="mi">0</span><span class="p">)</span>
<span class="k">end</span>
</pre></div>
</div>
<p>Notice that we have to be careful about the return type: <tt class="docutils literal"><span class="pre">qsort</span></tt> expects a function
returning a C <tt class="docutils literal"><span class="pre">int</span></tt>, so we must be sure to return <tt class="docutils literal"><span class="pre">Cint</span></tt> via a call to <tt class="docutils literal"><span class="pre">convert</span></tt>.</p>
<p>In order to pass this function to C, we obtain its address using the function
<tt class="docutils literal"><span class="pre">cfunction</span></tt>:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="kd">const</span> <span class="n">mycompare_c</span> <span class="o">=</span> <span class="n">cfunction</span><span class="p">(</span><span class="n">mycompare</span><span class="p">,</span> <span class="n">Cint</span><span class="p">,</span> <span class="p">(</span><span class="n">Ptr</span><span class="p">{</span><span class="n">Cdouble</span><span class="p">},</span> <span class="n">Ptr</span><span class="p">{</span><span class="n">Cdouble</span><span class="p">}))</span>
</pre></div>
</div>
<p><tt class="docutils literal"><span class="pre">cfunction</span></tt> accepts three arguments: the Julia function (<tt class="docutils literal"><span class="pre">mycompare</span></tt>), the return
type (<tt class="docutils literal"><span class="pre">Cint</span></tt>), and a tuple of the argument types, in this case to sort an array of
<tt class="docutils literal"><span class="pre">Cdouble</span></tt> (Float64) elements.</p>
<p>The final call to <tt class="docutils literal"><span class="pre">qsort</span></tt> looks like this:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="n">A</span> <span class="o">=</span> <span class="p">[</span><span class="mf">1.3</span><span class="p">,</span> <span class="o">-</span><span class="mf">2.7</span><span class="p">,</span> <span class="mf">4.4</span><span class="p">,</span> <span class="mf">3.1</span><span class="p">]</span>
<span class="k">ccall</span><span class="p">(:</span><span class="n">qsort</span><span class="p">,</span> <span class="n">Void</span><span class="p">,</span> <span class="p">(</span><span class="n">Ptr</span><span class="p">{</span><span class="n">Cdouble</span><span class="p">},</span> <span class="n">Csize_t</span><span class="p">,</span> <span class="n">Csize_t</span><span class="p">,</span> <span class="n">Ptr</span><span class="p">{</span><span class="n">Void</span><span class="p">}),</span>
<span class="n">A</span><span class="p">,</span> <span class="n">length</span><span class="p">(</span><span class="n">A</span><span class="p">),</span> <span class="nb">sizeof</span><span class="p">(</span><span class="n">eltype</span><span class="p">(</span><span class="n">A</span><span class="p">)),</span> <span class="n">mycompare_c</span><span class="p">)</span>
</pre></div>
</div>
<p>After this executes, <tt class="docutils literal"><span class="pre">A</span></tt> is changed to the sorted array <tt class="docutils literal"><span class="pre">[</span> <span class="pre">-2.7,</span> <span class="pre">1.3,</span> <span class="pre">3.1,</span> <span class="pre">4.4]</span></tt>.
Note that Julia knows how to convert an array into a <tt class="docutils literal"><span class="pre">Ptr{Cdouble}</span></tt>, how to compute
the size of a type in bytes (identical to C’s <tt class="docutils literal"><span class="pre">sizeof</span></tt> operator), and so on.
For fun, try inserting a <tt class="docutils literal"><span class="pre">println("mycompare($a,$b)")</span></tt> line into <tt class="docutils literal"><span class="pre">mycompare</span></tt>, which
will allow you to see the comparisons that <tt class="docutils literal"><span class="pre">qsort</span></tt> is performing (and to verify that
it is really calling the Julia function that you passed to it).</p>
<div class="section" id="thread-safety">
<h3>Thread-safety<a class="headerlink" href="#thread-safety" title="Permalink to this headline">¶</a></h3>
<p>Some C libraries execute their callbacks from a different thread, and
since Julia isn’t thread-safe you’ll need to take some extra
precautions. In particular, you’ll need to set up a two-layered
system: the C callback should only <em>schedule</em> (via Julia’s event loop)
the execution of your “real” callback. To do this, you pass a function
of one argument (the <tt class="docutils literal"><span class="pre">AsyncWork</span></tt> object for which the event was
triggered, which you’ll probably just ignore) to <tt class="docutils literal"><span class="pre">SingleAsyncWork</span></tt>:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="n">cb</span> <span class="o">=</span> <span class="n">Base</span><span class="o">.</span><span class="n">SingleAsyncWork</span><span class="p">(</span><span class="n">data</span> <span class="o">-></span> <span class="n">my_real_callback</span><span class="p">(</span><span class="n">args</span><span class="p">))</span>
</pre></div>
</div>
<p>The callback you pass to C should only execute a <tt class="docutils literal"><span class="pre">ccall</span></tt> to
<tt class="docutils literal"><span class="pre">:uv_async_send</span></tt>, passing <tt class="docutils literal"><span class="pre">cb.handle</span></tt> as the argument.</p>
</div>
<div class="section" id="more-about-callbacks">
<h3>More About Callbacks<a class="headerlink" href="#more-about-callbacks" title="Permalink to this headline">¶</a></h3>
<p>For more details on how to pass callbacks to C libraries, see this
<a class="reference external" href="http://julialang.org/blog/2013/05/callback/">blog post</a>.</p>
</div>
</div>
<div class="section" id="c">
<h2>C++<a class="headerlink" href="#c" title="Permalink to this headline">¶</a></h2>
<p>Limited support for C++ is provided by the <a class="reference external" href="https://github.com/timholy/Cpp.jl">Cpp</a>
and <a class="reference external" href="https://github.com/ihnorton/Clang.jl">Clang</a> packages.</p>
</div>
<div class="section" id="handling-platform-variations">
<h2>Handling Platform Variations<a class="headerlink" href="#handling-platform-variations" title="Permalink to this headline">¶</a></h2>
<p>When dealing with platform libraries, it is often necessary to provide special cases
for various platforms. The variable <tt class="docutils literal"><span class="pre">OS_NAME</span></tt> can be used to write these special
cases. Additionally, there are several macros intended to make this easier:
<tt class="docutils literal"><span class="pre">@windows</span></tt>, <tt class="docutils literal"><span class="pre">@unix</span></tt>, <tt class="docutils literal"><span class="pre">@linux</span></tt>, and <tt class="docutils literal"><span class="pre">@osx</span></tt>. Note that linux and osx are mutually
exclusive subsets of unix. Their usage takes the form of a ternary conditional
operator, as demonstrated in the following examples.</p>
<p>Simple blocks:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="k">ccall</span><span class="p">(</span> <span class="p">(@</span><span class="n">windows</span><span class="o">?</span> <span class="p">:</span><span class="n">_fopen</span> <span class="p">:</span> <span class="p">:</span><span class="n">fopen</span><span class="p">),</span> <span class="o">...</span><span class="p">)</span>
</pre></div>
</div>
<p>Complex blocks:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="p">@</span><span class="n">linux</span><span class="o">?</span> <span class="p">(</span>
<span class="k">begin</span>
<span class="n">some_complicated_thing</span><span class="p">(</span><span class="n">a</span><span class="p">)</span>
<span class="k">end</span>
<span class="p">:</span> <span class="k">begin</span>
<span class="n">some_different_thing</span><span class="p">(</span><span class="n">a</span><span class="p">)</span>
<span class="k">end</span>
<span class="p">)</span>
</pre></div>
</div>
<p>Chaining (parentheses optional, but recommended for readability):</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="p">@</span><span class="n">windows</span><span class="o">?</span> <span class="p">:</span><span class="n">a</span> <span class="p">:</span> <span class="p">(@</span><span class="n">osx</span><span class="o">?</span> <span class="p">:</span><span class="n">b</span> <span class="p">:</span> <span class="p">:</span><span class="n">c</span><span class="p">)</span>
</pre></div>
</div>
</div>
</div>
</div>
<footer>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="interacting-with-julia.html" class="btn btn-neutral float-right" title="Interacting With Julia"/>Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="running-external-programs.html" class="btn btn-neutral" title="Running External Programs"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
<hr/>
<div role="contentinfo">
<p>
</p>
</div>
<a href="https://github.com/snide/sphinx_rtd_theme">Sphinx theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'../',
VERSION:'0.3.4',
COLLAPSE_INDEX:false,
FILE_SUFFIX:'.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
<script type="text/javascript" src="../_static/js/theme.js"></script>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.StickyNav.enable();
});
</script>
</body>
</html>
