diff options
Diffstat (limited to 'vendor/rustix/src/not_implemented.rs')
| -rw-r--r-- | vendor/rustix/src/not_implemented.rs | 348 |
1 files changed, 348 insertions, 0 deletions
diff --git a/vendor/rustix/src/not_implemented.rs b/vendor/rustix/src/not_implemented.rs new file mode 100644 index 00000000..e8b162a8 --- /dev/null +++ b/vendor/rustix/src/not_implemented.rs @@ -0,0 +1,348 @@ +//! Documentation about unimplemented functions. +//! +//! This module contains documentation for several functions that rustix does +//! not implement, either because they are out of scope, or because they are +//! could probably be implemented but are not yet. + +macro_rules! not_implemented { + ($func:ident) => { + /// See the [module comment](self). + pub fn $func() { + unimplemented!() + } + }; +} + +/// Memory-allocation functions are out of scope for rustix. +/// +/// It is possible to implement `malloc`, `free`, and similar functions in +/// Rust, however rustix itself is focused on syscall-like functions. This +/// module contains an incomplete list of such functions. +/// +/// There are several allocator implementations for Rust; one of them is +/// [dlmalloc]. For a rustix-based implementation, see [rustix-dlmalloc]. +/// Another allocator implementation is [talc]. +/// +/// [dlmalloc]: https://crates.io/crates/dlmalloc +/// [talc]: https://crates.io/crates/talc +/// [rustix-dlmalloc]: https://crates.io/crates/rustix-dlmalloc +pub mod memory_allocation { + not_implemented!(malloc); + not_implemented!(realloc); + not_implemented!(calloc); + not_implemented!(free); + not_implemented!(posix_memalign); + not_implemented!(aligned_alloc); + not_implemented!(malloc_usable_size); +} + +/// Functions which need access to libc internals are out of scope for rustix. +/// +/// Most Rust programs have a libc present, and when a libc is present, it +/// expects to be the only thing in the process that can do certain operations. +/// For example, there can be only one `atexit` list in a process, only one +/// `pthread_atfork` list in a process, only one implementation of pthreads in +/// a process, and so on, and libc expects to own the one of each of those +/// things. And libc implementations may expect to be involved in signal +/// handling. So, these functions are believed to be out of scope for rustix. +/// This module contains an incomplete list of such functions. +/// +/// It would be possible to make a rust library which provides safe or +/// ergonomic wrappers around these libc functions, however that is out of +/// scope for rustix itself. +/// +/// If you would like to write a Rust program which does not use a libc, and +/// which does provide APIs for some of these functions, [Eyra] and [origin] +/// are two libraries which may be useful, and which provide public interfaces +/// for some of this functionality. +/// +/// If you are otherwise writing Rust code which you know will not share a +/// process with a libc, perhaps because you are writing a libc or similar +/// yourself, rustix's codebase does include experimental implementations of +/// the primitives needed to implement most of these functions. +/// +/// [Eyra]: https://github.com/sunfishcode/eyra?tab=readme-ov-file#eyra +/// [origin]: https://github.com/sunfishcode/origin?tab=readme-ov-file#origin +pub mod libc_internals { + not_implemented!(exit); + not_implemented!(fork); + not_implemented!(clone); + not_implemented!(clone3); + not_implemented!(brk); + not_implemented!(sigaction); + not_implemented!(sigaltstack); + not_implemented!(sigprocmask); + not_implemented!(sigwait); + not_implemented!(sigwaitinfo); + not_implemented!(sigtimedwait); + not_implemented!(set_thread_area); + not_implemented!(set_tid_address); + not_implemented!(tkill); + not_implemented!(sched_setscheduler); + not_implemented!(rseq); + not_implemented!(setuid); + not_implemented!(setgid); + not_implemented!(seteuid); + not_implemented!(setegid); + not_implemented!(setreuid); + not_implemented!(setregid); + not_implemented!(setresuid); + not_implemented!(setresgid); + not_implemented!(setgroups); + + not_implemented!(pthread_atfork); + not_implemented!(pthread_attr_destroy); + not_implemented!(pthread_attr_getaffinity_np); + not_implemented!(pthread_attr_getdetachstate); + not_implemented!(pthread_attr_getguardsize); + not_implemented!(pthread_attr_getinheritsched); + not_implemented!(pthread_attr_getschedparam); + not_implemented!(pthread_attr_getschedpolicy); + not_implemented!(pthread_attr_getscope); + not_implemented!(pthread_attr_getsigmask_np); + not_implemented!(pthread_attr_getstack); + not_implemented!(pthread_attr_getstackaddr); + not_implemented!(pthread_attr_getstacksize); + not_implemented!(pthread_attr_init); + not_implemented!(pthread_attr_setaffinity_np); + not_implemented!(pthread_attr_setdetachstate); + not_implemented!(pthread_attr_setguardsize); + not_implemented!(pthread_attr_setinheritsched); + not_implemented!(pthread_attr_setschedparam); + not_implemented!(pthread_attr_setschedpolicy); + not_implemented!(pthread_attr_setscope); + not_implemented!(pthread_attr_setsigmask_np); + not_implemented!(pthread_attr_setstack); + not_implemented!(pthread_attr_setstackaddr); + not_implemented!(pthread_attr_setstacksize); + not_implemented!(pthread_barrierattr_destroy); + not_implemented!(pthread_barrierattr_getpshared); + not_implemented!(pthread_barrierattr_init); + not_implemented!(pthread_barrierattr_setpshared); + not_implemented!(pthread_barrier_destroy); + not_implemented!(pthread_barrier_wait); + not_implemented!(pthread_cancel); + not_implemented!(pthread_cleanup_pop); + not_implemented!(pthread_cleanup_pop_restore_np); + not_implemented!(pthread_cleanup_push); + not_implemented!(pthread_cleanup_push_defer_np); + not_implemented!(pthread_condattr_destroy); + not_implemented!(pthread_condattr_getclock); + not_implemented!(pthread_condattr_getpshared); + not_implemented!(pthread_condattr_init); + not_implemented!(pthread_condattr_setclock); + not_implemented!(pthread_condattr_setpshared); + not_implemented!(pthread_cond_broadcast); + not_implemented!(pthread_cond_destroy); + not_implemented!(pthread_cond_signal); + not_implemented!(pthread_cond_timedwait); + not_implemented!(pthread_create); + not_implemented!(pthread_detach); + not_implemented!(pthread_equal); + not_implemented!(pthread_exit); + not_implemented!(pthread_getaffinity_np); + not_implemented!(pthread_getattr_default_np); + not_implemented!(pthread_getattr_np); + not_implemented!(pthread_getconcurrency); + not_implemented!(pthread_getcpuclockid); + not_implemented!(pthread_getname_np); + not_implemented!(pthread_getschedparam); + not_implemented!(pthread_getspecific); + not_implemented!(pthread_join); + not_implemented!(pthread_key_create); + not_implemented!(pthread_key_delete); + not_implemented!(pthread_kill); + not_implemented!(pthread_kill_other_threads_np); + not_implemented!(pthread_mutexattr_destroy); + not_implemented!(pthread_mutexattr_getprioceiling); + not_implemented!(pthread_mutexattr_getprotocol); + not_implemented!(pthread_mutexattr_getpshared); + not_implemented!(pthread_mutexattr_getrobust); + not_implemented!(pthread_mutexattr_getrobust_np); + not_implemented!(pthread_mutexattr_gettype); + not_implemented!(pthread_mutexattr_init); + not_implemented!(pthread_mutexattr_setprioceiling); + not_implemented!(pthread_mutexattr_setprotocol); + not_implemented!(pthread_mutexattr_setpshared); + not_implemented!(pthread_mutexattr_setrobust); + not_implemented!(pthread_mutexattr_setrobust_np); + not_implemented!(pthread_mutexattr_settype); + not_implemented!(pthread_mutex_consistent); + not_implemented!(pthread_mutex_consistent_np); + not_implemented!(pthread_mutex_destroy); + not_implemented!(pthread_mutex_getprioceiling); + not_implemented!(pthread_mutex_init); + not_implemented!(pthread_mutex_lock); + not_implemented!(pthread_mutex_setprioceiling); + not_implemented!(pthread_mutex_timedlock); + not_implemented!(pthread_mutex_trylock); + not_implemented!(pthread_once); + not_implemented!(pthread_rwlockattr_destroy); + not_implemented!(pthread_rwlockattr_getkind_np); + not_implemented!(pthread_rwlockattr_getpshared); + not_implemented!(pthread_rwlockattr_init); + not_implemented!(pthread_rwlockattr_setkind_np); + not_implemented!(pthread_rwlockattr_setpshared); + not_implemented!(pthread_rwlock_destroy); + not_implemented!(pthread_rwlock_rdlock); + not_implemented!(pthread_rwlock_timedrdlock); + not_implemented!(pthread_rwlock_timedwrlock); + not_implemented!(pthread_rwlock_tryrdlock); + not_implemented!(pthread_rwlock_trywrlock); + not_implemented!(pthread_rwlock_unlock); + not_implemented!(pthread_rwlock_wrlock); + not_implemented!(pthread_self); + not_implemented!(pthread_setaffinity_np); + not_implemented!(pthread_setattr_default_np); + not_implemented!(pthread_setcancelstate); + not_implemented!(pthread_setcanceltype); + not_implemented!(pthread_setconcurrency); + not_implemented!(pthread_setname_np); + not_implemented!(pthread_setschedparam); + not_implemented!(pthread_setschedprio); + not_implemented!(pthread_setspecific); + not_implemented!(pthread_sigmask); + not_implemented!(pthread_sigqueue); + not_implemented!(pthread_spin_destroy); + not_implemented!(pthread_spin_init); + not_implemented!(pthread_spin_lock); + not_implemented!(pthread_spin_trylock); + not_implemented!(pthread_spin_unlock); + not_implemented!(pthread_testcancel); + not_implemented!(pthread_timedjoin_np); + not_implemented!(pthread_tryjoin_np); + not_implemented!(pthread_yield); +} + +/// Functions which provide higher-level functionality are out of scope for +/// rustix. +/// +/// These functions are provided by typical libc implementations, but are +/// higher-level than the simple syscall-like functions that rustix focuses on. +/// They could be implemented as a separate library built on top of rustix, +/// rather than being part of rustix itself. This module contains an incomplete +/// list of such functions. +pub mod higher_level { + not_implemented!(getpwent); + not_implemented!(getpwuid); + not_implemented!(getpwnam); + not_implemented!(getpwuid_r); + not_implemented!(getpwnam_r); + not_implemented!(gethostbyname); + not_implemented!(execv); + not_implemented!(execvp); + not_implemented!(execvpe); + not_implemented!(wordexp); + not_implemented!(localtime); + not_implemented!(localtime_r); + not_implemented!(gmtime); + not_implemented!(gmtime_r); + not_implemented!(ctime); + not_implemented!(ctime_r); + not_implemented!(asctime); + not_implemented!(asctime_r); + not_implemented!(mktime); + not_implemented!(getifaddrs); + + /// See [rustix-openpty](https://crates.io/crates/rustix-openpty). + pub fn closefrom() { + unimplemented!() + } + /// See [rustix-openpty](https://crates.io/crates/rustix-openpty). + pub fn login_tty() { + unimplemented!() + } + /// See [rustix-openpty](https://crates.io/crates/rustix-openpty). + pub fn openpty() { + unimplemented!() + } + + /// See [`std::io::IsTerminal`]. + /// + /// For Rust < 1.70, see [is-terminal]. For a rustix-based implementation, + /// see [rustix-is-terminal]. + /// + /// [`std::io::IsTerminal`]: std::io::IsTerminal + /// [is-terminal]: https://crates.io/crates/is-terminal + /// [rustix-is-terminal]: https://crates.io/crates/rustix-is-terminal + pub fn isatty() { + unimplemented!() + } +} + +/// Functions which don't seem possible to even call from Rust with current +/// language features, even with `unsafe`. +pub mod impossible { + not_implemented!(vfork); + not_implemented!(sigreturn); + not_implemented!(setjmp); + not_implemented!(longjmp); + not_implemented!(sigsetjmp); + not_implemented!(siglongjmp); +} + +/// These functions are not yet implemented in rustix, but probably could be. +/// +/// These are functions that users have asked about, and which probably are in +/// scope for rustix, but are not yet implemented. This module contains an +/// incomplete list of such functions. +pub mod yet { + not_implemented!(tgkill); + not_implemented!(raise); + not_implemented!(sysctl); + not_implemented!(mq_open); + not_implemented!(mq_send); + not_implemented!(mq_unlink); + not_implemented!(recvmmsg); + not_implemented!(cachestat); + not_implemented!(fanotify_init); + not_implemented!(fanotify_mark); + not_implemented!(getifaddrs); + not_implemented!(signalfd); + not_implemented!(mount_setattr); + not_implemented!(extattr_delete_fd); + not_implemented!(extattr_delete_link); + not_implemented!(extattr_get_fd); + not_implemented!(extattr_get_link); + not_implemented!(extattr_list_fd); + not_implemented!(extattr_list_link); + not_implemented!(extattr_set_fd); + not_implemented!(extattr_set_link); + not_implemented!(get_mempolicy); + not_implemented!(mbind); + not_implemented!(set_mempolicy); + not_implemented!(migrate_pages); + not_implemented!(move_pages); + not_implemented!(fchmodat2); + not_implemented!(shmat); + not_implemented!(shmdt); + not_implemented!(shmget); + not_implemented!(shmctl); +} + +/// These functions are not quite yet finished in rustix. +/// +/// Rustix's codebase includes experimental implementations of these functions, +/// however they are not yet publicly exposed because their API might need more +/// work and/or they don't yet have a libc backend implementation yet. +/// +/// See [#1314] for more information, and please leave comments if there are +/// specific functions you're interested in. +/// +/// [#1314]: https://github.com/bytecodealliance/rustix/issues/1314 +pub mod quite_yet { + not_implemented!(_exit); + not_implemented!(_Exit); + not_implemented!(exit_group); + not_implemented!(sigpending); + not_implemented!(sigsuspend); + not_implemented!(execveat); + not_implemented!(execve); + + /// For now, use `rustix::process::uname().nodename()` instead. + /// + /// See also the [module comment](self). + pub fn gethostname() { + unimplemented!() + } +} |