glib/auto/
functions.rs

1// This file was generated by gir (https://github.com/gtk-rs/gir)
2// from gir-files (https://github.com/gtk-rs/gir-files)
3// DO NOT EDIT
4
5#[cfg(feature = "v2_66")]
6#[cfg_attr(docsrs, doc(cfg(feature = "v2_66")))]
7use crate::FileSetContentsFlags;
8use crate::{
9    ffi, translate::*, Bytes, ChecksumType, Error, FileTest, FormatSizeFlags, Pid, Source,
10    SpawnFlags, UserDirectory,
11};
12use std::boxed::Box as Box_;
13
14/// A wrapper for the POSIX access() function. This function is used to
15/// test a pathname for one or several of read, write or execute
16/// permissions, or just existence.
17///
18/// On Windows, the file protection mechanism is not at all POSIX-like,
19/// and the underlying function in the C library only checks the
20/// FAT-style READONLY attribute, and does not look at the ACL of a
21/// file at all. This function is this in practise almost useless on
22/// Windows. Software that needs to handle file permissions on Windows
23/// more exactly should use the Win32 API.
24///
25/// See your C library manual for more details about access().
26/// ## `filename`
27/// a pathname in the GLib file name encoding
28///     (UTF-8 on Windows)
29/// ## `mode`
30/// as in access()
31///
32/// # Returns
33///
34/// zero if the pathname refers to an existing file system
35///     object that has all the tested permissions, or -1 otherwise
36///     or on error.
37#[doc(alias = "g_access")]
38pub fn access(filename: impl AsRef<std::path::Path>, mode: i32) -> i32 {
39    unsafe { ffi::g_access(filename.as_ref().to_glib_none().0, mode) }
40}
41
42/// Decode a sequence of Base-64 encoded text into binary data.  Note
43/// that the returned binary data is not necessarily zero-terminated,
44/// so it should not be used as a character string.
45/// ## `text`
46/// zero-terminated string with base64 text to decode
47///
48/// # Returns
49///
50///
51///               newly allocated buffer containing the binary data
52///               that @text represents. The returned buffer must
53///               be freed with g_free().
54#[doc(alias = "g_base64_decode")]
55pub fn base64_decode(text: &str) -> Vec<u8> {
56    unsafe {
57        let mut out_len = std::mem::MaybeUninit::uninit();
58        let ret = FromGlibContainer::from_glib_full_num(
59            ffi::g_base64_decode(text.to_glib_none().0, out_len.as_mut_ptr()),
60            out_len.assume_init() as _,
61        );
62        ret
63    }
64}
65
66//#[doc(alias = "g_base64_decode_inplace")]
67//pub fn base64_decode_inplace(text: /*Unimplemented*/Vec<u8>) -> u8 {
68//    unsafe { TODO: call ffi:g_base64_decode_inplace() }
69//}
70
71//#[doc(alias = "g_base64_decode_step")]
72//pub fn base64_decode_step(in_: &[u8], out: Vec<u8>, state: &mut i32, save: &mut u32) -> usize {
73//    unsafe { TODO: call ffi:g_base64_decode_step() }
74//}
75
76/// Encode a sequence of binary data into its Base-64 stringified
77/// representation.
78/// ## `data`
79/// the binary data to encode
80///
81/// # Returns
82///
83/// a newly allocated, zero-terminated Base-64
84///               encoded string representing @data. The returned string must
85///               be freed with g_free().
86#[doc(alias = "g_base64_encode")]
87pub fn base64_encode(data: &[u8]) -> crate::GString {
88    let len = data.len() as _;
89    unsafe { from_glib_full(ffi::g_base64_encode(data.to_glib_none().0, len)) }
90}
91
92//#[doc(alias = "g_base64_encode_close")]
93//pub fn base64_encode_close(break_lines: bool, out: Vec<u8>, state: &mut i32, save: &mut i32) -> usize {
94//    unsafe { TODO: call ffi:g_base64_encode_close() }
95//}
96
97//#[doc(alias = "g_base64_encode_step")]
98//pub fn base64_encode_step(in_: &[u8], break_lines: bool, out: Vec<u8>, state: &mut i32, save: &mut i32) -> usize {
99//    unsafe { TODO: call ffi:g_base64_encode_step() }
100//}
101
102/// Checks that the GLib library in use is compatible with the
103/// given version.
104///
105/// Generally you would pass in the constants `GLIB_MAJOR_VERSION`,
106/// `GLIB_MINOR_VERSION`, `GLIB_MICRO_VERSION` as the three arguments
107/// to this function; that produces a check that the library in use
108/// is compatible with the version of GLib the application or module
109/// was compiled against.
110///
111/// Compatibility is defined by two things: first the version
112/// of the running library is newer than the version
113/// `@required_major.required_minor.@required_micro`. Second
114/// the running library must be binary compatible with the
115/// version `@required_major.@required_minor.@required_micro`
116/// (same major version.)
117/// ## `required_major`
118/// the required major version
119/// ## `required_minor`
120/// the required minor version
121/// ## `required_micro`
122/// the required micro version
123///
124/// # Returns
125///
126/// [`None`] if the GLib library is
127///   compatible with the given version, or a string describing the
128///   version mismatch. The returned string is owned by GLib and must
129///   not be modified or freed.
130#[doc(alias = "glib_check_version")]
131pub fn check_version(
132    required_major: u32,
133    required_minor: u32,
134    required_micro: u32,
135) -> Option<crate::GString> {
136    unsafe {
137        from_glib_none(ffi::glib_check_version(
138            required_major,
139            required_minor,
140            required_micro,
141        ))
142    }
143}
144
145/// Computes the checksum for a binary @data. This is a
146/// convenience wrapper for g_checksum_new(), g_checksum_get_string()
147/// and g_checksum_free().
148///
149/// The hexadecimal string returned will be in lower case.
150/// ## `checksum_type`
151/// a #GChecksumType
152/// ## `data`
153/// binary blob to compute the digest of
154///
155/// # Returns
156///
157/// the digest of the binary data as a
158///   string in hexadecimal, or [`None`] if g_checksum_new() fails for
159///   @checksum_type. The returned string should be freed with g_free() when
160///   done using it.
161#[doc(alias = "g_compute_checksum_for_bytes")]
162pub fn compute_checksum_for_bytes(
163    checksum_type: ChecksumType,
164    data: &Bytes,
165) -> Option<crate::GString> {
166    unsafe {
167        from_glib_full(ffi::g_compute_checksum_for_bytes(
168            checksum_type.into_glib(),
169            data.to_glib_none().0,
170        ))
171    }
172}
173
174/// Computes the checksum for a binary @data of @length. This is a
175/// convenience wrapper for g_checksum_new(), g_checksum_get_string()
176/// and g_checksum_free().
177///
178/// The hexadecimal string returned will be in lower case.
179/// ## `checksum_type`
180/// a #GChecksumType
181/// ## `data`
182/// binary blob to compute the digest of
183///
184/// # Returns
185///
186/// the digest of the binary data as a
187///   string in hexadecimal, or [`None`] if g_checksum_new() fails for
188///   @checksum_type. The returned string should be freed with g_free() when
189///   done using it.
190#[doc(alias = "g_compute_checksum_for_data")]
191pub fn compute_checksum_for_data(
192    checksum_type: ChecksumType,
193    data: &[u8],
194) -> Option<crate::GString> {
195    let length = data.len() as _;
196    unsafe {
197        from_glib_full(ffi::g_compute_checksum_for_data(
198            checksum_type.into_glib(),
199            data.to_glib_none().0,
200            length,
201        ))
202    }
203}
204
205/// Computes the HMAC for a binary @data. This is a
206/// convenience wrapper for g_hmac_new(), g_hmac_get_string()
207/// and g_hmac_unref().
208///
209/// The hexadecimal string returned will be in lower case.
210/// ## `digest_type`
211/// a #GChecksumType to use for the HMAC
212/// ## `key`
213/// the key to use in the HMAC
214/// ## `data`
215/// binary blob to compute the HMAC of
216///
217/// # Returns
218///
219/// the HMAC of the binary data as a string in hexadecimal.
220///   The returned string should be freed with g_free() when done using it.
221#[doc(alias = "g_compute_hmac_for_bytes")]
222pub fn compute_hmac_for_bytes(
223    digest_type: ChecksumType,
224    key: &Bytes,
225    data: &Bytes,
226) -> crate::GString {
227    unsafe {
228        from_glib_full(ffi::g_compute_hmac_for_bytes(
229            digest_type.into_glib(),
230            key.to_glib_none().0,
231            data.to_glib_none().0,
232        ))
233    }
234}
235
236/// Computes the HMAC for a binary @data of @length. This is a
237/// convenience wrapper for g_hmac_new(), g_hmac_get_string()
238/// and g_hmac_unref().
239///
240/// The hexadecimal string returned will be in lower case.
241/// ## `digest_type`
242/// a #GChecksumType to use for the HMAC
243/// ## `key`
244/// the key to use in the HMAC
245/// ## `data`
246/// binary blob to compute the HMAC of
247///
248/// # Returns
249///
250/// the HMAC of the binary data as a string in hexadecimal.
251///   The returned string should be freed with g_free() when done using it.
252#[doc(alias = "g_compute_hmac_for_data")]
253pub fn compute_hmac_for_data(digest_type: ChecksumType, key: &[u8], data: &[u8]) -> crate::GString {
254    let key_len = key.len() as _;
255    let length = data.len() as _;
256    unsafe {
257        from_glib_full(ffi::g_compute_hmac_for_data(
258            digest_type.into_glib(),
259            key.to_glib_none().0,
260            key_len,
261            data.to_glib_none().0,
262            length,
263        ))
264    }
265}
266
267/// This is a variant of g_dgettext() that allows specifying a locale
268/// category instead of always using `LC_MESSAGES`. See g_dgettext() for
269/// more information about how this functions differs from calling
270/// dcgettext() directly.
271/// ## `domain`
272/// the translation domain to use, or [`None`] to use
273///   the domain set with textdomain()
274/// ## `msgid`
275/// message to translate
276/// ## `category`
277/// a locale category
278///
279/// # Returns
280///
281/// the translated string for the given locale category
282#[doc(alias = "g_dcgettext")]
283pub fn dcgettext(domain: Option<&str>, msgid: &str, category: i32) -> crate::GString {
284    unsafe {
285        from_glib_none(ffi::g_dcgettext(
286            domain.to_glib_none().0,
287            msgid.to_glib_none().0,
288            category,
289        ))
290    }
291}
292
293/// This function is a wrapper of dgettext() which does not translate
294/// the message if the default domain as set with textdomain() has no
295/// translations for the current locale.
296///
297/// The advantage of using this function over dgettext() proper is that
298/// libraries using this function (like GTK) will not use translations
299/// if the application using the library does not have translations for
300/// the current locale.  This results in a consistent English-only
301/// interface instead of one having partial translations.  For this
302/// feature to work, the call to textdomain() and setlocale() should
303/// precede any g_dgettext() invocations.  For GTK, it means calling
304/// textdomain() before gtk_init or its variants.
305///
306/// This function disables translations if and only if upon its first
307/// call all the following conditions hold:
308///
309/// - @domain is not [`None`]
310///
311/// - textdomain() has been called to set a default text domain
312///
313/// - there is no translations available for the default text domain
314///   and the current locale
315///
316/// - current locale is not "C" or any English locales (those
317///   starting with "en_")
318///
319/// Note that this behavior may not be desired for example if an application
320/// has its untranslated messages in a language other than English. In those
321/// cases the application should call textdomain() after initializing GTK.
322///
323/// Applications should normally not use this function directly,
324/// but use the _() macro for translations.
325/// ## `domain`
326/// the translation domain to use, or [`None`] to use
327///   the domain set with textdomain()
328/// ## `msgid`
329/// message to translate
330///
331/// # Returns
332///
333/// The translated string
334#[doc(alias = "g_dgettext")]
335pub fn dgettext(domain: Option<&str>, msgid: &str) -> crate::GString {
336    unsafe {
337        from_glib_none(ffi::g_dgettext(
338            domain.to_glib_none().0,
339            msgid.to_glib_none().0,
340        ))
341    }
342}
343
344/// This function is a wrapper of dngettext() which does not translate
345/// the message if the default domain as set with textdomain() has no
346/// translations for the current locale.
347///
348/// See g_dgettext() for details of how this differs from dngettext()
349/// proper.
350/// ## `domain`
351/// the translation domain to use, or [`None`] to use
352///   the domain set with textdomain()
353/// ## `msgid`
354/// message to translate
355/// ## `msgid_plural`
356/// plural form of the message
357/// ## `n`
358/// the quantity for which translation is needed
359///
360/// # Returns
361///
362/// The translated string
363#[doc(alias = "g_dngettext")]
364pub fn dngettext(
365    domain: Option<&str>,
366    msgid: &str,
367    msgid_plural: &str,
368    n: libc::c_ulong,
369) -> crate::GString {
370    unsafe {
371        from_glib_none(ffi::g_dngettext(
372            domain.to_glib_none().0,
373            msgid.to_glib_none().0,
374            msgid_plural.to_glib_none().0,
375            n,
376        ))
377    }
378}
379
380/// This function is a variant of g_dgettext() which supports
381/// a disambiguating message context. GNU gettext uses the
382/// '\004' character to separate the message context and
383/// message id in @msgctxtid.
384/// If 0 is passed as @msgidoffset, this function will fall back to
385/// trying to use the deprecated convention of using "|" as a separation
386/// character.
387///
388/// This uses g_dgettext() internally. See that functions for differences
389/// with dgettext() proper.
390///
391/// Applications should normally not use this function directly,
392/// but use the C_() macro for translations with context.
393/// ## `domain`
394/// the translation domain to use, or [`None`] to use
395///   the domain set with textdomain()
396/// ## `msgctxtid`
397/// a combined message context and message id, separated
398///   by a \004 character
399/// ## `msgidoffset`
400/// the offset of the message id in @msgctxid
401///
402/// # Returns
403///
404/// The translated string
405#[doc(alias = "g_dpgettext")]
406pub fn dpgettext(domain: Option<&str>, msgctxtid: &str, msgidoffset: usize) -> crate::GString {
407    unsafe {
408        from_glib_none(ffi::g_dpgettext(
409            domain.to_glib_none().0,
410            msgctxtid.to_glib_none().0,
411            msgidoffset,
412        ))
413    }
414}
415
416/// This function is a variant of g_dgettext() which supports
417/// a disambiguating message context. GNU gettext uses the
418/// '\004' character to separate the message context and
419/// message id in @msgctxtid.
420///
421/// This uses g_dgettext() internally. See that functions for differences
422/// with dgettext() proper.
423///
424/// This function differs from C_() in that it is not a macro and
425/// thus you may use non-string-literals as context and msgid arguments.
426/// ## `domain`
427/// the translation domain to use, or [`None`] to use
428///   the domain set with textdomain()
429/// ## `context`
430/// the message context
431/// ## `msgid`
432/// the message
433///
434/// # Returns
435///
436/// The translated string
437#[doc(alias = "g_dpgettext2")]
438pub fn dpgettext2(domain: Option<&str>, context: &str, msgid: &str) -> crate::GString {
439    unsafe {
440        from_glib_none(ffi::g_dpgettext2(
441            domain.to_glib_none().0,
442            context.to_glib_none().0,
443            msgid.to_glib_none().0,
444        ))
445    }
446}
447
448/// Writes all of @contents to a file named @filename. This is a convenience
449/// wrapper around calling g_file_set_contents_full() with `flags` set to
450/// `G_FILE_SET_CONTENTS_CONSISTENT | G_FILE_SET_CONTENTS_ONLY_EXISTING` and
451/// `mode` set to `0666`.
452/// ## `filename`
453/// name of a file to write @contents to, in the GLib file name
454///   encoding
455/// ## `contents`
456/// string to write to the file
457///
458/// # Returns
459///
460/// [`true`] on success, [`false`] if an error occurred
461#[doc(alias = "g_file_set_contents")]
462pub fn file_set_contents(
463    filename: impl AsRef<std::path::Path>,
464    contents: &[u8],
465) -> Result<(), crate::Error> {
466    let length = contents.len() as _;
467    unsafe {
468        let mut error = std::ptr::null_mut();
469        let is_ok = ffi::g_file_set_contents(
470            filename.as_ref().to_glib_none().0,
471            contents.to_glib_none().0,
472            length,
473            &mut error,
474        );
475        debug_assert_eq!(is_ok == crate::ffi::GFALSE, !error.is_null());
476        if error.is_null() {
477            Ok(())
478        } else {
479            Err(from_glib_full(error))
480        }
481    }
482}
483
484/// Writes all of @contents to a file named @filename, with good error checking.
485/// If a file called @filename already exists it will be overwritten.
486///
487/// @flags control the properties of the write operation: whether it’s atomic,
488/// and what the tradeoff is between returning quickly or being resilient to
489/// system crashes.
490///
491/// As this function performs file I/O, it is recommended to not call it anywhere
492/// where blocking would cause problems, such as in the main loop of a graphical
493/// application. In particular, if @flags has any value other than
494/// [`FileSetContentsFlags::NONE`][crate::FileSetContentsFlags::NONE] then this function may call `fsync()`.
495///
496/// If [`FileSetContentsFlags::CONSISTENT`][crate::FileSetContentsFlags::CONSISTENT] is set in @flags, the operation is atomic
497/// in the sense that it is first written to a temporary file which is then
498/// renamed to the final name.
499///
500/// Notes:
501///
502/// - On UNIX, if @filename already exists hard links to @filename will break.
503///   Also since the file is recreated, existing permissions, access control
504///   lists, metadata etc. may be lost. If @filename is a symbolic link,
505///   the link itself will be replaced, not the linked file.
506///
507/// - On UNIX, if @filename already exists and is non-empty, and if the system
508///   supports it (via a journalling filesystem or equivalent), and if
509///   [`FileSetContentsFlags::CONSISTENT`][crate::FileSetContentsFlags::CONSISTENT] is set in @flags, the `fsync()` call (or
510///   equivalent) will be used to ensure atomic replacement: @filename
511///   will contain either its old contents or @contents, even in the face of
512///   system power loss, the disk being unsafely removed, etc.
513///
514/// - On UNIX, if @filename does not already exist or is empty, there is a
515///   possibility that system power loss etc. after calling this function will
516///   leave @filename empty or full of NUL bytes, depending on the underlying
517///   filesystem, unless [`FileSetContentsFlags::DURABLE`][crate::FileSetContentsFlags::DURABLE] and
518///   [`FileSetContentsFlags::CONSISTENT`][crate::FileSetContentsFlags::CONSISTENT] are set in @flags.
519///
520/// - On Windows renaming a file will not remove an existing file with the
521///   new name, so on Windows there is a race condition between the existing
522///   file being removed and the temporary file being renamed.
523///
524/// - On Windows there is no way to remove a file that is open to some
525///   process, or mapped into memory. Thus, this function will fail if
526///   @filename already exists and is open.
527///
528/// If the call was successful, it returns [`true`]. If the call was not successful,
529/// it returns [`false`] and sets @error. The error domain is `G_FILE_ERROR`.
530/// Possible error codes are those in the #GFileError enumeration.
531///
532/// Note that the name for the temporary file is constructed by appending up
533/// to 7 characters to @filename.
534///
535/// If the file didn’t exist before and is created, it will be given the
536/// permissions from @mode. Otherwise, the permissions of the existing file will
537/// remain unchanged.
538/// ## `filename`
539/// name of a file to write @contents to, in the GLib file name
540///   encoding
541/// ## `contents`
542/// string to write to the file
543/// ## `flags`
544/// flags controlling the safety vs speed of the operation
545/// ## `mode`
546/// file mode, as passed to `open()`; typically this will be `0666`
547///
548/// # Returns
549///
550/// [`true`] on success, [`false`] if an error occurred
551#[cfg(feature = "v2_66")]
552#[cfg_attr(docsrs, doc(cfg(feature = "v2_66")))]
553#[doc(alias = "g_file_set_contents_full")]
554pub fn file_set_contents_full(
555    filename: impl AsRef<std::path::Path>,
556    contents: &[u8],
557    flags: FileSetContentsFlags,
558    mode: i32,
559) -> Result<(), crate::Error> {
560    let length = contents.len() as _;
561    unsafe {
562        let mut error = std::ptr::null_mut();
563        let is_ok = ffi::g_file_set_contents_full(
564            filename.as_ref().to_glib_none().0,
565            contents.to_glib_none().0,
566            length,
567            flags.into_glib(),
568            mode,
569            &mut error,
570        );
571        debug_assert_eq!(is_ok == crate::ffi::GFALSE, !error.is_null());
572        if error.is_null() {
573            Ok(())
574        } else {
575            Err(from_glib_full(error))
576        }
577    }
578}
579
580/// Returns [`true`] if any of the tests in the bitfield @test are
581/// [`true`]. For example, `(G_FILE_TEST_EXISTS | G_FILE_TEST_IS_DIR)`
582/// will return [`true`] if the file exists; the check whether it's a
583/// directory doesn't matter since the existence test is [`true`]. With
584/// the current set of available tests, there's no point passing in
585/// more than one test at a time.
586///
587/// Apart from [`FileTest::IS_SYMLINK`][crate::FileTest::IS_SYMLINK] all tests follow symbolic links,
588/// so for a symbolic link to a regular file g_file_test() will return
589/// [`true`] for both [`FileTest::IS_SYMLINK`][crate::FileTest::IS_SYMLINK] and [`FileTest::IS_REGULAR`][crate::FileTest::IS_REGULAR].
590///
591/// Note, that for a dangling symbolic link g_file_test() will return
592/// [`true`] for [`FileTest::IS_SYMLINK`][crate::FileTest::IS_SYMLINK] and [`false`] for all other flags.
593///
594/// You should never use g_file_test() to test whether it is safe
595/// to perform an operation, because there is always the possibility
596/// of the condition changing before you actually perform the operation,
597/// see [TOCTOU](https://en.wikipedia.org/wiki/Time-of-check_to_time-of-use).
598///
599/// For example, you might think you could use [`FileTest::IS_SYMLINK`][crate::FileTest::IS_SYMLINK]
600/// to know whether it is safe to write to a file without being
601/// tricked into writing into a different location. It doesn't work!
602///
603///
604///
605/// **⚠️ The following code is in C ⚠️**
606///
607/// ```C
608///  // DON'T DO THIS
609///  if (!g_file_test (filename, G_FILE_TEST_IS_SYMLINK))
610///    {
611///      fd = g_open (filename, O_WRONLY);
612///      // write to fd
613///    }
614///
615///  // DO THIS INSTEAD
616///  fd = g_open (filename, O_WRONLY | O_NOFOLLOW | O_CLOEXEC);
617///  if (fd == -1)
618///    {
619///      // check error
620///      if (errno == ELOOP)
621///        // file is a symlink and can be ignored
622///      else
623///        // handle errors as before
624///    }
625///  else
626///    {
627///      // write to fd
628///    }
629/// ```
630///
631/// Another thing to note is that [`FileTest::EXISTS`][crate::FileTest::EXISTS] and
632/// [`FileTest::IS_EXECUTABLE`][crate::FileTest::IS_EXECUTABLE] are implemented using the access()
633/// system call. This usually doesn't matter, but if your program
634/// is setuid or setgid it means that these tests will give you
635/// the answer for the real user ID and group ID, rather than the
636/// effective user ID and group ID.
637///
638/// On Windows, there are no symlinks, so testing for
639/// [`FileTest::IS_SYMLINK`][crate::FileTest::IS_SYMLINK] will always return [`false`]. Testing for
640/// [`FileTest::IS_EXECUTABLE`][crate::FileTest::IS_EXECUTABLE] will just check that the file exists and
641/// its name indicates that it is executable, checking for well-known
642/// extensions and those listed in the `PATHEXT` environment variable.
643/// ## `filename`
644/// a filename to test in the
645///     GLib file name encoding
646/// ## `test`
647/// bitfield of #GFileTest flags
648///
649/// # Returns
650///
651/// whether a test was [`true`]
652#[doc(alias = "g_file_test")]
653#[allow(dead_code)]
654pub(crate) fn file_test(filename: impl AsRef<std::path::Path>, test: FileTest) -> bool {
655    unsafe {
656        from_glib(ffi::g_file_test(
657            filename.as_ref().to_glib_none().0,
658            test.into_glib(),
659        ))
660    }
661}
662
663/// Returns the display basename for the particular filename, guaranteed
664/// to be valid UTF-8. The display name might not be identical to the filename,
665/// for instance there might be problems converting it to UTF-8, and some files
666/// can be translated in the display.
667///
668/// If GLib cannot make sense of the encoding of @filename, as a last resort it
669/// replaces unknown characters with U+FFFD, the Unicode replacement character.
670/// You can search the result for the UTF-8 encoding of this character (which is
671/// "\357\277\275" in octal notation) to find out if @filename was in an invalid
672/// encoding.
673///
674/// You must pass the whole absolute pathname to this functions so that
675/// translation of well known locations can be done.
676///
677/// This function is preferred over g_filename_display_name() if you know the
678/// whole path, as it allows translation.
679/// ## `filename`
680/// an absolute pathname in the
681///     GLib file name encoding
682///
683/// # Returns
684///
685/// a newly allocated string containing
686///   a rendition of the basename of the filename in valid UTF-8
687#[doc(alias = "g_filename_display_basename")]
688pub fn filename_display_basename(filename: impl AsRef<std::path::Path>) -> crate::GString {
689    unsafe {
690        from_glib_full(ffi::g_filename_display_basename(
691            filename.as_ref().to_glib_none().0,
692        ))
693    }
694}
695
696/// Converts a filename into a valid UTF-8 string. The conversion is
697/// not necessarily reversible, so you should keep the original around
698/// and use the return value of this function only for display purposes.
699/// Unlike g_filename_to_utf8(), the result is guaranteed to be non-[`None`]
700/// even if the filename actually isn't in the GLib file name encoding.
701///
702/// If GLib cannot make sense of the encoding of @filename, as a last resort it
703/// replaces unknown characters with U+FFFD, the Unicode replacement character.
704/// You can search the result for the UTF-8 encoding of this character (which is
705/// "\357\277\275" in octal notation) to find out if @filename was in an invalid
706/// encoding.
707///
708/// If you know the whole pathname of the file you should use
709/// g_filename_display_basename(), since that allows location-based
710/// translation of filenames.
711/// ## `filename`
712/// a pathname hopefully in the
713///     GLib file name encoding
714///
715/// # Returns
716///
717/// a newly allocated string containing
718///   a rendition of the filename in valid UTF-8
719#[doc(alias = "g_filename_display_name")]
720pub fn filename_display_name(filename: impl AsRef<std::path::Path>) -> crate::GString {
721    unsafe {
722        from_glib_full(ffi::g_filename_display_name(
723            filename.as_ref().to_glib_none().0,
724        ))
725    }
726}
727
728/// Converts an escaped ASCII-encoded URI to a local filename in the
729/// encoding used for filenames.
730///
731/// Since GLib 2.78, the query string and fragment can be present in the URI,
732/// but are not part of the resulting filename.
733/// We take inspiration from https://url.spec.whatwg.org/#file-state,
734/// but we don't support the entire standard.
735/// ## `uri`
736/// a uri describing a filename (escaped, encoded in ASCII).
737///
738/// # Returns
739///
740/// a newly-allocated string holding
741///               the resulting filename, or [`None`] on an error.
742///
743/// ## `hostname`
744/// Location to store hostname for the URI.
745///            If there is no hostname in the URI, [`None`] will be
746///            stored in this location.
747#[doc(alias = "g_filename_from_uri")]
748pub fn filename_from_uri(
749    uri: &str,
750) -> Result<(std::path::PathBuf, Option<crate::GString>), crate::Error> {
751    unsafe {
752        let mut hostname = std::ptr::null_mut();
753        let mut error = std::ptr::null_mut();
754        let ret = ffi::g_filename_from_uri(uri.to_glib_none().0, &mut hostname, &mut error);
755        if error.is_null() {
756            Ok((from_glib_full(ret), from_glib_full(hostname)))
757        } else {
758            Err(from_glib_full(error))
759        }
760    }
761}
762
763/// Converts an absolute filename to an escaped ASCII-encoded URI, with the path
764/// component following Section 3.3. of RFC 2396.
765/// ## `filename`
766/// an absolute filename specified in the GLib file
767///     name encoding, which is the on-disk file name bytes on Unix, and UTF-8
768///     on Windows
769/// ## `hostname`
770/// A UTF-8 encoded hostname, or [`None`] for none.
771///
772/// # Returns
773///
774/// a newly-allocated string holding the resulting
775///               URI, or [`None`] on an error.
776#[doc(alias = "g_filename_to_uri")]
777pub fn filename_to_uri(
778    filename: impl AsRef<std::path::Path>,
779    hostname: Option<&str>,
780) -> Result<crate::GString, crate::Error> {
781    unsafe {
782        let mut error = std::ptr::null_mut();
783        let ret = ffi::g_filename_to_uri(
784            filename.as_ref().to_glib_none().0,
785            hostname.to_glib_none().0,
786            &mut error,
787        );
788        if error.is_null() {
789            Ok(from_glib_full(ret))
790        } else {
791            Err(from_glib_full(error))
792        }
793    }
794}
795
796/// Locates the first executable named @program in the user's path, in the
797/// same way that execvp() would locate it. Returns an allocated string
798/// with the absolute path name, or [`None`] if the program is not found in
799/// the path. If @program is already an absolute path, returns a copy of
800/// @program if @program exists and is executable, and [`None`] otherwise.
801///
802/// On Windows, if @program does not have a file type suffix, tries
803/// with the suffixes .exe, .cmd, .bat and .com, and the suffixes in
804/// the `PATHEXT` environment variable.
805///
806/// On Windows, it looks for the file in the same way as CreateProcess()
807/// would. This means first in the directory where the executing
808/// program was loaded from, then in the current directory, then in the
809/// Windows 32-bit system directory, then in the Windows directory, and
810/// finally in the directories in the `PATH` environment variable. If
811/// the program is found, the return value contains the full name
812/// including the type suffix.
813/// ## `program`
814/// a program name in the GLib file name encoding
815///
816/// # Returns
817///
818/// a newly-allocated
819///   string with the absolute path, or [`None`]
820#[doc(alias = "g_find_program_in_path")]
821pub fn find_program_in_path(program: impl AsRef<std::path::Path>) -> Option<std::path::PathBuf> {
822    unsafe {
823        from_glib_full(ffi::g_find_program_in_path(
824            program.as_ref().to_glib_none().0,
825        ))
826    }
827}
828
829/// Formats a size (for example the size of a file) into a human readable
830/// string.  Sizes are rounded to the nearest size prefix (kB, MB, GB)
831/// and are displayed rounded to the nearest tenth. E.g. the file size
832/// 3292528 bytes will be converted into the string "3.2 MB". The returned string
833/// is UTF-8, and may use a non-breaking space to separate the number and units,
834/// to ensure they aren’t separated when line wrapped.
835///
836/// The prefix units base is 1000 (i.e. 1 kB is 1000 bytes).
837///
838/// This string should be freed with g_free() when not needed any longer.
839///
840/// See g_format_size_full() for more options about how the size might be
841/// formatted.
842/// ## `size`
843/// a size in bytes
844///
845/// # Returns
846///
847/// a newly-allocated formatted string containing
848///   a human readable file size
849#[doc(alias = "g_format_size")]
850pub fn format_size(size: u64) -> crate::GString {
851    unsafe { from_glib_full(ffi::g_format_size(size)) }
852}
853
854/// Formats a size.
855///
856/// This function is similar to g_format_size() but allows for flags
857/// that modify the output. See #GFormatSizeFlags.
858/// ## `size`
859/// a size in bytes
860/// ## `flags`
861/// #GFormatSizeFlags to modify the output
862///
863/// # Returns
864///
865/// a newly-allocated formatted string
866///   containing a human readable file size
867#[doc(alias = "g_format_size_full")]
868pub fn format_size_full(size: u64, flags: FormatSizeFlags) -> crate::GString {
869    unsafe { from_glib_full(ffi::g_format_size_full(size, flags.into_glib())) }
870}
871
872/// Gets a human-readable name for the application, as set by
873/// g_set_application_name(). This name should be localized if
874/// possible, and is intended for display to the user.  Contrast with
875/// g_get_prgname(), which gets a non-localized name. If
876/// g_set_application_name() has not been called, returns the result of
877/// g_get_prgname() (which may be [`None`] if g_set_prgname() has also not
878/// been called).
879///
880/// # Returns
881///
882/// human-readable application
883///   name. May return [`None`]
884#[doc(alias = "g_get_application_name")]
885#[doc(alias = "get_application_name")]
886pub fn application_name() -> Option<crate::GString> {
887    unsafe { from_glib_none(ffi::g_get_application_name()) }
888}
889
890/// Gets the character set for the current locale.
891///
892/// # Returns
893///
894/// a newly allocated string containing the name
895///     of the character set. This string must be freed with g_free().
896#[doc(alias = "g_get_codeset")]
897#[doc(alias = "get_codeset")]
898pub fn codeset() -> crate::GString {
899    unsafe { from_glib_full(ffi::g_get_codeset()) }
900}
901
902/// Obtains the character set used by the console attached to the process,
903/// which is suitable for printing output to the terminal.
904///
905/// Usually this matches the result returned by g_get_charset(), but in
906/// environments where the locale's character set does not match the encoding
907/// of the console this function tries to guess a more suitable value instead.
908///
909/// On Windows the character set returned by this function is the
910/// output code page used by the console associated with the calling process.
911/// If the codepage can't be determined (for example because there is no
912/// console attached) UTF-8 is assumed.
913///
914/// The return value is [`true`] if the locale's encoding is UTF-8, in that
915/// case you can perhaps avoid calling g_convert().
916///
917/// The string returned in @charset is not allocated, and should not be
918/// freed.
919///
920/// # Returns
921///
922/// [`true`] if the returned charset is UTF-8
923///
924/// ## `charset`
925/// return location for character set
926///   name, or [`None`].
927#[cfg(feature = "v2_62")]
928#[cfg_attr(docsrs, doc(cfg(feature = "v2_62")))]
929#[doc(alias = "g_get_console_charset")]
930#[doc(alias = "get_console_charset")]
931pub fn console_charset() -> Option<crate::GString> {
932    unsafe {
933        let mut charset = std::ptr::null();
934        let ret = from_glib(ffi::g_get_console_charset(&mut charset));
935        if ret {
936            Some(from_glib_none(charset))
937        } else {
938            None
939        }
940    }
941}
942
943/// Gets the current directory.
944///
945/// The returned string should be freed when no longer needed.
946/// The encoding of the returned string is system defined.
947/// On Windows, it is always UTF-8.
948///
949/// Since GLib 2.40, this function will return the value of the "PWD"
950/// environment variable if it is set and it happens to be the same as
951/// the current directory.  This can make a difference in the case that
952/// the current directory is the target of a symbolic link.
953///
954/// # Returns
955///
956/// the current directory
957#[doc(alias = "g_get_current_dir")]
958#[doc(alias = "get_current_dir")]
959pub fn current_dir() -> std::path::PathBuf {
960    unsafe { from_glib_full(ffi::g_get_current_dir()) }
961}
962
963/// Gets the list of environment variables for the current process.
964///
965/// The list is [`None`] terminated and each item in the list is of the
966/// form 'NAME=VALUE'.
967///
968/// This is equivalent to direct access to the 'environ' global variable,
969/// except portable.
970///
971/// The return value is freshly allocated and it should be freed with
972/// g_strfreev() when it is no longer needed.
973///
974/// # Returns
975///
976///
977///     the list of environment variables
978#[doc(alias = "g_get_environ")]
979#[doc(alias = "get_environ")]
980pub fn environ() -> Vec<std::ffi::OsString> {
981    unsafe { FromGlibPtrContainer::from_glib_full(ffi::g_get_environ()) }
982}
983
984/// Gets the current user's home directory.
985///
986/// As with most UNIX tools, this function will return the value of the
987/// `HOME` environment variable if it is set to an existing absolute path
988/// name, falling back to the `passwd` file in the case that it is unset.
989///
990/// If the path given in `HOME` is non-absolute, does not exist, or is
991/// not a directory, the result is undefined.
992///
993/// Before version 2.36 this function would ignore the `HOME` environment
994/// variable, taking the value from the `passwd` database instead. This was
995/// changed to increase the compatibility of GLib with other programs (and
996/// the XDG basedir specification) and to increase testability of programs
997/// based on GLib (by making it easier to run them from test frameworks).
998///
999/// If your program has a strong requirement for either the new or the
1000/// old behaviour (and if you don't wish to increase your GLib
1001/// dependency to ensure that the new behaviour is in effect) then you
1002/// should either directly check the `HOME` environment variable yourself
1003/// or unset it before calling any functions in GLib.
1004///
1005/// # Returns
1006///
1007/// the current user's home directory
1008#[doc(alias = "g_get_home_dir")]
1009#[doc(alias = "get_home_dir")]
1010pub fn home_dir() -> std::path::PathBuf {
1011    unsafe { from_glib_none(ffi::g_get_home_dir()) }
1012}
1013
1014/// Return a name for the machine.
1015///
1016/// The returned name is not necessarily a fully-qualified domain name,
1017/// or even present in DNS or some other name service at all. It need
1018/// not even be unique on your local network or site, but usually it
1019/// is. Callers should not rely on the return value having any specific
1020/// properties like uniqueness for security purposes. Even if the name
1021/// of the machine is changed while an application is running, the
1022/// return value from this function does not change. The returned
1023/// string is owned by GLib and should not be modified or freed. If no
1024/// name can be determined, a default fixed string "localhost" is
1025/// returned.
1026///
1027/// The encoding of the returned string is UTF-8.
1028///
1029/// # Returns
1030///
1031/// the host name of the machine.
1032#[doc(alias = "g_get_host_name")]
1033#[doc(alias = "get_host_name")]
1034pub fn host_name() -> crate::GString {
1035    unsafe { from_glib_none(ffi::g_get_host_name()) }
1036}
1037
1038/// Computes a list of applicable locale names, which can be used to
1039/// e.g. construct locale-dependent filenames or search paths. The returned
1040/// list is sorted from most desirable to least desirable and always contains
1041/// the default locale "C".
1042///
1043/// For example, if LANGUAGE=de:en_US, then the returned list is
1044/// "de", "en_US", "en", "C".
1045///
1046/// This function consults the environment variables `LANGUAGE`, `LC_ALL`,
1047/// `LC_MESSAGES` and `LANG` to find the list of locales specified by the
1048/// user.
1049///
1050/// # Returns
1051///
1052/// a [`None`]-terminated array of strings owned by GLib
1053///    that must not be modified or freed.
1054#[doc(alias = "g_get_language_names")]
1055#[doc(alias = "get_language_names")]
1056pub fn language_names() -> Vec<crate::GString> {
1057    unsafe { FromGlibPtrContainer::from_glib_none(ffi::g_get_language_names()) }
1058}
1059
1060/// Computes a list of applicable locale names with a locale category name,
1061/// which can be used to construct the fallback locale-dependent filenames
1062/// or search paths. The returned list is sorted from most desirable to
1063/// least desirable and always contains the default locale "C".
1064///
1065/// This function consults the environment variables `LANGUAGE`, `LC_ALL`,
1066/// @category_name, and `LANG` to find the list of locales specified by the
1067/// user.
1068///
1069/// g_get_language_names() returns g_get_language_names_with_category("LC_MESSAGES").
1070/// ## `category_name`
1071/// a locale category name
1072///
1073/// # Returns
1074///
1075/// a [`None`]-terminated array of strings owned by
1076///    the thread g_get_language_names_with_category was called from.
1077///    It must not be modified or freed. It must be copied if planned to be used in another thread.
1078#[cfg(feature = "v2_58")]
1079#[cfg_attr(docsrs, doc(cfg(feature = "v2_58")))]
1080#[doc(alias = "g_get_language_names_with_category")]
1081#[doc(alias = "get_language_names_with_category")]
1082pub fn language_names_with_category(category_name: &str) -> Vec<crate::GString> {
1083    unsafe {
1084        FromGlibPtrContainer::from_glib_none(ffi::g_get_language_names_with_category(
1085            category_name.to_glib_none().0,
1086        ))
1087    }
1088}
1089
1090/// Returns a list of derived variants of @locale, which can be used to
1091/// e.g. construct locale-dependent filenames or search paths. The returned
1092/// list is sorted from most desirable to least desirable.
1093/// This function handles territory, charset and extra locale modifiers. See
1094/// [`setlocale(3)`](man:setlocale) for information about locales and their format.
1095///
1096/// @locale itself is guaranteed to be returned in the output.
1097///
1098/// For example, if @locale is `fr_BE`, then the returned list
1099/// is `fr_BE`, `fr`. If @locale is `en_GB.UTF-8@euro`, then the returned list
1100/// is `en_GB.UTF-8@euro`, `en_GB.UTF-8`, `en_GB@euro`, `en_GB`, `en.UTF-8@euro`,
1101/// `en.UTF-8`, `en@euro`, `en`.
1102///
1103/// If you need the list of variants for the current locale,
1104/// use g_get_language_names().
1105/// ## `locale`
1106/// a locale identifier
1107///
1108/// # Returns
1109///
1110/// a newly
1111///   allocated array of newly allocated strings with the locale variants. Free with
1112///   g_strfreev().
1113#[doc(alias = "g_get_locale_variants")]
1114#[doc(alias = "get_locale_variants")]
1115pub fn locale_variants(locale: &str) -> Vec<crate::GString> {
1116    unsafe {
1117        FromGlibPtrContainer::from_glib_full(ffi::g_get_locale_variants(locale.to_glib_none().0))
1118    }
1119}
1120
1121/// Queries the system monotonic time.
1122///
1123/// The monotonic clock will always increase and doesn’t suffer
1124/// discontinuities when the user (or NTP) changes the system time.  It
1125/// may or may not continue to tick during times where the machine is
1126/// suspended.
1127///
1128/// We try to use the clock that corresponds as closely as possible to
1129/// the passage of time as measured by system calls such as
1130/// [`poll()`](man:poll(2)) but it
1131/// may not always be possible to do this.
1132///
1133/// # Returns
1134///
1135/// the monotonic time, in microseconds
1136#[doc(alias = "g_get_monotonic_time")]
1137#[doc(alias = "get_monotonic_time")]
1138pub fn monotonic_time() -> i64 {
1139    unsafe { ffi::g_get_monotonic_time() }
1140}
1141
1142/// Determine the approximate number of threads that the system will
1143/// schedule simultaneously for this process.  This is intended to be
1144/// used as a parameter to g_thread_pool_new() for CPU bound tasks and
1145/// similar cases.
1146///
1147/// # Returns
1148///
1149/// Number of schedulable threads, always greater than 0
1150#[doc(alias = "g_get_num_processors")]
1151#[doc(alias = "get_num_processors")]
1152pub fn num_processors() -> u32 {
1153    unsafe { ffi::g_get_num_processors() }
1154}
1155
1156/// Get information about the operating system.
1157///
1158/// On Linux this comes from the `/etc/os-release` file. On other systems, it may
1159/// come from a variety of sources. You can either use the standard key names
1160/// like `G_OS_INFO_KEY_NAME` or pass any UTF-8 string key name. For example,
1161/// `/etc/os-release` provides a number of other less commonly used values that may
1162/// be useful. No key is guaranteed to be provided, so the caller should always
1163/// check if the result is [`None`].
1164/// ## `key_name`
1165/// a key for the OS info being requested, for example `G_OS_INFO_KEY_NAME`.
1166///
1167/// # Returns
1168///
1169/// The associated value for the requested key or [`None`] if
1170///   this information is not provided.
1171#[cfg(feature = "v2_64")]
1172#[cfg_attr(docsrs, doc(cfg(feature = "v2_64")))]
1173#[doc(alias = "g_get_os_info")]
1174#[doc(alias = "get_os_info")]
1175pub fn os_info(key_name: &str) -> Option<crate::GString> {
1176    unsafe { from_glib_full(ffi::g_get_os_info(key_name.to_glib_none().0)) }
1177}
1178
1179/// Gets the real name of the user. This usually comes from the user's
1180/// entry in the `passwd` file. The encoding of the returned string is
1181/// system-defined. (On Windows, it is, however, always UTF-8.) If the
1182/// real user name cannot be determined, the string "Unknown" is
1183/// returned.
1184///
1185/// # Returns
1186///
1187/// the user's real name.
1188#[doc(alias = "g_get_real_name")]
1189#[doc(alias = "get_real_name")]
1190pub fn real_name() -> std::ffi::OsString {
1191    unsafe { from_glib_none(ffi::g_get_real_name()) }
1192}
1193
1194/// Queries the system wall-clock time.
1195///
1196/// This is equivalent to the UNIX [`gettimeofday()`](man:gettimeofday(2))
1197/// function, but portable.
1198///
1199/// You should only use this call if you are actually interested in the real
1200/// wall-clock time. [`monotonic_time()`][crate::monotonic_time()] is probably more useful for
1201/// measuring intervals.
1202///
1203/// # Returns
1204///
1205/// the number of microseconds since
1206///   [January 1, 1970 UTC](https://en.wikipedia.org/wiki/Unix_time)
1207#[doc(alias = "g_get_real_time")]
1208#[doc(alias = "get_real_time")]
1209pub fn real_time() -> i64 {
1210    unsafe { ffi::g_get_real_time() }
1211}
1212
1213/// Returns an ordered list of base directories in which to access
1214/// system-wide configuration information.
1215///
1216/// On UNIX platforms this is determined using the mechanisms described
1217/// in the
1218/// [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
1219/// In this case the list of directories retrieved will be `XDG_CONFIG_DIRS`.
1220///
1221/// On Windows it follows XDG Base Directory Specification if `XDG_CONFIG_DIRS` is defined.
1222/// If `XDG_CONFIG_DIRS` is undefined, the directory that contains application
1223/// data for all users is used instead. A typical path is
1224/// `C:\Documents and Settings\All Users\Application Data`.
1225/// This folder is used for application data
1226/// that is not user specific. For example, an application can store
1227/// a spell-check dictionary, a database of clip art, or a log file in the
1228/// FOLDERID_ProgramData folder. This information will not roam and is available
1229/// to anyone using the computer.
1230///
1231/// The return value is cached and modifying it at runtime is not supported, as
1232/// it’s not thread-safe to modify environment variables at runtime.
1233///
1234/// # Returns
1235///
1236///
1237///     a [`None`]-terminated array of strings owned by GLib that must not be
1238///     modified or freed.
1239#[doc(alias = "g_get_system_config_dirs")]
1240#[doc(alias = "get_system_config_dirs")]
1241pub fn system_config_dirs() -> Vec<std::path::PathBuf> {
1242    unsafe { FromGlibPtrContainer::from_glib_none(ffi::g_get_system_config_dirs()) }
1243}
1244
1245/// Returns an ordered list of base directories in which to access
1246/// system-wide application data.
1247///
1248/// On UNIX platforms this is determined using the mechanisms described
1249/// in the
1250/// [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec)
1251/// In this case the list of directories retrieved will be `XDG_DATA_DIRS`.
1252///
1253/// On Windows it follows XDG Base Directory Specification if `XDG_DATA_DIRS` is defined.
1254/// If `XDG_DATA_DIRS` is undefined,
1255/// the first elements in the list are the Application Data
1256/// and Documents folders for All Users. (These can be determined only
1257/// on Windows 2000 or later and are not present in the list on other
1258/// Windows versions.) See documentation for FOLDERID_ProgramData and
1259/// FOLDERID_PublicDocuments.
1260///
1261/// Then follows the "share" subfolder in the installation folder for
1262/// the package containing the DLL that calls this function, if it can
1263/// be determined.
1264///
1265/// Finally the list contains the "share" subfolder in the installation
1266/// folder for GLib, and in the installation folder for the package the
1267/// application's .exe file belongs to.
1268///
1269/// The installation folders above are determined by looking up the
1270/// folder where the module (DLL or EXE) in question is located. If the
1271/// folder's name is "bin", its parent is used, otherwise the folder
1272/// itself.
1273///
1274/// Note that on Windows the returned list can vary depending on where
1275/// this function is called.
1276///
1277/// The return value is cached and modifying it at runtime is not supported, as
1278/// it’s not thread-safe to modify environment variables at runtime.
1279///
1280/// # Returns
1281///
1282///
1283///     a [`None`]-terminated array of strings owned by GLib that must not be
1284///     modified or freed.
1285#[doc(alias = "g_get_system_data_dirs")]
1286#[doc(alias = "get_system_data_dirs")]
1287pub fn system_data_dirs() -> Vec<std::path::PathBuf> {
1288    unsafe { FromGlibPtrContainer::from_glib_none(ffi::g_get_system_data_dirs()) }
1289}
1290
1291/// Gets the directory to use for temporary files.
1292///
1293/// On UNIX, this is taken from the `TMPDIR` environment variable.
1294/// If the variable is not set, `P_tmpdir` is
1295/// used, as defined by the system C library. Failing that, a
1296/// hard-coded default of "/tmp" is returned.
1297///
1298/// On Windows, the `TEMP` environment variable is used, with the
1299/// root directory of the Windows installation (eg: "C:\") used
1300/// as a default.
1301///
1302/// The encoding of the returned string is system-defined. On Windows,
1303/// it is always UTF-8. The return value is never [`None`] or the empty
1304/// string.
1305///
1306/// # Returns
1307///
1308/// the directory to use for temporary files.
1309#[doc(alias = "g_get_tmp_dir")]
1310#[doc(alias = "get_tmp_dir")]
1311pub fn tmp_dir() -> std::path::PathBuf {
1312    unsafe { from_glib_none(ffi::g_get_tmp_dir()) }
1313}
1314
1315/// Returns a base directory in which to store non-essential, cached
1316/// data specific to particular user.
1317///
1318/// On UNIX platforms this is determined using the mechanisms described
1319/// in the
1320/// [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
1321/// In this case the directory retrieved will be `XDG_CACHE_HOME`.
1322///
1323/// On Windows it follows XDG Base Directory Specification if `XDG_CACHE_HOME` is defined.
1324/// If `XDG_CACHE_HOME` is undefined, the directory that serves as a common
1325/// repository for temporary Internet files is used instead. A typical path is
1326/// `C:\Documents and Settings\username\Local Settings\Temporary Internet Files`.
1327/// See the [documentation for `FOLDERID_InternetCache`](https://docs.microsoft.com/en-us/windows/win32/shell/knownfolderid).
1328///
1329/// The return value is cached and modifying it at runtime is not supported, as
1330/// it’s not thread-safe to modify environment variables at runtime.
1331///
1332/// # Returns
1333///
1334/// a string owned by GLib that
1335///   must not be modified or freed.
1336#[doc(alias = "g_get_user_cache_dir")]
1337#[doc(alias = "get_user_cache_dir")]
1338pub fn user_cache_dir() -> std::path::PathBuf {
1339    unsafe { from_glib_none(ffi::g_get_user_cache_dir()) }
1340}
1341
1342/// Returns a base directory in which to store user-specific application
1343/// configuration information such as user preferences and settings.
1344///
1345/// On UNIX platforms this is determined using the mechanisms described
1346/// in the
1347/// [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
1348/// In this case the directory retrieved will be `XDG_CONFIG_HOME`.
1349///
1350/// On Windows it follows XDG Base Directory Specification if `XDG_CONFIG_HOME` is defined.
1351/// If `XDG_CONFIG_HOME` is undefined, the folder to use for local (as opposed
1352/// to roaming) application data is used instead. See the
1353/// [documentation for `FOLDERID_LocalAppData`](https://docs.microsoft.com/en-us/windows/win32/shell/knownfolderid).
1354/// Note that in this case on Windows it will be  the same
1355/// as what g_get_user_data_dir() returns.
1356///
1357/// The return value is cached and modifying it at runtime is not supported, as
1358/// it’s not thread-safe to modify environment variables at runtime.
1359///
1360/// # Returns
1361///
1362/// a string owned by GLib that
1363///   must not be modified or freed.
1364#[doc(alias = "g_get_user_config_dir")]
1365#[doc(alias = "get_user_config_dir")]
1366pub fn user_config_dir() -> std::path::PathBuf {
1367    unsafe { from_glib_none(ffi::g_get_user_config_dir()) }
1368}
1369
1370/// Returns a base directory in which to access application data such
1371/// as icons that is customized for a particular user.
1372///
1373/// On UNIX platforms this is determined using the mechanisms described
1374/// in the
1375/// [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
1376/// In this case the directory retrieved will be `XDG_DATA_HOME`.
1377///
1378/// On Windows it follows XDG Base Directory Specification if `XDG_DATA_HOME`
1379/// is defined. If `XDG_DATA_HOME` is undefined, the folder to use for local (as
1380/// opposed to roaming) application data is used instead. See the
1381/// [documentation for `FOLDERID_LocalAppData`](https://docs.microsoft.com/en-us/windows/win32/shell/knownfolderid).
1382/// Note that in this case on Windows it will be the same
1383/// as what g_get_user_config_dir() returns.
1384///
1385/// The return value is cached and modifying it at runtime is not supported, as
1386/// it’s not thread-safe to modify environment variables at runtime.
1387///
1388/// # Returns
1389///
1390/// a string owned by GLib that must
1391///   not be modified or freed.
1392#[doc(alias = "g_get_user_data_dir")]
1393#[doc(alias = "get_user_data_dir")]
1394pub fn user_data_dir() -> std::path::PathBuf {
1395    unsafe { from_glib_none(ffi::g_get_user_data_dir()) }
1396}
1397
1398/// Gets the user name of the current user. The encoding of the returned
1399/// string is system-defined. On UNIX, it might be the preferred file name
1400/// encoding, or something else, and there is no guarantee that it is even
1401/// consistent on a machine. On Windows, it is always UTF-8.
1402///
1403/// # Returns
1404///
1405/// the user name of the current user.
1406#[doc(alias = "g_get_user_name")]
1407#[doc(alias = "get_user_name")]
1408pub fn user_name() -> std::ffi::OsString {
1409    unsafe { from_glib_none(ffi::g_get_user_name()) }
1410}
1411
1412/// Returns a directory that is unique to the current user on the local
1413/// system.
1414///
1415/// This is determined using the mechanisms described
1416/// in the
1417/// [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
1418/// This is the directory
1419/// specified in the `XDG_RUNTIME_DIR` environment variable.
1420/// In the case that this variable is not set, we return the value of
1421/// g_get_user_cache_dir(), after verifying that it exists.
1422///
1423/// The return value is cached and modifying it at runtime is not supported, as
1424/// it’s not thread-safe to modify environment variables at runtime.
1425///
1426/// # Returns
1427///
1428/// a string owned by GLib that must not be
1429///     modified or freed.
1430#[doc(alias = "g_get_user_runtime_dir")]
1431#[doc(alias = "get_user_runtime_dir")]
1432pub fn user_runtime_dir() -> std::path::PathBuf {
1433    unsafe { from_glib_none(ffi::g_get_user_runtime_dir()) }
1434}
1435
1436/// Returns the full path of a special directory using its logical id.
1437///
1438/// On UNIX this is done using the XDG special user directories.
1439/// For compatibility with existing practise, [`UserDirectory::DirectoryDesktop`][crate::UserDirectory::DirectoryDesktop]
1440/// falls back to `$HOME/Desktop` when XDG special user directories have
1441/// not been set up.
1442///
1443/// Depending on the platform, the user might be able to change the path
1444/// of the special directory without requiring the session to restart; GLib
1445/// will not reflect any change once the special directories are loaded.
1446/// ## `directory`
1447/// the logical id of special directory
1448///
1449/// # Returns
1450///
1451/// the path to the specified special
1452///   directory, or [`None`] if the logical id was not found. The returned string is
1453///   owned by GLib and should not be modified or freed.
1454#[doc(alias = "g_get_user_special_dir")]
1455#[doc(alias = "get_user_special_dir")]
1456pub fn user_special_dir(directory: UserDirectory) -> Option<std::path::PathBuf> {
1457    unsafe { from_glib_none(ffi::g_get_user_special_dir(directory.into_glib())) }
1458}
1459
1460/// Returns a base directory in which to store state files specific to
1461/// particular user.
1462///
1463/// On UNIX platforms this is determined using the mechanisms described
1464/// in the
1465/// [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
1466/// In this case the directory retrieved will be `XDG_STATE_HOME`.
1467///
1468/// On Windows it follows XDG Base Directory Specification if `XDG_STATE_HOME` is defined.
1469/// If `XDG_STATE_HOME` is undefined, the folder to use for local (as opposed
1470/// to roaming) application data is used instead. See the
1471/// [documentation for `FOLDERID_LocalAppData`](https://docs.microsoft.com/en-us/windows/win32/shell/knownfolderid).
1472/// Note that in this case on Windows it will be the same
1473/// as what g_get_user_data_dir() returns.
1474///
1475/// The return value is cached and modifying it at runtime is not supported, as
1476/// it’s not thread-safe to modify environment variables at runtime.
1477///
1478/// # Returns
1479///
1480/// a string owned by GLib that
1481///   must not be modified or freed.
1482#[cfg(feature = "v2_72")]
1483#[cfg_attr(docsrs, doc(cfg(feature = "v2_72")))]
1484#[doc(alias = "g_get_user_state_dir")]
1485#[doc(alias = "get_user_state_dir")]
1486pub fn user_state_dir() -> std::path::PathBuf {
1487    unsafe { from_glib_none(ffi::g_get_user_state_dir()) }
1488}
1489
1490/// Returns the value of an environment variable.
1491///
1492/// On UNIX, the name and value are byte strings which might or might not
1493/// be in some consistent character set and encoding. On Windows, they are
1494/// in UTF-8.
1495/// On Windows, in case the environment variable's value contains
1496/// references to other environment variables, they are expanded.
1497/// ## `variable`
1498/// the environment variable to get
1499///
1500/// # Returns
1501///
1502/// the value of the environment variable, or [`None`] if
1503///     the environment variable is not found. The returned string
1504///     may be overwritten by the next call to g_getenv(), g_setenv()
1505///     or g_unsetenv().
1506#[doc(alias = "g_getenv")]
1507pub fn getenv(variable: impl AsRef<std::ffi::OsStr>) -> Option<std::ffi::OsString> {
1508    unsafe { from_glib_none(ffi::g_getenv(variable.as_ref().to_glib_none().0)) }
1509}
1510
1511/// Tests if @hostname contains segments with an ASCII-compatible
1512/// encoding of an Internationalized Domain Name. If this returns
1513/// [`true`], you should decode the hostname with g_hostname_to_unicode()
1514/// before displaying it to the user.
1515///
1516/// Note that a hostname might contain a mix of encoded and unencoded
1517/// segments, and so it is possible for g_hostname_is_non_ascii() and
1518/// g_hostname_is_ascii_encoded() to both return [`true`] for a name.
1519/// ## `hostname`
1520/// a hostname
1521///
1522/// # Returns
1523///
1524/// [`true`] if @hostname contains any ASCII-encoded
1525/// segments.
1526#[doc(alias = "g_hostname_is_ascii_encoded")]
1527pub fn hostname_is_ascii_encoded(hostname: &str) -> bool {
1528    unsafe { from_glib(ffi::g_hostname_is_ascii_encoded(hostname.to_glib_none().0)) }
1529}
1530
1531/// Tests if @hostname is the string form of an IPv4 or IPv6 address.
1532/// (Eg, "192.168.0.1".)
1533///
1534/// Since 2.66, IPv6 addresses with a zone-id are accepted (RFC6874).
1535/// ## `hostname`
1536/// a hostname (or IP address in string form)
1537///
1538/// # Returns
1539///
1540/// [`true`] if @hostname is an IP address
1541#[doc(alias = "g_hostname_is_ip_address")]
1542pub fn hostname_is_ip_address(hostname: &str) -> bool {
1543    unsafe { from_glib(ffi::g_hostname_is_ip_address(hostname.to_glib_none().0)) }
1544}
1545
1546/// Tests if @hostname contains Unicode characters. If this returns
1547/// [`true`], you need to encode the hostname with g_hostname_to_ascii()
1548/// before using it in non-IDN-aware contexts.
1549///
1550/// Note that a hostname might contain a mix of encoded and unencoded
1551/// segments, and so it is possible for g_hostname_is_non_ascii() and
1552/// g_hostname_is_ascii_encoded() to both return [`true`] for a name.
1553/// ## `hostname`
1554/// a hostname
1555///
1556/// # Returns
1557///
1558/// [`true`] if @hostname contains any non-ASCII characters
1559#[doc(alias = "g_hostname_is_non_ascii")]
1560pub fn hostname_is_non_ascii(hostname: &str) -> bool {
1561    unsafe { from_glib(ffi::g_hostname_is_non_ascii(hostname.to_glib_none().0)) }
1562}
1563
1564/// Converts @hostname to its canonical ASCII form; an ASCII-only
1565/// string containing no uppercase letters and not ending with a
1566/// trailing dot.
1567/// ## `hostname`
1568/// a valid UTF-8 or ASCII hostname
1569///
1570/// # Returns
1571///
1572/// an ASCII hostname, which must be freed,
1573///    or [`None`] if @hostname is in some way invalid.
1574#[doc(alias = "g_hostname_to_ascii")]
1575pub fn hostname_to_ascii(hostname: &str) -> Option<crate::GString> {
1576    unsafe { from_glib_full(ffi::g_hostname_to_ascii(hostname.to_glib_none().0)) }
1577}
1578
1579/// Converts @hostname to its canonical presentation form; a UTF-8
1580/// string in Unicode normalization form C, containing no uppercase
1581/// letters, no forbidden characters, and no ASCII-encoded segments,
1582/// and not ending with a trailing dot.
1583///
1584/// Of course if @hostname is not an internationalized hostname, then
1585/// the canonical presentation form will be entirely ASCII.
1586/// ## `hostname`
1587/// a valid UTF-8 or ASCII hostname
1588///
1589/// # Returns
1590///
1591/// a UTF-8 hostname, which must be freed,
1592///    or [`None`] if @hostname is in some way invalid.
1593#[doc(alias = "g_hostname_to_unicode")]
1594pub fn hostname_to_unicode(hostname: &str) -> Option<crate::GString> {
1595    unsafe { from_glib_full(ffi::g_hostname_to_unicode(hostname.to_glib_none().0)) }
1596}
1597
1598/// Gets the names of all variables set in the environment.
1599///
1600/// Programs that want to be portable to Windows should typically use
1601/// this function and g_getenv() instead of using the environ array
1602/// from the C library directly. On Windows, the strings in the environ
1603/// array are in system codepage encoding, while in most of the typical
1604/// use cases for environment variables in GLib-using programs you want
1605/// the UTF-8 encoding that this function and g_getenv() provide.
1606///
1607/// # Returns
1608///
1609///
1610///     a [`None`]-terminated list of strings which must be freed with
1611///     g_strfreev().
1612#[doc(alias = "g_listenv")]
1613pub fn listenv() -> Vec<std::ffi::OsString> {
1614    unsafe { FromGlibPtrContainer::from_glib_full(ffi::g_listenv()) }
1615}
1616
1617/// Returns the currently firing source for this thread.
1618///
1619/// # Returns
1620///
1621/// the currently firing source, or `NULL`
1622///   if none is firing
1623#[doc(alias = "g_main_current_source")]
1624pub fn main_current_source() -> Option<Source> {
1625    unsafe { from_glib_none(ffi::g_main_current_source()) }
1626}
1627
1628/// Returns the depth of the stack of calls to
1629/// [`MainContext::dispatch()`][crate::MainContext::dispatch()] on any #GMainContext in the current thread.
1630///
1631/// That is, when called from the top level, it gives `0`. When
1632/// called from within a callback from [`MainContext::iteration()`][crate::MainContext::iteration()]
1633/// (or [`MainLoop::run()`][crate::MainLoop::run()], etc.) it returns `1`. When called from within
1634/// a callback to a recursive call to [`MainContext::iteration()`][crate::MainContext::iteration()],
1635/// it returns `2`. And so forth.
1636///
1637/// This function is useful in a situation like the following:
1638/// Imagine an extremely simple ‘garbage collected’ system.
1639///
1640/// **⚠️ The following code is in c ⚠️**
1641///
1642/// ```c
1643/// static GList *free_list;
1644///
1645/// gpointer
1646/// allocate_memory (gsize size)
1647/// {
1648///   gpointer result = g_malloc (size);
1649///   free_list = g_list_prepend (free_list, result);
1650///   return result;
1651/// }
1652///
1653/// void
1654/// free_allocated_memory (void)
1655/// {
1656///   GList *l;
1657///   for (l = free_list; l; l = l->next);
1658///     g_free (l->data);
1659///   g_list_free (free_list);
1660///   free_list = NULL;
1661///  }
1662///
1663/// [...]
1664///
1665/// while (TRUE);
1666///  {
1667///    g_main_context_iteration (NULL, TRUE);
1668///    free_allocated_memory();
1669///   }
1670/// ```
1671///
1672/// This works from an application, however, if you want to do the same
1673/// thing from a library, it gets more difficult, since you no longer
1674/// control the main loop. You might think you can simply use an idle
1675/// function to make the call to `free_allocated_memory()`, but that
1676/// doesn’t work, since the idle function could be called from a
1677/// recursive callback. This can be fixed by using [`main_depth()`][crate::main_depth()]
1678///
1679/// **⚠️ The following code is in c ⚠️**
1680///
1681/// ```c
1682/// gpointer
1683/// allocate_memory (gsize size)
1684/// {
1685///   FreeListBlock *block = g_new (FreeListBlock, 1);
1686///   block->mem = g_malloc (size);
1687///   block->depth = g_main_depth ();
1688///   free_list = g_list_prepend (free_list, block);
1689///   return block->mem;
1690/// }
1691///
1692/// void
1693/// free_allocated_memory (void)
1694/// {
1695///   GList *l;
1696///
1697///   int depth = g_main_depth ();
1698///   for (l = free_list; l; );
1699///     {
1700///       GList *next = l->next;
1701///       FreeListBlock *block = l->data;
1702///       if (block->depth > depth)
1703///         {
1704///           g_free (block->mem);
1705///           g_free (block);
1706///           free_list = g_list_delete_link (free_list, l);
1707///         }
1708///
1709///       l = next;
1710///     }
1711///   }
1712/// ```
1713///
1714/// There is a temptation to use [`main_depth()`][crate::main_depth()] to solve
1715/// problems with reentrancy. For instance, while waiting for data
1716/// to be received from the network in response to a menu item,
1717/// the menu item might be selected again. It might seem that
1718/// one could make the menu item’s callback return immediately
1719/// and do nothing if [`main_depth()`][crate::main_depth()] returns a value greater than 1.
1720/// However, this should be avoided since the user then sees selecting
1721/// the menu item do nothing. Furthermore, you’ll find yourself adding
1722/// these checks all over your code, since there are doubtless many,
1723/// many things that the user could do. Instead, you can use the
1724/// following techniques:
1725///
1726/// 1. Use `gtk_widget_set_sensitive()` or modal dialogs to prevent
1727///    the user from interacting with elements while the main
1728///    loop is recursing.
1729///
1730/// 2. Avoid main loop recursion in situations where you can’t handle
1731///    arbitrary  callbacks. Instead, structure your code so that you
1732///    simply return to the main loop and then get called again when
1733///    there is more work to do.
1734///
1735/// # Returns
1736///
1737/// the main loop recursion level in the current thread
1738#[doc(alias = "g_main_depth")]
1739pub fn main_depth() -> i32 {
1740    unsafe { ffi::g_main_depth() }
1741}
1742
1743/// Escapes text so that the markup parser will parse it verbatim.
1744/// Less than, greater than, ampersand, etc. are replaced with the
1745/// corresponding entities. This function would typically be used
1746/// when writing out a file to be parsed with the markup parser.
1747///
1748/// Note that this function doesn't protect whitespace and line endings
1749/// from being processed according to the XML rules for normalization
1750/// of line endings and attribute values.
1751///
1752/// Note also that this function will produce character references in
1753/// the range of &#x1; ... &#x1f; for all control sequences
1754/// except for tabstop, newline and carriage return.  The character
1755/// references in this range are not valid XML 1.0, but they are
1756/// valid XML 1.1 and will be accepted by the GMarkup parser.
1757/// ## `text`
1758/// some valid UTF-8 text
1759/// ## `length`
1760/// length of @text in bytes, or -1 if the text is nul-terminated
1761///
1762/// # Returns
1763///
1764/// a newly allocated string with the escaped text
1765#[doc(alias = "g_markup_escape_text")]
1766pub fn markup_escape_text(text: &str) -> crate::GString {
1767    let length = text.len() as _;
1768    unsafe { from_glib_full(ffi::g_markup_escape_text(text.to_glib_none().0, length)) }
1769}
1770
1771/// Create a directory if it doesn't already exist. Create intermediate
1772/// parent directories as needed, too.
1773/// ## `pathname`
1774/// a pathname in the GLib file name encoding
1775/// ## `mode`
1776/// permissions to use for newly created directories
1777///
1778/// # Returns
1779///
1780/// 0 if the directory already exists, or was successfully
1781/// created. Returns -1 if an error occurred, with errno set.
1782#[doc(alias = "g_mkdir_with_parents")]
1783pub fn mkdir_with_parents(pathname: impl AsRef<std::path::Path>, mode: i32) -> i32 {
1784    unsafe { ffi::g_mkdir_with_parents(pathname.as_ref().to_glib_none().0, mode) }
1785}
1786
1787/// Prompts the user with
1788/// `[E]xit, [H]alt, show [S]tack trace or [P]roceed`.
1789/// This function is intended to be used for debugging use only.
1790/// The following example shows how it can be used together with
1791/// the g_log() functions.
1792///
1793///
1794///
1795/// **⚠️ The following code is in C ⚠️**
1796///
1797/// ```C
1798/// #include <glib.h>
1799///
1800/// static void
1801/// log_handler (const gchar   *log_domain,
1802///              GLogLevelFlags log_level,
1803///              const gchar   *message,
1804///              gpointer       user_data)
1805/// {
1806///   g_log_default_handler (log_domain, log_level, message, user_data);
1807///
1808///   g_on_error_query (MY_PROGRAM_NAME);
1809/// }
1810///
1811/// int
1812/// main (int argc, char *argv[])
1813/// {
1814///   g_log_set_handler (MY_LOG_DOMAIN,
1815///                      G_LOG_LEVEL_WARNING |
1816///                      G_LOG_LEVEL_ERROR |
1817///                      G_LOG_LEVEL_CRITICAL,
1818///                      log_handler,
1819///                      NULL);
1820///   ...
1821/// ```
1822///
1823/// If "[E]xit" is selected, the application terminates with a call
1824/// to _exit(0).
1825///
1826/// If "[S]tack" trace is selected, g_on_error_stack_trace() is called.
1827/// This invokes gdb, which attaches to the current process and shows
1828/// a stack trace. The prompt is then shown again.
1829///
1830/// If "[P]roceed" is selected, the function returns.
1831///
1832/// This function may cause different actions on non-UNIX platforms.
1833///
1834/// On Windows consider using the `G_DEBUGGER` environment
1835/// variable (see [Running GLib Applications](running.html)) and
1836/// calling g_on_error_stack_trace() instead.
1837/// ## `prg_name`
1838/// the program name, needed by gdb for the "[S]tack trace"
1839///     option. If @prg_name is [`None`], g_get_prgname() is called to get
1840///     the program name (which will work correctly if gdk_init() or
1841///     gtk_init() has been called)
1842#[doc(alias = "g_on_error_query")]
1843pub fn on_error_query(prg_name: &str) {
1844    unsafe {
1845        ffi::g_on_error_query(prg_name.to_glib_none().0);
1846    }
1847}
1848
1849/// Invokes gdb, which attaches to the current process and shows a
1850/// stack trace. Called by g_on_error_query() when the "[S]tack trace"
1851/// option is selected. You can get the current process's program name
1852/// with g_get_prgname(), assuming that you have called gtk_init() or
1853/// gdk_init().
1854///
1855/// This function may cause different actions on non-UNIX platforms.
1856///
1857/// When running on Windows, this function is *not* called by
1858/// g_on_error_query(). If called directly, it will raise an
1859/// exception, which will crash the program. If the `G_DEBUGGER` environment
1860/// variable is set, a debugger will be invoked to attach and
1861/// handle that exception (see [Running GLib Applications](running.html)).
1862/// ## `prg_name`
1863/// the program name, needed by gdb for the
1864///   "[S]tack trace" option, or `NULL` to use a default string
1865#[doc(alias = "g_on_error_stack_trace")]
1866pub fn on_error_stack_trace(prg_name: Option<&str>) {
1867    unsafe {
1868        ffi::g_on_error_stack_trace(prg_name.to_glib_none().0);
1869    }
1870}
1871
1872/// Gets the last component of the filename.
1873///
1874/// If @file_name ends with a directory separator it gets the component
1875/// before the last slash. If @file_name consists only of directory
1876/// separators (and on Windows, possibly a drive letter), a single
1877/// separator is returned. If @file_name is empty, it gets ".".
1878/// ## `file_name`
1879/// the name of the file
1880///
1881/// # Returns
1882///
1883/// a newly allocated string
1884///   containing the last component of the filename
1885#[doc(alias = "g_path_get_basename")]
1886#[allow(dead_code)]
1887pub(crate) fn path_get_basename(file_name: impl AsRef<std::path::Path>) -> std::path::PathBuf {
1888    unsafe {
1889        from_glib_full(ffi::g_path_get_basename(
1890            file_name.as_ref().to_glib_none().0,
1891        ))
1892    }
1893}
1894
1895/// Gets the directory components of a file name. For example, the directory
1896/// component of `/usr/bin/test` is `/usr/bin`. The directory component of `/`
1897/// is `/`.
1898///
1899/// If the file name has no directory components "." is returned.
1900/// The returned string should be freed when no longer needed.
1901/// ## `file_name`
1902/// the name of the file
1903///
1904/// # Returns
1905///
1906/// the directory components of the file
1907#[doc(alias = "g_path_get_dirname")]
1908#[allow(dead_code)]
1909pub(crate) fn path_get_dirname(file_name: impl AsRef<std::path::Path>) -> std::path::PathBuf {
1910    unsafe { from_glib_full(ffi::g_path_get_dirname(file_name.as_ref().to_glib_none().0)) }
1911}
1912
1913//#[doc(alias = "g_poll")]
1914//pub fn poll(fds: /*Ignored*/&mut PollFD, nfds: u32, timeout: i32) -> i32 {
1915//    unsafe { TODO: call ffi:g_poll() }
1916//}
1917
1918/// Returns a random #gdouble equally distributed over the range [0..1).
1919///
1920/// # Returns
1921///
1922/// a random number
1923#[doc(alias = "g_random_double")]
1924pub fn random_double() -> f64 {
1925    unsafe { ffi::g_random_double() }
1926}
1927
1928/// Returns a random #gdouble equally distributed over the range
1929/// [@begin..@end).
1930/// ## `begin`
1931/// lower closed bound of the interval
1932/// ## `end`
1933/// upper open bound of the interval
1934///
1935/// # Returns
1936///
1937/// a random number
1938#[doc(alias = "g_random_double_range")]
1939pub fn random_double_range(begin: f64, end: f64) -> f64 {
1940    unsafe { ffi::g_random_double_range(begin, end) }
1941}
1942
1943/// Return a random #guint32 equally distributed over the range
1944/// [0..2^32-1].
1945///
1946/// # Returns
1947///
1948/// a random number
1949#[doc(alias = "g_random_int")]
1950pub fn random_int() -> u32 {
1951    unsafe { ffi::g_random_int() }
1952}
1953
1954/// Returns a random #gint32 equally distributed over the range
1955/// [@begin..@end-1].
1956/// ## `begin`
1957/// lower closed bound of the interval
1958/// ## `end`
1959/// upper open bound of the interval
1960///
1961/// # Returns
1962///
1963/// a random number
1964#[doc(alias = "g_random_int_range")]
1965pub fn random_int_range(begin: i32, end: i32) -> i32 {
1966    unsafe { ffi::g_random_int_range(begin, end) }
1967}
1968
1969/// Sets the seed for the global random number generator, which is used
1970/// by the g_random_* functions, to @seed.
1971/// ## `seed`
1972/// a value to reinitialize the global random number generator
1973#[doc(alias = "g_random_set_seed")]
1974pub fn random_set_seed(seed: u32) {
1975    unsafe {
1976        ffi::g_random_set_seed(seed);
1977    }
1978}
1979
1980/// Resets the cache used for g_get_user_special_dir(), so
1981/// that the latest on-disk version is used. Call this only
1982/// if you just changed the data on disk yourself.
1983///
1984/// Due to thread safety issues this may cause leaking of strings
1985/// that were previously returned from g_get_user_special_dir()
1986/// that can't be freed. We ensure to only leak the data for
1987/// the directories that actually changed value though.
1988#[doc(alias = "g_reload_user_special_dirs_cache")]
1989pub fn reload_user_special_dirs_cache() {
1990    unsafe {
1991        ffi::g_reload_user_special_dirs_cache();
1992    }
1993}
1994
1995/// Sets a human-readable name for the application. This name should be
1996/// localized if possible, and is intended for display to the user.
1997/// Contrast with g_set_prgname(), which sets a non-localized name.
1998/// g_set_prgname() will be called automatically by gtk_init(),
1999/// but g_set_application_name() will not.
2000///
2001/// Note that for thread safety reasons, this function can only
2002/// be called once.
2003///
2004/// The application name will be used in contexts such as error messages,
2005/// or when displaying an application's name in the task list.
2006/// ## `application_name`
2007/// localized name of the application
2008#[doc(alias = "g_set_application_name")]
2009pub fn set_application_name(application_name: &str) {
2010    unsafe {
2011        ffi::g_set_application_name(application_name.to_glib_none().0);
2012    }
2013}
2014
2015/// Sets an environment variable. On UNIX, both the variable's name and
2016/// value can be arbitrary byte strings, except that the variable's name
2017/// cannot contain '='. On Windows, they should be in UTF-8.
2018///
2019/// Note that on some systems, when variables are overwritten, the memory
2020/// used for the previous variables and its value isn't reclaimed.
2021///
2022/// You should be mindful of the fact that environment variable handling
2023/// in UNIX is not thread-safe, and your program may crash if one thread
2024/// calls g_setenv() while another thread is calling getenv(). (And note
2025/// that many functions, such as gettext(), call getenv() internally.)
2026/// This function is only safe to use at the very start of your program,
2027/// before creating any other threads (or creating objects that create
2028/// worker threads of their own).
2029///
2030/// If you need to set up the environment for a child process, you can
2031/// use g_get_environ() to get an environment array, modify that with
2032/// g_environ_setenv() and g_environ_unsetenv(), and then pass that
2033/// array directly to execvpe(), g_spawn_async(), or the like.
2034/// ## `variable`
2035/// the environment variable to set, must not
2036///     contain '='.
2037/// ## `value`
2038/// the value for to set the variable to.
2039/// ## `overwrite`
2040/// whether to change the variable if it already exists.
2041///
2042/// # Returns
2043///
2044/// [`false`] if the environment variable couldn't be set.
2045#[doc(alias = "g_setenv")]
2046pub fn setenv(
2047    variable: impl AsRef<std::ffi::OsStr>,
2048    value: impl AsRef<std::ffi::OsStr>,
2049    overwrite: bool,
2050) -> Result<(), crate::error::BoolError> {
2051    unsafe {
2052        crate::result_from_gboolean!(
2053            ffi::g_setenv(
2054                variable.as_ref().to_glib_none().0,
2055                value.as_ref().to_glib_none().0,
2056                overwrite.into_glib()
2057            ),
2058            "Failed to set environment variable"
2059        )
2060    }
2061}
2062
2063/// Parses a command line into an argument vector, in much the same way
2064/// the shell would, but without many of the expansions the shell would
2065/// perform (variable expansion, globs, operators, filename expansion,
2066/// etc. are not supported).
2067///
2068/// The results are defined to be the same as those you would get from
2069/// a UNIX98 `/bin/sh`, as long as the input contains none of the
2070/// unsupported shell expansions. If the input does contain such expansions,
2071/// they are passed through literally.
2072///
2073/// Possible errors are those from the `G_SHELL_ERROR` domain.
2074///
2075/// In particular, if @command_line is an empty string (or a string containing
2076/// only whitespace), `G_SHELL_ERROR_EMPTY_STRING` will be returned. It’s
2077/// guaranteed that @argvp will be a non-empty array if this function returns
2078/// successfully.
2079///
2080/// Free the returned vector with g_strfreev().
2081/// ## `command_line`
2082/// command line to parse
2083///
2084/// # Returns
2085///
2086/// [`true`] on success, [`false`] if error set
2087///
2088/// ## `argvp`
2089///
2090///   return location for array of args
2091#[doc(alias = "g_shell_parse_argv")]
2092pub fn shell_parse_argv(
2093    command_line: impl AsRef<std::ffi::OsStr>,
2094) -> Result<Vec<std::ffi::OsString>, crate::Error> {
2095    unsafe {
2096        let mut argcp = std::mem::MaybeUninit::uninit();
2097        let mut argvp = std::ptr::null_mut();
2098        let mut error = std::ptr::null_mut();
2099        let is_ok = ffi::g_shell_parse_argv(
2100            command_line.as_ref().to_glib_none().0,
2101            argcp.as_mut_ptr(),
2102            &mut argvp,
2103            &mut error,
2104        );
2105        debug_assert_eq!(is_ok == crate::ffi::GFALSE, !error.is_null());
2106        if error.is_null() {
2107            Ok(FromGlibContainer::from_glib_full_num(
2108                argvp,
2109                argcp.assume_init() as _,
2110            ))
2111        } else {
2112            Err(from_glib_full(error))
2113        }
2114    }
2115}
2116
2117/// Quotes a string so that the shell (/bin/sh) will interpret the
2118/// quoted string to mean @unquoted_string.
2119///
2120/// If you pass a filename to the shell, for example, you should first
2121/// quote it with this function.
2122///
2123/// The return value must be freed with g_free().
2124///
2125/// The quoting style used is undefined (single or double quotes may be
2126/// used).
2127/// ## `unquoted_string`
2128/// a literal string
2129///
2130/// # Returns
2131///
2132/// quoted string
2133#[doc(alias = "g_shell_quote")]
2134pub fn shell_quote(unquoted_string: impl AsRef<std::ffi::OsStr>) -> std::ffi::OsString {
2135    unsafe {
2136        from_glib_full(ffi::g_shell_quote(
2137            unquoted_string.as_ref().to_glib_none().0,
2138        ))
2139    }
2140}
2141
2142/// Unquotes a string as the shell (/bin/sh) would.
2143///
2144/// This function only handles quotes; if a string contains file globs,
2145/// arithmetic operators, variables, backticks, redirections, or other
2146/// special-to-the-shell features, the result will be different from the
2147/// result a real shell would produce (the variables, backticks, etc.
2148/// will be passed through literally instead of being expanded).
2149///
2150/// This function is guaranteed to succeed if applied to the result of
2151/// g_shell_quote(). If it fails, it returns [`None`] and sets the
2152/// error.
2153///
2154/// The @quoted_string need not actually contain quoted or escaped text;
2155/// g_shell_unquote() simply goes through the string and unquotes/unescapes
2156/// anything that the shell would. Both single and double quotes are
2157/// handled, as are escapes including escaped newlines.
2158///
2159/// The return value must be freed with g_free().
2160///
2161/// Possible errors are in the `G_SHELL_ERROR` domain.
2162///
2163/// Shell quoting rules are a bit strange. Single quotes preserve the
2164/// literal string exactly. escape sequences are not allowed; not even
2165/// `\'` - if you want a `'` in the quoted text, you have to do something
2166/// like `'foo'\''bar'`. Double quotes allow `$`, **⚠️ The following code is in , `"`, `\`, and ⚠️**
2167///
2168/// ```, `"`, `\`, and
2169/// newline to be escaped with backslash. Otherwise double quotes
2170/// preserve things literally.
2171/// ## `quoted_string`
2172/// shell-quoted string
2173///
2174/// # Returns
2175///
2176/// an unquoted string
2177#[doc(alias = "g_shell_unquote")]
2178pub fn shell_unquote(
2179    quoted_string: impl AsRef<std::ffi::OsStr>,
2180) -> Result<std::ffi::OsString, crate::Error> {
2181    unsafe {
2182        let mut error = std::ptr::null_mut();
2183        let ret = ffi::g_shell_unquote(quoted_string.as_ref().to_glib_none().0, &mut error);
2184        if error.is_null() {
2185            Ok(from_glib_full(ret))
2186        } else {
2187            Err(from_glib_full(error))
2188        }
2189    }
2190}
2191
2192//#[cfg(feature = "v2_82")]
2193//#[cfg_attr(docsrs, doc(cfg(feature = "v2_82")))]
2194//#[doc(alias = "g_sort_array")]
2195//pub fn sort_array(array: /*Unimplemented*/&[&Basic: Pointer], element_size: usize, compare_func: /*Unimplemented*/FnMut(/*Unimplemented*/Option<Basic: Pointer>, /*Unimplemented*/Option<Basic: Pointer>) -> i32, user_data: /*Unimplemented*/Option<Basic: Pointer>) {
2196//    unsafe { TODO: call ffi:g_sort_array() }
2197//}
2198
2199/// Gets the smallest prime number from a built-in array of primes which
2200/// is larger than @num. This is used within GLib to calculate the optimum
2201/// size of a #GHashTable.
2202///
2203/// The built-in array of primes ranges from 11 to 13845163 such that
2204/// each prime is approximately 1.5-2 times the previous prime.
2205/// ## `num`
2206/// a #guint
2207///
2208/// # Returns
2209///
2210/// the smallest prime number from a built-in array of primes
2211///     which is larger than @num
2212#[doc(alias = "g_spaced_primes_closest")]
2213pub fn spaced_primes_closest(num: u32) -> u32 {
2214    unsafe { ffi::g_spaced_primes_closest(num) }
2215}
2216
2217/// Executes a child program asynchronously.
2218///
2219/// See g_spawn_async_with_pipes_and_fds() for a full description; this function
2220/// simply calls the g_spawn_async_with_pipes() without any pipes, which in turn
2221/// calls g_spawn_async_with_pipes_and_fds().
2222///
2223/// You should call g_spawn_close_pid() on the returned child process
2224/// reference when you don't need it any more.
2225///
2226/// If you are writing a GTK application, and the program you are spawning is a
2227/// graphical application too, then to ensure that the spawned program opens its
2228/// windows on the right screen, you may want to use #GdkAppLaunchContext,
2229/// #GAppLaunchContext, or set the `DISPLAY` environment variable.
2230///
2231/// Note that the returned @child_pid on Windows is a handle to the child
2232/// process and not its identifier. Process handles and process identifiers
2233/// are different concepts on Windows.
2234/// ## `working_directory`
2235/// child's current working
2236///     directory, or [`None`] to inherit parent's
2237/// ## `argv`
2238///
2239///     child's argument vector
2240/// ## `envp`
2241///
2242///     child's environment, or [`None`] to inherit parent's
2243/// ## `flags`
2244/// flags from #GSpawnFlags
2245/// ## `child_setup`
2246/// function to run
2247///     in the child just before `exec()`
2248///
2249/// # Returns
2250///
2251/// [`true`] on success, [`false`] if error is set
2252///
2253/// ## `child_pid`
2254/// return location for child process reference, or [`None`]
2255#[doc(alias = "g_spawn_async")]
2256pub fn spawn_async(
2257    working_directory: Option<impl AsRef<std::path::Path>>,
2258    argv: &[&std::path::Path],
2259    envp: &[&std::path::Path],
2260    flags: SpawnFlags,
2261    child_setup: Option<Box_<dyn FnOnce() + 'static>>,
2262) -> Result<Pid, crate::Error> {
2263    let child_setup_data: Box_<Option<Box_<dyn FnOnce() + 'static>>> = Box_::new(child_setup);
2264    unsafe extern "C" fn child_setup_func(data: ffi::gpointer) {
2265        let callback = Box_::from_raw(data as *mut Option<Box_<dyn FnOnce() + 'static>>);
2266        let callback = (*callback).expect("cannot get closure...");
2267        callback()
2268    }
2269    let child_setup = if child_setup_data.is_some() {
2270        Some(child_setup_func as _)
2271    } else {
2272        None
2273    };
2274    let super_callback0: Box_<Option<Box_<dyn FnOnce() + 'static>>> = child_setup_data;
2275    unsafe {
2276        let mut child_pid = std::mem::MaybeUninit::uninit();
2277        let mut error = std::ptr::null_mut();
2278        let is_ok = ffi::g_spawn_async(
2279            working_directory
2280                .as_ref()
2281                .map(|p| p.as_ref())
2282                .to_glib_none()
2283                .0,
2284            argv.to_glib_none().0,
2285            envp.to_glib_none().0,
2286            flags.into_glib(),
2287            child_setup,
2288            Box_::into_raw(super_callback0) as *mut _,
2289            child_pid.as_mut_ptr(),
2290            &mut error,
2291        );
2292        debug_assert_eq!(is_ok == crate::ffi::GFALSE, !error.is_null());
2293        if error.is_null() {
2294            Ok(from_glib(child_pid.assume_init()))
2295        } else {
2296            Err(from_glib_full(error))
2297        }
2298    }
2299}
2300
2301//#[cfg(feature = "v2_68")]
2302//#[cfg_attr(docsrs, doc(cfg(feature = "v2_68")))]
2303//#[doc(alias = "g_spawn_async_with_pipes_and_fds")]
2304//pub fn spawn_async_with_pipes_and_fds(working_directory: Option<impl AsRef<std::path::Path>>, argv: &[&std::path::Path], envp: &[&std::path::Path], flags: SpawnFlags, child_setup: Option<Box_<dyn FnOnce() + 'static>>, stdin_fd: i32, stdout_fd: i32, stderr_fd: i32, source_fds: &[i32], target_fds: &[i32], n_fds: usize) -> Result<(Pid, i32, i32, i32), crate::Error> {
2305//    unsafe { TODO: call ffi:g_spawn_async_with_pipes_and_fds() }
2306//}
2307
2308#[cfg_attr(feature = "v2_70", deprecated = "Since 2.70")]
2309#[allow(deprecated)]
2310#[doc(alias = "g_spawn_check_exit_status")]
2311pub fn spawn_check_exit_status(wait_status: i32) -> Result<(), crate::Error> {
2312    unsafe {
2313        let mut error = std::ptr::null_mut();
2314        let is_ok = ffi::g_spawn_check_exit_status(wait_status, &mut error);
2315        debug_assert_eq!(is_ok == crate::ffi::GFALSE, !error.is_null());
2316        if error.is_null() {
2317            Ok(())
2318        } else {
2319            Err(from_glib_full(error))
2320        }
2321    }
2322}
2323
2324#[cfg(feature = "v2_70")]
2325#[cfg_attr(docsrs, doc(cfg(feature = "v2_70")))]
2326#[doc(alias = "g_spawn_check_wait_status")]
2327pub fn spawn_check_wait_status(wait_status: i32) -> Result<(), crate::Error> {
2328    unsafe {
2329        let mut error = std::ptr::null_mut();
2330        let is_ok = ffi::g_spawn_check_wait_status(wait_status, &mut error);
2331        debug_assert_eq!(is_ok == crate::ffi::GFALSE, !error.is_null());
2332        if error.is_null() {
2333            Ok(())
2334        } else {
2335            Err(from_glib_full(error))
2336        }
2337    }
2338}
2339
2340/// A simple version of g_spawn_async() that parses a command line with
2341/// g_shell_parse_argv() and passes it to g_spawn_async().
2342///
2343/// Runs a command line in the background. Unlike g_spawn_async(), the
2344/// [`SpawnFlags::SEARCH_PATH`][crate::SpawnFlags::SEARCH_PATH] flag is enabled, other flags are not. Note
2345/// that [`SpawnFlags::SEARCH_PATH`][crate::SpawnFlags::SEARCH_PATH] can have security implications, so
2346/// consider using g_spawn_async() directly if appropriate. Possible
2347/// errors are those from g_shell_parse_argv() and g_spawn_async().
2348///
2349/// The same concerns on Windows apply as for g_spawn_command_line_sync().
2350/// ## `command_line`
2351/// a command line
2352///
2353/// # Returns
2354///
2355/// [`true`] on success, [`false`] if error is set
2356#[cfg(unix)]
2357#[cfg_attr(docsrs, doc(cfg(unix)))]
2358#[doc(alias = "g_spawn_command_line_async")]
2359pub fn spawn_command_line_async(
2360    command_line: impl AsRef<std::ffi::OsStr>,
2361) -> Result<(), crate::Error> {
2362    unsafe {
2363        let mut error = std::ptr::null_mut();
2364        let is_ok =
2365            ffi::g_spawn_command_line_async(command_line.as_ref().to_glib_none().0, &mut error);
2366        debug_assert_eq!(is_ok == crate::ffi::GFALSE, !error.is_null());
2367        if error.is_null() {
2368            Ok(())
2369        } else {
2370            Err(from_glib_full(error))
2371        }
2372    }
2373}
2374
2375//#[doc(alias = "g_spawn_command_line_sync")]
2376//pub fn spawn_command_line_sync(command_line: impl AsRef<std::path::Path>, standard_output: Vec<u8>, standard_error: Vec<u8>) -> Result<i32, crate::Error> {
2377//    unsafe { TODO: call ffi:g_spawn_command_line_sync() }
2378//}
2379
2380//#[doc(alias = "g_spawn_sync")]
2381//pub fn spawn_sync(working_directory: Option<impl AsRef<std::path::Path>>, argv: &[&std::path::Path], envp: &[&std::path::Path], flags: SpawnFlags, child_setup: Option<&mut dyn FnMut()>, standard_output: Vec<u8>, standard_error: Vec<u8>) -> Result<i32, crate::Error> {
2382//    unsafe { TODO: call ffi:g_spawn_sync() }
2383//}
2384
2385//#[doc(alias = "g_stat")]
2386//pub fn stat(filename: impl AsRef<std::path::Path>, buf: /*Ignored*/&mut StatBuf) -> i32 {
2387//    unsafe { TODO: call ffi:g_stat() }
2388//}
2389
2390//#[cfg(unix)]
2391//#[cfg_attr(docsrs, doc(cfg(unix)))]
2392//#[cfg(feature = "v2_64")]
2393//#[cfg_attr(docsrs, doc(cfg(feature = "v2_64")))]
2394//#[doc(alias = "g_unix_get_passwd_entry")]
2395//pub fn unix_get_passwd_entry(user_name: &str) -> Result</*Unimplemented*/Option<Basic: Pointer>, crate::Error> {
2396//    unsafe { TODO: call ffi:g_unix_get_passwd_entry() }
2397//}
2398
2399/// A wrapper for the POSIX unlink() function. The unlink() function
2400/// deletes a name from the filesystem. If this was the last link to the
2401/// file and no processes have it opened, the diskspace occupied by the
2402/// file is freed.
2403///
2404/// See your C library manual for more details about unlink(). Note
2405/// that on Windows, it is in general not possible to delete files that
2406/// are open to some process, or mapped into memory.
2407/// ## `filename`
2408/// a pathname in the GLib file name encoding
2409///     (UTF-8 on Windows)
2410///
2411/// # Returns
2412///
2413/// 0 if the name was successfully deleted, -1 if an error
2414///    occurred
2415#[doc(alias = "g_unlink")]
2416pub fn unlink(filename: impl AsRef<std::path::Path>) -> i32 {
2417    unsafe { ffi::g_unlink(filename.as_ref().to_glib_none().0) }
2418}
2419
2420/// Removes an environment variable from the environment.
2421///
2422/// Note that on some systems, when variables are overwritten, the
2423/// memory used for the previous variables and its value isn't reclaimed.
2424///
2425/// You should be mindful of the fact that environment variable handling
2426/// in UNIX is not thread-safe, and your program may crash if one thread
2427/// calls g_unsetenv() while another thread is calling getenv(). (And note
2428/// that many functions, such as gettext(), call getenv() internally.) This
2429/// function is only safe to use at the very start of your program, before
2430/// creating any other threads (or creating objects that create worker
2431/// threads of their own).
2432///
2433/// If you need to set up the environment for a child process, you can
2434/// use g_get_environ() to get an environment array, modify that with
2435/// g_environ_setenv() and g_environ_unsetenv(), and then pass that
2436/// array directly to execvpe(), g_spawn_async(), or the like.
2437/// ## `variable`
2438/// the environment variable to remove, must
2439///     not contain '='
2440#[doc(alias = "g_unsetenv")]
2441pub fn unsetenv(variable: impl AsRef<std::ffi::OsStr>) {
2442    unsafe {
2443        ffi::g_unsetenv(variable.as_ref().to_glib_none().0);
2444    }
2445}
2446
2447/// Pauses the current thread for the given number of microseconds.
2448///
2449/// There are 1 million microseconds per second (represented by the
2450/// `G_USEC_PER_SEC` macro). g_usleep() may have limited precision,
2451/// depending on hardware and operating system; don't rely on the exact
2452/// length of the sleep.
2453/// ## `microseconds`
2454/// number of microseconds to pause
2455#[doc(alias = "g_usleep")]
2456pub fn usleep(microseconds: libc::c_ulong) {
2457    unsafe {
2458        ffi::g_usleep(microseconds);
2459    }
2460}
2461
2462/// Parses the string @str and verify if it is a UUID.
2463///
2464/// The function accepts the following syntax:
2465///
2466/// - simple forms (e.g. `f81d4fae-7dec-11d0-a765-00a0c91e6bf6`)
2467///
2468/// Note that hyphens are required within the UUID string itself,
2469/// as per the aforementioned RFC.
2470/// ## `str`
2471/// a string representing a UUID
2472///
2473/// # Returns
2474///
2475/// [`true`] if @str is a valid UUID, [`false`] otherwise.
2476#[doc(alias = "g_uuid_string_is_valid")]
2477pub fn uuid_string_is_valid(str: &str) -> bool {
2478    unsafe { from_glib(ffi::g_uuid_string_is_valid(str.to_glib_none().0)) }
2479}
2480
2481/// Generates a random UUID (RFC 4122 version 4) as a string. It has the same
2482/// randomness guarantees as #GRand, so must not be used for cryptographic
2483/// purposes such as key generation, nonces, salts or one-time pads.
2484///
2485/// # Returns
2486///
2487/// A string that should be freed with g_free().
2488#[doc(alias = "g_uuid_string_random")]
2489pub fn uuid_string_random() -> crate::GString {
2490    unsafe { from_glib_full(ffi::g_uuid_string_random()) }
2491}