'\" t
.\"     Title: device_rename
.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: January 2017
.\"    Manual: Device drivers infrastructure
.\"    Source: Kernel Hackers Manual 4.8.15
.\"  Language: English
.\"
.TH "DEVICE_RENAME" "9" "January 2017" "Kernel Hackers Manual 4\&.8\&." "Device drivers infrastructure"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
device_rename \- renames a device
.SH "SYNOPSIS"
.HP \w'int\ device_rename('u
.BI "int device_rename(struct\ device\ *\ " "dev" ", const\ char\ *\ " "new_name" ");"
.SH "ARGUMENTS"
.PP
\fIdev\fR
.RS 4
the pointer to the struct device to be renamed
.RE
.PP
\fInew_name\fR
.RS 4
the new name of the device
.RE
.SH "DESCRIPTION"
.PP
It is the responsibility of the caller to provide mutual exclusion between two different calls of device_rename on the same device to ensure that new_name is valid and won\*(Aqt conflict with other devices\&.
.SH "NOTE"
.PP
Don\*(Aqt call this function\&. Currently, the networking layer calls this function, but that will change\&. The following text from Kay Sievers offers some insight:
.PP
Renaming devices is racy at many levels, symlinks and other stuff are not replaced atomically, and you get a
\(lqmove\(rq
uevent, but it\*(Aqs not easy to connect the event to the old and new device\&. Device nodes are not renamed at all, there isn\*(Aqt even support for that in the kernel now\&.
.PP
In the meantime, during renaming, your target name might be taken by another driver, creating conflicts\&. Or the old name is taken directly after you renamed it \-\- then you get events for the same DEVPATH, before you even see the
\(lqmove\(rq
event\&. It\*(Aqs just a mess, and nothing new should ever rely on kernel device renaming\&. Besides that, it\*(Aqs not even implemented now for other things than (driver\-core wise very simple) network devices\&.
.PP
We are currently about to change network renaming in udev to completely disallow renaming of devices in the same namespace as the kernel uses, because we can\*(Aqt solve the problems properly, that arise with swapping names of multiple interfaces without races\&. Means, renaming of eth[0\-9]* will only be allowed to some other name than eth[0\-9]*, for the aforementioned reasons\&.
.PP
Make up a
\(lqreal\(rq
name in the driver before you register anything, or add some other attributes for userspace to find the device, or use udev to add symlinks \-\- but never rename kernel devices later, it\*(Aqs a complete mess\&. We don\*(Aqt even want to get into that and try to implement the missing pieces in the core\&. We really have other pieces to fix in the driver core mess\&. :)
.SH "COPYRIGHT"
.br