pathname.h File Reference

(37a72b0150ec36b4ea27175039afc28c62207b0c)

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"

Include dependency graph for pathname.h:

This graph shows which files directly or indirectly include this file:

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. More...
char *	rb_enc_path_skip_prefix (const char *path, const char *end, rb_encoding *enc)
	Seeks for non-prefix part of a pathname. More...
char *	rb_enc_path_last_separator (const char *path, const char *end, rb_encoding *enc)
	Returns the last path component. More...
char *	rb_enc_path_end (const char *path, const char *end, rb_encoding *enc)
	This just returns the passed end basically. More...
const char *	ruby_enc_find_basename (const char *name, long *baselen, long *alllen, rb_encoding *enc)
	Our own encoding-aware version of basename(3). More...
const char *	ruby_enc_find_extname (const char *name, long *len, rb_encoding *enc)
	Our own encoding-aware version of extname. More...

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.

Referenced by ruby_init_loadpath().

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.

Referenced by rb_enc_path_skip_prefix().

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.
}

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 4982 of file file.c.