Linux Core-Api Documentation
Total Page:16
File Type:pdf, Size:1020Kb
Linux Core-api Documentation The kernel development community Jul 14, 2020 CONTENTS i ii Linux Core-api Documentation This is the beginning of a manual for core kernel APIs. The conversion (and writ- ing!) of documents for this manual is much appreciated! CONTENTS 1 Linux Core-api Documentation 2 CONTENTS CHAPTER ONE CORE UTILITIES This section has general and “core core”documentation. The first is a massive grab-bag of kerneldoc info left over from the docbook days; it should really be broken up someday when somebody finds the energy to do it. 1.1 The Linux Kernel API 1.1.1 List Management Functions void INIT_LIST_HEAD(struct list_head * list) Initialize a list_head structure Parameters struct list_head * list list_head structure to be initialized. Description Initializes the list_head to point to itself. If it is a list header, the result is an empty list. void list_add(struct list_head * new, struct list_head * head) add a new entry Parameters struct list_head * new new entry to be added struct list_head * head list head to add it after Description Insert a new entry after the specified head. This is good for implementing stacks. void list_add_tail(struct list_head * new, struct list_head * head) add a new entry Parameters struct list_head * new new entry to be added struct list_head * head list head to add it before Description 3 Linux Core-api Documentation Insert a new entry before the specified head. This is useful for implementing queues. void list_del(struct list_head * entry) deletes entry from list. Parameters struct list_head * entry the element to delete from the list. Note list_empty() on entry does not return true after this, the entry is in an undefined state. void list_replace(struct list_head * old, struct list_head * new) replace old entry by new one Parameters struct list_head * old the element to be replaced struct list_head * new the new element to insert Description If old was empty, it will be overwritten. void list_replace_init(struct list_head * old, struct list_head * new) replace old entry by new one and initialize the old one Parameters struct list_head * old the element to be replaced struct list_head * new the new element to insert Description If old was empty, it will be overwritten. void list_swap(struct list_head * entry1, struct list_head * entry2) replace entry1 with entry2 and re-add entry1 at entry2’s position Parameters struct list_head * entry1 the location to place entry2 struct list_head * entry2 the location to place entry1 void list_del_init(struct list_head * entry) deletes entry from list and reinitialize it. Parameters struct list_head * entry the element to delete from the list. void list_move(struct list_head * list, struct list_head * head) delete from one list and add as another’s head Parameters struct list_head * list the entry to move struct list_head * head the head that will precede our entry 4 Chapter 1. Core utilities Linux Core-api Documentation void list_move_tail(struct list_head * list, struct list_head * head) delete from one list and add as another’s tail Parameters struct list_head * list the entry to move struct list_head * head the head that will follow our entry void list_bulk_move_tail(struct list_head * head, struct list_head * first, struct list_head * last) move a subsection of a list to its tail Parameters struct list_head * head the head that will follow our entry struct list_head * first first entry to move struct list_head * last last entry to move, can be the same as first Description Move all entries between first and including last before head. All three entries must belong to the same linked list. int list_is_first(const struct list_head * list, const struct list_head * head) • tests whether list is the first entry in list head Parameters const struct list_head * list the entry to test const struct list_head * head the head of the list int list_is_last(const struct list_head * list, const struct list_head * head) tests whether list is the last entry in list head Parameters const struct list_head * list the entry to test const struct list_head * head the head of the list int list_empty(const struct list_head * head) tests whether a list is empty Parameters const struct list_head * head the list to test. int list_empty_careful(const struct list_head * head) tests whether a list is empty and not being modified Parameters const struct list_head * head the list to test Description tests whether a list is empty _and_ checks that no other CPU might be in the pro- cess of modifying either member (next or prev) NOTE 1.1. The Linux Kernel API 5 Linux Core-api Documentation using list_empty_careful() without synchronization can only be safe if the only activity that can happen to the list entry is list_del_init(). Eg. it cannot be used if another CPU could re-list_add() it. void list_rotate_left(struct list_head * head) rotate the list to the left Parameters struct list_head * head the head of the list void list_rotate_to_front(struct list_head * list, struct list_head * head) Rotate list to specific item. Parameters struct list_head * list The desired new front of the list. struct list_head * head The head of the list. Description Rotates list so that list becomes the new front of the list. int list_is_singular(const struct list_head * head) tests whether a list has just one entry. Parameters const struct list_head * head the list to test. void list_cut_position(struct list_head * list, struct list_head * head, struct list_head * entry) cut a list into two Parameters struct list_head * list a new list to add all removed entries struct list_head * head a list with entries struct list_head * entry an entry within head, could be the head itself and if so we won’t cut the list Description This helper moves the initial part of head, up to and including entry, from head to list. You should pass on entry an element you know is on head. list should be an empty list or a list you do not care about losing its data. void list_cut_before(struct list_head * list, struct list_head * head, struct list_head * entry) cut a list into two, before given entry Parameters struct list_head * list a new list to add all removed entries struct list_head * head a list with entries struct list_head * entry an entry within head, could be the head itself Description 6 Chapter 1. Core utilities Linux Core-api Documentation This helper moves the initial part of head, up to but excluding entry, from head to list. You should pass in entry an element you know is on head. list should be an empty list or a list you do not care about losing its data. If entry == head, all entries on head are moved to list. void list_splice(const struct list_head * list, struct list_head * head) join two lists, this is designed for stacks Parameters const struct list_head * list the new list to add. struct list_head * head the place to add it in the first list. void list_splice_tail(struct list_head * list, struct list_head * head) join two lists, each list being a queue Parameters struct list_head * list the new list to add. struct list_head * head the place to add it in the first list. void list_splice_init(struct list_head * list, struct list_head * head) join two lists and reinitialise the emptied list. Parameters struct list_head * list the new list to add. struct list_head * head the place to add it in the first list. Description The list at list is reinitialised void list_splice_tail_init(struct list_head * list, struct list_head * head) join two lists and reinitialise the emptied list Parameters struct list_head * list the new list to add. struct list_head * head the place to add it in the first list. Description Each of the lists is a queue. The list at list is reinitialised list_entry(ptr, type, member) get the struct for this entry Parameters ptr the struct list_head pointer. type the type of the struct this is embedded in. member the name of the list_head within the struct. list_first_entry(ptr, type, member) get the first element from a list Parameters 1.1. The Linux Kernel API 7 Linux Core-api Documentation ptr the list head to take the element from. type the type of the struct this is embedded in. member the name of the list_head within the struct. Description Note, that list is expected to be not empty. list_last_entry(ptr, type, member) get the last element from a list Parameters ptr the list head to take the element from. type the type of the struct this is embedded in. member the name of the list_head within the struct. Description Note, that list is expected to be not empty. list_first_entry_or_null(ptr, type, member) get the first element from a list Parameters ptr the list head to take the element from. type the type of the struct this is embedded in. member the name of the list_head within the struct. Description Note that if the list is empty, it returns NULL. list_next_entry(pos, member) get the next element in list Parameters pos the type * to cursor member the name of the list_head within the struct. list_prev_entry(pos, member) get the prev element in list Parameters pos the type * to cursor member the name of the list_head within the struct. list_for_each(pos, head) iterate over a list Parameters pos the struct list_head to use as a loop cursor. head the head for your list. 8 Chapter 1. Core utilities Linux Core-api Documentation list_for_each_continue(pos, head) continue iteration over a list Parameters pos the struct list_head to use as a loop cursor. head the head for your list. Description Continue to iterate over a list, continuing after the current position. list_for_each_prev(pos, head) iterate over a list backwards Parameters pos the struct list_head to use as a loop cursor. head the head for your list. list_for_each_safe(pos, n, head) iterate over a list safe against removal of list entry Parameters pos the struct list_head to use as a loop cursor.