File: //usr/local/ssl/share/gtk-doc/html/glib/glib-Windows-Compatibility-Functions.html
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Windows Compatibility Functions</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.69.1">
<link rel="start" href="index.html" title="GLib Reference Manual">
<link rel="up" href="glib-utilities.html" title="GLib Utilities">
<link rel="prev" href="glib-Bookmark-file-parser.html" title="Bookmark file parser">
<link rel="next" href="glib-data-types.html" title="GLib Data Types">
<meta name="generator" content="GTK-Doc V1.6 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
<link rel="chapter" href="glib.html" title="GLib Overview">
<link rel="chapter" href="glib-fundamentals.html" title="GLib Fundamentals">
<link rel="chapter" href="glib-core.html" title="GLib Core Application Support">
<link rel="chapter" href="glib-utilities.html" title="GLib Utilities">
<link rel="chapter" href="glib-data-types.html" title="GLib Data Types">
<link rel="chapter" href="tools.html" title="GLib Tools">
<link rel="index" href="ix01.html" title="Index">
<link rel="index" href="ix02.html" title="Index of deprecated symbols">
<link rel="index" href="ix03.html" title="Index of new symbols in 2.2">
<link rel="index" href="ix04.html" title="Index of new symbols in 2.4">
<link rel="index" href="ix05.html" title="Index of new symbols in 2.6">
<link rel="index" href="ix06.html" title="Index of new symbols in 2.8">
<link rel="index" href="ix07.html" title="Index of new symbols in 2.10">
<link rel="index" href="ix08.html" title="Index of new symbols in 2.12">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
<tr valign="middle">
<td><a accesskey="p" href="glib-Bookmark-file-parser.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
<td><a accesskey="u" href="glib-utilities.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
<th width="100%" align="center">GLib Reference Manual</th>
<td><a accesskey="n" href="glib-data-types.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
</tr>
<tr><td colspan="5" class="shortcuts"><nobr><a href="#id3189676" class="shortcut">Top</a>
 | 
