<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"
lang="en" dir="ltr">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>
strlcpy [C++ Reference]
</title>
<meta name="generator" content="DokuWiki Release 2009-12-25c "Lemming"" />
<meta name="robots" content="index,follow" />
<meta name="date" content="2010-03-08T09:30:33-0800" />
<meta name="keywords" content="c,string,strlcpy" />
<link rel="search" type="application/opensearchdescription+xml" href="/wiki/lib/exe/opensearch.php" title="C++ Reference" />
<link rel="start" href="/wiki/" />
<link rel="contents" href="/wiki/c/string/strlcpy?do=index" title="Index" />
<link rel="alternate" type="application/rss+xml" title="Recent Changes" href="/wiki/feed.php" />
<link rel="alternate" type="application/rss+xml" title="Current Namespace" href="/wiki/feed.php?mode=list&ns=c:string" />
<link rel="edit" title="Edit this page" href="/wiki/c/string/strlcpy?do=edit" />
<link rel="alternate" type="text/html" title="Plain HTML" href="/wiki/_export/xhtml/c/string/strlcpy" />
<link rel="alternate" type="text/plain" title="Wiki Markup" href="/wiki/_export/raw/c/string/strlcpy" />
<link rel="canonical" href="http://www.cppreference.com/wiki/c/string/strlcpy" />
<link rel="stylesheet" media="all" type="text/css" href="/wiki/lib/exe/css.php?s=all&t=custom1&tseed=1272971091" />
<link rel="stylesheet" media="screen" type="text/css" href="/wiki/lib/exe/css.php?t=custom1&tseed=1272971091" />
<link rel="stylesheet" media="print" type="text/css" href="/wiki/lib/exe/css.php?s=print&t=custom1&tseed=1272971091" />
<script type="text/javascript" charset="utf-8" ><!--//--><![CDATA[//><!--
var NS='c:string';var JSINFO = {"id":"c:string:strlcpy","namespace":"c:string"};
//--><!]]></script>
<script type="text/javascript" charset="utf-8" src="/wiki/lib/exe/js.php?tseed=1272971091" ></script>
<link rel="shortcut icon" href="/wiki/lib/tpl/custom1/images/favicon.png" />
</head>
<body>
<div class="dokuwiki">
<div class="stylehead">
<div class="header">
<div class="pagename">
[[<a href="../../c/string/strlcpy.html" title="Backlinks">strlcpy</a>]]
</div>
<div class="logo">
<a href="http://www.cppreference.com" name="dokuwiki__top" id="dokuwiki__top" accesskey="h" title="[ALT+H]">C++ Reference</a> </div>
<div class="clearer"></div>
</div>
<div class="breadcrumbs">
<span class="bchead">You are here: </span><a href="../../start.html" title="start">C++ Reference</a> » <a href="../../c/start.html" title="c:start">The Standard C Library</a> » <a href="../../c/string/start.html" title="c:string:start">Standard C String and Character</a> » <a href="../../c/string/strlcpy.html" title="c:string:strlcpy">strlcpy</a> </div>
</div>
<div class="plugin_translation"><span>Translations of this page<sup><a href="../../localization.html" class="wikilink1" title="localization">?</a></sup>:</span> <ul> <li><div class="li"><span class="curid"><a href="../../c/string/strlcpy.html" class="wikilink1" title="c:string:strlcpy">en</a></span></div></li> <li><div class="li"><a href="../../br-pt/c/string/strlcpy.html" class="wikilink2" title="br-pt:c:string:strlcpy" rel="nofollow">br-pt</a></div></li> <li><div class="li"><a href="../../cn/c/string/strlcpy.html" class="wikilink2" title="cn:c:string:strlcpy" rel="nofollow">cn</a></div></li> <li><div class="li"><a href="../../cz/c/string/strlcpy.html" class="wikilink2" title="cz:c:string:strlcpy" rel="nofollow">cz</a></div></li> <li><div class="li"><a href="../../de/c/string/strlcpy.html" class="wikilink2" title="de:c:string:strlcpy" rel="nofollow">de</a></div></li> <li><div class="li"><a href="../../es/c/string/strlcpy.html" class="wikilink2" title="es:c:string:strlcpy" rel="nofollow">es</a></div></li> <li><div class="li"><a href="../../fr/c/string/strlcpy.html" class="wikilink2" title="fr:c:string:strlcpy" rel="nofollow">fr</a></div></li> <li><div class="li"><a href="../../it/c/string/strlcpy.html" class="wikilink2" title="it:c:string:strlcpy" rel="nofollow">it</a></div></li> <li><div class="li"><a href="../../jp/c/string/strlcpy.html" class="wikilink2" title="jp:c:string:strlcpy" rel="nofollow">jp</a></div></li> <li><div class="li"><a href="../../nl/c/string/strlcpy.html" class="wikilink2" title="nl:c:string:strlcpy" rel="nofollow">nl</a></div></li> <li><div class="li"><a href="../../pl/c/string/strlcpy.html" class="wikilink2" title="pl:c:string:strlcpy" rel="nofollow">pl</a></div></li> <li><div class="li"><a href="../../ro/c/string/strlcpy.html" class="wikilink2" title="ro:c:string:strlcpy" rel="nofollow">ro</a></div></li> <li><div class="li"><a href="../../ru/c/string/strlcpy.html" class="wikilink2" title="ru:c:string:strlcpy" rel="nofollow">ru</a></div></li> <li><div class="li"><a href="../../sk/c/string/strlcpy.html" class="wikilink2" title="sk:c:string:strlcpy" rel="nofollow">sk</a></div></li> <li><div class="li"><a href="../../tr/c/string/strlcpy.html" class="wikilink2" title="tr:c:string:strlcpy" rel="nofollow">tr</a></div></li> <li><div class="li"><a href="../../tw/c/string/strlcpy.html" class="wikilink2" title="tw:c:string:strlcpy" rel="nofollow">tw</a></div></li></ul></div>
<div class="page">
<script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
</script>
<script type="text/javascript">
_uacct = "UA-2828341-1";
urchinTracker();
</script>
<!-- wikipage start -->
<!-- TOC START -->
<div class="toc">
<div class="tocheader toctoggle" id="toc__header">Table of Contents</div>
<div id="toc__inside">
<ul class="toc">
<li class="clear">
<ul class="toc">
<li class="level2"><div class="li"><span class="li"><a href="#strlcpy" class="toc">strlcpy</a></span></div></li>
<li class="level2"><div class="li"><span class="li"><a href="#section" class="toc"></a></span></div></li>
<li class="level2"><div class="li"><span class="li"><a href="#section1" class="toc"></a></span></div></li></ul>
</li></ul>
</div>
</div>
<!-- TOC END -->
<h2><a name="strlcpy" id="strlcpy">strlcpy</a></h2>
<div class="level2">
<p>
<strong>Warning:</strong> Non-standard function!
</p>
<p>
Syntax:
</p>
<pre class="c code c++" style="font-family:monospace;"> <span class="co2">#include <string.h> // On BSD or compatible systems</span>
size_t strlcpy<span class="br0">(</span> <span class="kw4">char</span> <span class="sy0">*</span>dst<span class="sy0">,</span> <span class="kw4">const</span> <span class="kw4">char</span> <span class="sy0">*</span>src<span class="sy0">,</span> size_t siz<span class="br0">)</span><span class="sy0">;</span></pre>
<p>
An attempt of the BSD people to “fix” <a href="../../c/string/strncpy.html" class="wikilink1" title="c:string:strncpy">strncpy</a>. There is a reason this function is not in any <acronym title="International Organization for Standardization">ISO</acronym> standard. See explanation after the description.
</p>
<p>
<strong>Original description:</strong>
</p>
<p>
Copy <code>src</code> to string <code>dst</code> of size <code>siz</code>.<br/>
At most <code>siz-1</code> characters will be copied.<br/>
Always <code>NUL</code> terminates (unless <code>siz == 0</code>).<br/>
Returns <code>strlen(src);</code> if <code>retval >= siz</code>, truncation occurred.
</p>
</div>
<div class="secedit"><form class="button btn_secedit" method="post" action="/wiki/c/string/strlcpy"><div class="no"><input type="hidden" name="do" value="edit" /><input type="hidden" name="lines" value="1-594" /><input type="hidden" name="rev" value="1268069433" /><input type="submit" value="Edit" class="button" title="strlcpy" /></div></form></div><div class="level2">
<p>
<strong>Why strlcpy is not an improvement, but rather a different, and quite possibly worse compromise:</strong>
</p>
<p>
Perceived advantages of strlcpy are:
</p>
<ol>
<li class="level1"><div class="li"> the target is (nearly) always <code>NUL</code> terminated</div>
</li>
<li class="level1"><div class="li"> the target is not filled up with zero characters</div>
</li>
</ol>
<p>
<em>The first “advantage”</em> is supposed to make programs more robust by ensuring that the resulting strings are always <code>NUL</code> terminated. First of all, they aren't, because the size argument can be <code>0</code>, in which case the code cannot write the terminating <code>NUL</code> character. This fact is already a hint that strlcpy is not a very well designed function. Even if we ignore that flaw for a moment, there is more to it.
</p>
<p>
The good and warm feeling of security that <code>strlcpy</code> may give its user is actually nothing more, than hiding an error. And hiding an error is never a good idea. <a href="../../c/string/strncpy.html" class="wikilink1" title="c:string:strncpy">strncpy</a> has a very blunt and effective way of reporting if the copy operation failed: it does not <code>NUL</code> terminate its target string. This means, that 2 hours after the <a href="../../c/string/strncpy.html" class="wikilink1" title="c:string:strncpy">strncpy</a> call that went unchecked (without error handling), it is still clearly visible (in memory) what has happened. Our buffer has no terminating zero character. However 2 hours after <code>strlcpy(buf,”assume”,3);</code> nothing whatsoever will show that the copy has failed, and the call went unchecked. In the lucky case, it will just result in overwriting some files or some mysteriously failed operations. In the very lucky case it will result in immediate damage. For example the overwritten files are important, and so the unchecked return value results in a crash or other system failure later on. Why is this luckier? Because we know there is a bug, even though <code>strlcpy</code> has tried its best to hide it.
</p>
<p>
Not much different from <a href="../../c/string/strncpy.html" class="wikilink1" title="c:string:strncpy">strncpy</a> you might say. You do not check the return value, you get problems. Except that with <a href="../../c/string/strncpy.html" class="wikilink1" title="c:string:strncpy">strncpy</a> a look at the dump will tell you exactly what the problem is. No <code>NUL</code> termination. With <code>strlcpy</code> all you see is a C-string, with no indication that it has been truncated.
</p>
<p>
<em>The second “advantage”</em> seems to be more straightforward. If I copy 5 bytes into a 42K buffer, <a href="../../c/string/strncpy.html" class="wikilink1" title="c:string:strncpy">strncpy</a> will write nearly 42K for no reason whatsoever, because we are only possibly interested in the <code>NUL</code> after the 5 characters and the <code>NUL</code> at the end of the buffer. That may be a performance hit you do not want to pay. If you meet such a rare situation while coding ask yourself: what is the maximum size for what I am copying? Is this the only thing that may go into that large buffer? It may well turn out that instead of 42*1024, you actually need 255 bytes max. for that filename you are copying. Depending on your situation, zeroing out a few bytes more might as well worth the trouble: you can use an <acronym title="International Organization for Standardization">ISO</acronym> <em>standard</em> function.
</p>
<p>
So while there are corner cases when <code>strlcpy</code> may actually be a lot faster than <a href="../../c/string/strncpy.html" class="wikilink1" title="c:string:strncpy">strncpy</a>, it is also true the other way around. The designers of <code>strlcpy</code> have made the unfortunate decision of ignoring the golden rule of: do one thing (and do that well). <code>strlcpy</code> does not report only whether or not the copy was successful. Nope. It reports also the <em>size</em> of the input. Who asked for that? This means, that if our hypothetical situation above is reversed, <code>strlcpy</code> will read 42K characters to find the length of the input, while it had only 5 bytes it could write. The caller may not even be interested in the length of the input. The caller just wants to give an error message saying “The filename is too long”. A malicious entity figures this out and may just start sending large strings and slow down a server tenfold.
</p>
<p>
So even the second, not-so-controversial “benefit” of <code>strlcpy</code> over <a href="../../c/string/strncpy.html" class="wikilink1" title="c:string:strncpy">strncpy</a> is questionable at best, and bogus at worse.
</p>
<p>
<strong>Why strlcpy is actually well-designed.</strong>
</p>
<p>
The above rant is misguided at best, a troll at worst.
</p>
<p>
The reason strlcpy returns the number of bytes written is so that you can check for short counts. This is the “error handling” that you are ranting about. Also, if you think that not NULL-terminating a string is an acceptable mechanism of error handling, then you're pretty far gone.
</p>
</div>
<div class="secedit"><form class="button btn_secedit" method="post" action="/wiki/c/string/strlcpy"><div class="no"><input type="hidden" name="do" value="edit" /><input type="hidden" name="lines" value="595-4755" /><input type="hidden" name="rev" value="1268069433" /><input type="submit" value="Edit" class="button" title="Edit" /></div></form></div><div class="level2">
<p>
Related Topics: <a href="../../c/string/memcpy.html" class="wikilink1" title="c:string:memcpy">memcpy</a>, <a href="../../c/string/strchr.html" class="wikilink1" title="c:string:strchr">strchr</a>, <a href="../../c/string/strncpy.html" class="wikilink1" title="c:string:strncpy">strncpy</a>, <a href="../../c/string/strncat.html" class="wikilink1" title="c:string:strncat">strncat</a>, <a href="../../c/string/strncmp.html" class="wikilink1" title="c:string:strncmp">strncmp</a>
</p>
<p>
Another related (but non-standard) function is <a href="../../c/string/strlcat.html" class="wikilink1" title="c:string:strlcat">strlcat</a>.
</p>
</div>
<div class="secedit"><form class="button btn_secedit" method="post" action="/wiki/c/string/strlcpy"><div class="no"><input type="hidden" name="do" value="edit" /><input type="hidden" name="lines" value="4756-" /><input type="hidden" name="rev" value="1268069433" /><input type="submit" value="Edit" class="button" title="Edit" /></div></form></div>
<!-- wikipage stop -->
</div>
<div class="clearer"> </div>
<div class="stylefoot">
<div class="meta">
<div class="user">
</div>
<!--
<div class="doc">
c/string/strlcpy.txt · Last modified: 03/08/2010 09:30 by 143.111.239.69 </div>
-->
</div>
<div class="bar" id="bar__bottom">
<div class="bar-left" id="bar__bottomleft">
<a href="../../c/string/strlcpy.html" class="action edit" accesskey="e" rel="nofollow">Edit this page</a> •
<a href="../../c/string/strlcpy.html" class="action revisions" accesskey="o" rel="nofollow">Old revisions</a> </div>
<div class="bar-right" id="bar__bottomright">
•
•
•
<a href="../../c/string/strlcpy.html" class="action login" rel="nofollow">Login</a> •
<a href="../../c/string/strlcpy.html" class="action index" accesskey="x" rel="nofollow">Index</a> •
<a href="../../c/string/strlcpy.html" class="action recent" accesskey="r" rel="nofollow">Recent changes</a> •
<a href="../../feed.php.html" title="Recent changes RSS feed">RSS</a> •
<a href='http://creativecommons.org/licenses/by/3.0/us/' title='Creative Commons license'>cc</a> •
<form action="/wiki/" accept-charset="utf-8" class="search" id="dw__search"><div class="no"><input type="hidden" name="do" value="search" /><input type="text" id="qsearch__in" accesskey="f" name="id" class="edit" title="[ALT+F]" /><input type="submit" value="Search" class="button" title="Search" /><div id="qsearch__out" class="ajax_qsearch JSpopup"></div></div></form>
</div>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="no"><img src="/wiki/lib/exe/indexer.php?id=c%3Astring%3Astrlcpy&1273199896" width="1" height="1" alt="" /></div>
</body>
</html>