Ruby: include/ruby/internal/encoding/pathname.h File Reference

Ruby 3.4.6p54 (2025-09-16 revision dbd83256b1cec76c69756ecb8758b9e1079833de)

Functions
pathname.h File Reference

Routines to manipulate encodings of pathnames. More...

`#include "ruby/internal/attr/nonnull.h"`
`#include "ruby/internal/dllexport.h"`
`#include "ruby/internal/encoding/encoding.h"`
`#include "ruby/internal/value.h"`

Go to the source code of this file.

## Functions
char * | rb_enc_path_next (const char *path, const char *end, rb_encoding *enc)
| Returns a path component directly adjacent to the passed pointer.
char * | rb_enc_path_skip_prefix (const char *path, const char *end, rb_encoding *enc)
| Seeks for non-prefix part of a pathname.
char * | rb_enc_path_last_separator (const char *path, const char *end, rb_encoding *enc)
| Returns the last path component.
char * | rb_enc_path_end (const char *path, const char *end, rb_encoding *enc)
| This just returns the passed end basically.
const char * | ruby_enc_find_basename (const char *name, long *baselen, long *alllen, rb_encoding *enc)
| Our own encoding-aware version of basename(3).
const char * | ruby_enc_find_extname (const char *name, long *len, rb_encoding *enc)
| Our own encoding-aware version of extname.

## Detailed Description

Routines to manipulate encodings of pathnames.

Author
  Ruby developers ruby-.nosp@m.core.nosp@m.@ruby.nosp@m.-lan.nosp@m.g.org

Copyright
  This file is a part of the programming language Ruby. Permission is hereby granted, to either redistribute and/or modify this file, provided that the conditions mentioned in the file COPYING are met. Consult the file for details.

Warning
  Symbols prefixed with either RBIMPL or rbimpl are implementation details. Don't take them as canon. They could rapidly appear then vanish. The name (path) of this header file is also an implementation detail. Do not expect it to persist at the place it is now. Developers are free to move it anywhere anytime at will.

Note
  To ruby-core: remember that this header can be possibly recursively included from extension libraries written in C++. Do not expect for instance __VA_ARGS__ is always available. We assume C99 for ruby itself but we don't assume languages of extension libraries. They could be written in C++98.

Definition in file pathname.h.

## Function Documentation

## ◆ rb_enc_path_end()

char * rb_enc_path_end | ( | const char * | path,
|  | const char * | end,
|  | rb_encoding * | enc )

This just returns the passed end basically.

It makes difference in case the passed string ends with tons of path separators like the following:

"/path/that/ends/with/lots/of/slashes//////////////"
^ ^ ^
| | +--- end
| +--- @return
+--- path

Parameters

  [in] | path | Where to start scanning.
  [in] | end | End of the path string.
  [in] | enc | Encoding of the string.

Returns
  A pointer in the passed string where the trailing path separators start, or end if there is no trailing path separators.

Definition at line 3594 of file file.c.

## ◆ rb_enc_path_last_separator()

char * rb_enc_path_last_separator | ( | const char * | path,
|  | const char * | end,
|  | rb_encoding * | enc )

Returns the last path component.

"/multi/byte/encoded/pathname.txt"
^ ^ ^
| | +--- end
| +--- @return
+--- path

Parameters

  [in] | path | Where to start scanning.
  [in] | end | End of the path string.
  [in] | enc | Encoding of the string.

Returns
  A pointer in the passed string where the last path component resides, or end if there is no more path component.

Definition at line 3560 of file file.c.

## ◆ rb_enc_path_next()

char * rb_enc_path_next | ( | const char * | path,
|  | const char * | end,
|  | rb_encoding * | enc )

Returns a path component directly adjacent to the passed pointer.

"/multi/byte/encoded/pathname.txt"
^ ^ ^
| | +--- end
| +--- @return
+--- path

Parameters

  [in] | path | Where to start scanning.
  [in] | end | End of the path string.
  [in] | enc | Encoding of the string.

Returns
  A pointer in the passed string where the next path component resides, or end if there is no next path component.

Definition at line 3512 of file file.c.

## ◆ rb_enc_path_skip_prefix()

char * rb_enc_path_skip_prefix | ( | const char * | path,
|  | const char * | end,
|  | rb_encoding * | enc )

Seeks for non-prefix part of a pathname.

This can be a no-op when the OS has no such concept like a path prefix. But there are OSes where path prefixes do exist.

"C:\multi\byte\encoded\pathname.txt"
^ ^ ^
| | +--- end
| +--- @return
+--- path

Parameters

  [in] | path | Where to start scanning.
  [in] | end | End of the path string.
  [in] | enc | Encoding of the string.

Returns
  A pointer in the passed string where non-prefix part starts, or path if the OS does not have path prefix.

Definition at line 3526 of file file.c.

## ◆ ruby_enc_find_basename()

const char * ruby_enc_find_basename | ( | const char * | name,
|  | long * | baselen,
|  | long * | alllen,
|  | rb_encoding * | enc )

Our own encoding-aware version of basename(3).

Normally, this function returns the last path component of the given name. However in case the passed name ends with a path separator, it returns the name of the directory, not the last (empty) component. Also if the passed name is a root directory, it returns that root directory. Note however that Windows filesystem have drive letters, which this function does not return.

Parameters

  [in] | name | Target path.
  [out] | baselen | Return buffer.
  [in,out] | alllen | Number of bytes of name.
  | [enc] | enc Encoding of name.

Returns
  The rightmost component of name.

Postcondition
  baselen, if passed, is updated to be the number of bytes of the returned basename.
  alllen, if passed, is updated to be the number of bytes of strings not considered as the basename.

Definition at line 4735 of file file.c.

## ◆ ruby_enc_find_extname()

const char * ruby_enc_find_extname | ( | const char * | name,
|  | long * | len,
|  | rb_encoding * | enc )

Our own encoding-aware version of extname.

This function first applies rb_enc_path_last_separator() to the passed name and only concerns its return value (ignores any parent directories). This function returns complicated results:

auto path = "...";
auto len = strlen(path);
auto ret = ruby_enc_find_extname(path, &len, rb_ascii8bit_encoding());
switch(len) {
case 0:
if (ret == 0) {
// `path` is a file without extensions.
}
else {
// `path` is a dotfile.
// `ret` is the file's name.
}
break;
case 1:
// `path` _ends_ with a dot.
// `ret` is that dot.
break;
default:
// `path` has an extension.
// `ret` is that extension.
}
rb_ascii8bit_encoding
rb_encoding * rb_ascii8bit_encoding(void)
Queries the encoding that represents ASCII-8BIT a.k.a.
Definition encoding.c:1463
len
int len
Length of the buffer.
Definition io.h:8
ruby_enc_find_extname
const char * ruby_enc_find_extname(const char *name, long *len, rb_encoding *enc)
Our own encoding-aware version of extname.
Definition file.c:4985

Parameters

  [in] | name | Target path.
  [in,out] | len | Number of bytes of name.
  [in] | enc | Encoding of name.

Returns
  See above.

Postcondition
  len, if passed, is updated (see above).

Definition at line 4985 of file file.c.