<a href="#id3189883" class="shortcut">Description</a></nobr></td></tr>
</table>
<div class="refentry" lang="en">
<a name="glib-Windows-Compatibility-Functions"></a><div class="titlepage"></div>
<div class="refnamediv"><table width="100%"><tr>
<td valign="top">
<h2>
<a name="id3189676"></a><span class="refentrytitle">Windows Compatibility Functions</span>
</h2>
<p>Windows Compatibility Functions — UNIX emulation on Windows.</p>
</td>
<td valign="top" align="right"></td>
</tr></table></div>
<div class="refsynopsisdiv">
<h2>Synopsis</h2>
<pre class="synopsis">
#include <glib.h>
#define <a href="glib-Windows-Compatibility-Functions.html#MAXPATHLEN:CAPS">MAXPATHLEN</a>
#define <a href="glib-Windows-Compatibility-Functions.html#pipe">pipe</a> (phandles)
<a href="glib-Basic-Types.html#gchar">gchar</a>* <a href="glib-Windows-Compatibility-Functions.html#g-win32-error-message">g_win32_error_message</a> (<a href="glib-Basic-Types.html#gint">gint</a> error);
<a href="glib-Basic-Types.html#gchar">gchar</a>* <a href="glib-Windows-Compatibility-Functions.html#g-win32-getlocale">g_win32_getlocale</a> (void);
<a href="glib-Basic-Types.html#gchar">gchar</a>* <a href="glib-Windows-Compatibility-Functions.html#g-win32-get-package-installation-directory">g_win32_get_package_installation_directory</a>
(<a href="glib-Basic-Types.html#gchar">gchar</a> *package,
<a href="glib-Basic-Types.html#gchar">gchar</a> *dll_name);
<a href="glib-Basic-Types.html#gchar">gchar</a>* <a href="glib-Windows-Compatibility-Functions.html#g-win32-get-package-installation-subdirectory">g_win32_get_package_installation_subdirectory</a>
(<a href="glib-Basic-Types.html#gchar">gchar</a> *package,
<a href="glib-Basic-Types.html#gchar">gchar</a> *dll_name,
<a href="glib-Basic-Types.html#gchar">gchar</a> *subdir);
<a href="glib-Basic-Types.html#guint">guint</a> <a href="glib-Windows-Compatibility-Functions.html#g-win32-get-windows-version">g_win32_get_windows_version</a> (void);
<a href="glib-Basic-Types.html#gchar">gchar</a>* <a href="glib-Windows-Compatibility-Functions.html#g-win32-locale-filename-from-utf8">g_win32_locale_filename_from_utf8</a>
(const <a href="glib-Basic-Types.html#gchar">gchar</a> *utf8filename);
#define <a href="glib-Windows-Compatibility-Functions.html#G-WIN32-DLLMAIN-FOR-DLL-NAME:CAPS">G_WIN32_DLLMAIN_FOR_DLL_NAME</a> (static, dll_name)
#define <a href="glib-Windows-Compatibility-Functions.html#G-WIN32-HAVE-WIDECHAR-API:CAPS">G_WIN32_HAVE_WIDECHAR_API</a> ()
#define <a href="glib-Windows-Compatibility-Functions.html#G-WIN32-IS-NT-BASED:CAPS">G_WIN32_IS_NT_BASED</a> ()
</pre>
</div>
<div class="refsect1" lang="en">
<a name="id3189883"></a><h2>Description</h2>
<p>
These functions provide some level of UNIX emulation on the Windows platform.
If your application really needs the POSIX APIs, we suggest you try the Cygwin
project.
</p>
</div>
<div class="refsect1" lang="en">
<a name="id3189900"></a><h2>Details</h2>
<div class="refsect2" lang="en">
<a name="id3189910"></a><h3>
<a name="MAXPATHLEN:CAPS"></a>MAXPATHLEN</h3>
<a class="indexterm" name="id3189923"></a><pre class="programlisting">#define MAXPATHLEN 1024
</pre>
<p>
Provided for UNIX emulation on Windows; equivalent to UNIX
macro <a href="glib-Windows-Compatibility-Functions.html#MAXPATHLEN:CAPS"><code class="literal">MAXPATHLEN</code></a>, which is the maximum length of a filename
(including full path).
</p>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id3189951"></a><h3>
<a name="pipe"></a>pipe()</h3>
<a class="indexterm" name="id3189963"></a><pre class="programlisting">#define pipe(phandles) _pipe (phandles, 4096, _O_BINARY)
</pre>
<p>
Provided for UNIX emulation on Windows; see documentation for <code class="function"><a href="glib-Windows-Compatibility-Functions.html#pipe"><code class="function">pipe()</code></a></code>
in any UNIX manual.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td>
<span class="term"><em class="parameter"><code>phandles</code></em> :</span></td>
<td>file descriptors, the first one for reading, the second one for writing.
</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id3190013"></a><h3>
<a name="g-win32-error-message"></a>g_win32_error_message ()</h3>
<a class="indexterm" name="id3190026"></a><pre class="programlisting"><a href="glib-Basic-Types.html#gchar">gchar</a>* g_win32_error_message (<a href="glib-Basic-Types.html#gint">gint</a> error);</pre>
<p>
Translate a Win32 error code (as returned by <code class="function">GetLastError()</code>) into
the corresponding message. The message is either language neutral,
or in the thread's language, or the user's language, the system's
language, or US English (see docs for <code class="function">FormatMessage()</code>). The
returned string is in UTF-8. It should be deallocated with
<a href="glib-Memory-Allocation.html#g-free"><code class="function">g_free()</code></a>.</p>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>error</code></em> :</span></td>
<td> error code.
</td>
</tr>
<tr>
<td>
<span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
<td> newly-allocated error message
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id3190124"></a><h3>
<a name="g-win32-getlocale"></a>g_win32_getlocale ()</h3>
<a class="indexterm" name="id3190137"></a><pre class="programlisting"><a href="glib-Basic-Types.html#gchar">gchar</a>* g_win32_getlocale (void);</pre>
<p>
The <code class="function">setlocale()</code> function in the Microsoft C library uses locale
names of the form "English_United States.1252" etc. We want the
UNIXish standard form "en_US", "zh_TW" etc. This function gets the
current thread locale from Windows - without any encoding info -
and returns it as a string of the above form for use in forming
file names etc. The returned string should be deallocated with
<a href="glib-Memory-Allocation.html#g-free"><code class="function">g_free()</code></a>.</p>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td>
<span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
<td> newly-allocated locale name.
</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id3190204"></a><h3>
<a name="g-win32-get-package-installation-directory"></a>g_win32_get_package_installation_directory ()</h3>
<a class="indexterm" name="id3190219"></a><pre class="programlisting"><a href="glib-Basic-Types.html#gchar">gchar</a>* g_win32_get_package_installation_directory
(<a href="glib-Basic-Types.html#gchar">gchar</a> *package,
<a href="glib-Basic-Types.html#gchar">gchar</a> *dll_name);</pre>
<p>
Try to determine the installation directory for a software package.
Typically used by GNU software packages.
</p>
<p>
<em class="parameter"><code>package</code></em> should be a short identifier for the package. Typically it
is the same identifier as used for
<code class="literal">GETTEXT_PACKAGE</code> in software configured according
to GNU standards. The function first looks in the Windows Registry
for the value <code class="literal">#InstallationDirectory</code> in the key
<code class="literal">#HKLM\Software\<em class="parameter"><code>package</code></em></code>, and if that value
exists and is a string, returns that.
</p>
<p>
If <em class="parameter"><code>package</code></em> is <a href="glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>, or the above value isn't found in the
Registry, but <em class="parameter"><code>dll_name</code></em> is non-<a href="glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>, it should name a DLL loaded
into the current process. Typically that would be the name of the
DLL calling this function, looking for its installation
directory. The function then asks Windows what directory that DLL
was loaded from. If that directory's last component is "bin" or
"lib", the parent directory is returned, otherwise the directory
itself. If that DLL isn't loaded, the function proceeds as if
<em class="parameter"><code>dll_name</code></em> was <a href="glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>.
</p>
<p>
If both <em class="parameter"><code>package</code></em> and <em class="parameter"><code>dll_name</code></em> are <a href="glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>, the directory from where
the main executable of the process was loaded is used instead in
the same way as above.</p>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>package</code></em> :</span></td>
<td> An identifier for a software package, or <a href="glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>, in UTF-8
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>dll_name</code></em> :</span></td>
<td> The name of a DLL that a package provides, or <a href="glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>, in UTF-8
</td>
</tr>
<tr>
<td>
<span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
<td> a string containing the installation directory for
<em class="parameter"><code>package</code></em>. The string is in the GLib file name encoding, i.e. UTF-8
on Windows. The return value should be freed with <a href="glib-Memory-Allocation.html#g-free"><code class="function">g_free()</code></a> when not
needed any longer.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id3189654"></a><h3>
<a name="g-win32-get-package-installation-subdirectory"></a>g_win32_get_package_installation_subdirectory ()</h3>
<a class="indexterm" name="id3190618"></a><pre class="programlisting"><a href="glib-Basic-Types.html#gchar">gchar</a>* g_win32_get_package_installation_subdirectory
(<a href="glib-Basic-Types.html#gchar">gchar</a> *package,
<a href="glib-Basic-Types.html#gchar">gchar</a> *dll_name,
<a href="glib-Basic-Types.html#gchar">gchar</a> *subdir);</pre>
<p>
Returns a newly-allocated string containing the path of the
subdirectory <em class="parameter"><code>subdir</code></em> in the return value from calling
<a href="glib-Windows-Compatibility-Functions.html#g-win32-get-package-installation-directory"><code class="function">g_win32_get_package_installation_directory()</code></a> with the <em class="parameter"><code>package</code></em> and
<em class="parameter"><code>dll_name</code></em> parameters.</p>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>package</code></em> :</span></td>
<td> An identifier for a software package, in UTF-8, or <a href="glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>dll_name</code></em> :</span></td>
<td> The name of a DLL that a package provides, in UTF-8, or <a href="glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>subdir</code></em> :</span></td>
<td> A subdirectory of the package installation directory, also in UTF-8
</td>
</tr>
<tr>
<td>
<span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
<td> a string containing the complete path to <em class="parameter"><code>subdir</code></em> inside
the installation directory of <em class="parameter"><code>package</code></em>. The returned string is in
the GLib file name encoding, i.e. UTF-8 on Windows. The return
value should be freed with <a href="glib-Memory-Allocation.html#g-free"><code class="function">g_free()</code></a> when no longer needed.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id3190802"></a><h3>
<a name="g-win32-get-windows-version"></a>g_win32_get_windows_version ()</h3>
<a class="indexterm" name="id3190818"></a><pre class="programlisting"><a href="glib-Basic-Types.html#guint">guint</a> g_win32_get_windows_version (void);</pre>
<p>
Returns version information for the Windows operating system the
code is running on. See MSDN documentation for the <code class="function">GetVersion()</code>
function. To summarize, the most significant bit is one on Win9x,
and zero on NT-based systems. The least significant byte is 4 on
Windows NT 4, 5 on Windows XP. Software that needs really detailled
version and feature information should use Win32 API like
<code class="function">GetVersionEx()</code> and <code class="function">VerifyVersionInfo()</code>.
</p>
<p>
If there is an environment variable <code class="envar">G_WIN32_PRETEND_WIN9X</code>
defined (with any value), this function always returns a version
code for Windows 9x. This is mainly an internal debugging aid for
GTK+ and GLib developers, to be able to check the code paths for
Windows 9x.</p>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td>
<span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
<td> The version information.
</td>
</tr></tbody>
</table></div>
<p>Since 2.6
</p>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id3190914"></a><h3>
<a name="g-win32-locale-filename-from-utf8"></a>g_win32_locale_filename_from_utf8 ()</h3>
<a class="indexterm" name="id3190930"></a><pre class="programlisting"><a href="glib-Basic-Types.html#gchar">gchar</a>* g_win32_locale_filename_from_utf8
(const <a href="glib-Basic-Types.html#gchar">gchar</a> *utf8filename);</pre>
<p>
Converts a filename from UTF-8 to the system codepage.
</p>
<p>
On NT-based Windows, on NTFS file systems, file names are in
Unicode. It is quite possible that Unicode file names contain
characters not representable in the system codepage. (For instance,
Greek or Cyrillic characters on Western European or US Windows
installations, or various less common CJK characters on CJK Windows
installations.)
</p>
<p>
In such a case, and if the filename refers to an existing file, and
the file system stores alternate short (8.3) names for directory
entries, the short form of the filename is returned. Note that the
"short" name might in fact be longer than the Unicode name if the
Unicode name has very short pathname components containing
non-ASCII characters. If no system codepage name for the file is
possible, <a href="glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> is returned.
</p>
<p>
The return value is dynamically allocated and should be freed with
<a href="glib-Memory-Allocation.html#g-free"><code class="function">g_free()</code></a> when no longer needed.</p>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>utf8filename</code></em> :</span></td>
<td> a UTF-8 encoded filename.
</td>
</tr>
<tr>
<td>
<span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
<td> The converted filename, or <a href="glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> on conversion
failure and lack of short names.
</td>
</tr>
</tbody>
</table></div>
<p>Since 2.8
</p>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id3191052"></a><h3>
<a name="G-WIN32-DLLMAIN-FOR-DLL-NAME:CAPS"></a>G_WIN32_DLLMAIN_FOR_DLL_NAME()</h3>
<a class="indexterm" name="id3191066"></a><pre class="programlisting">#define G_WIN32_DLLMAIN_FOR_DLL_NAME(static, dll_name)</pre>
<p>
On Windows, this macro defines a <code class="function"><code class="function">DllMain()</code></code> function
that stores the actual DLL name that the code being compiled will be
included in.
</p>
<p>
On non-Windows platforms, expands to nothing.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>static</code></em> :</span></td>
<td>empty or "static".
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>dll_name</code></em> :</span></td>
<td>the name of the (pointer to the) char array where the DLL name
will be stored. If this is used, you must also include
<code class="filename">windows.h</code>. If you need a more complex DLL entry
point function, you cannot use this.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id3191144"></a><h3>
<a name="G-WIN32-HAVE-WIDECHAR-API:CAPS"></a>G_WIN32_HAVE_WIDECHAR_API()</h3>
<a class="indexterm" name="id3191160"></a><pre class="programlisting">#define G_WIN32_HAVE_WIDECHAR_API() (G_WIN32_IS_NT_BASED ())
</pre>
<p>
On Windows, this macro defines an expression which evaluates to <a href="glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a>
if the code is running on a version of Windows where the wide
character versions of the Win32 API functions, and the wide chaacter
versions of the C library functions work. (They are always present in
the DLLs, but don't work on Windows 9x and Me.)
</p>
<p>
On non-Windows platforms, it is not defined.
</p>
<p>Since 2.6
</p>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id3191200"></a><h3>
<a name="G-WIN32-IS-NT-BASED:CAPS"></a>G_WIN32_IS_NT_BASED()</h3>
<a class="indexterm" name="id3191215"></a><pre class="programlisting">#define G_WIN32_IS_NT_BASED() (g_win32_get_windows_version () < 0x80000000)
</pre>
<p>
On Windows, this macro defines an expression which evaluates to <a href="glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a>
if the code is running on an NT-based Windows operating system.
</p>
<p>
On non-Windows platforms, it is not defined.
</p>
<p>Since 2.6
</p>
</div>
</div>
</div>
</body>
</html>